[postgis-devel] Noob questions about aliases and undocumented functions

[Regina Obe]

In theory they should be documented.  In practice I've told people to not
use those and just stick with 

 

ST_GeomFromText and ST_GeomFromWKB.

 

The reason as I recall is that those functions are pretty much the above but
with a CASE WHEN wrapper, which makes them much slower than the above.  The
only reason I can think why people would ever want to use them is if they
have a mixed bag of geometries and say only want a polygon and have NULLs
returned for others.  Even then they'd probably be better off by just using
the ST_GeomFromText / ST_GeomFromWKB and filtering out the nulls.

 

I've always felt it's just more confusing to document, what I consider
useless functions that are just there to satisfy the specs.  Do others have
an opinion on this?

 

Thanks,

Regina

 

From: postgis-devel [mailto:postgis-devel-bounces at lists.osgeo.org] On Behalf
Of Juris Evertovskis
Sent: Saturday, June 18, 2022 10:38 AM
To: postgis-devel at lists.osgeo.org
Subject: [postgis-devel] Noob questions about aliases and undocumented
functions

 

Hi all, newbie here.

 

I was going through the OpenGIS SFA spec and discovered some functions that
are in the spec and implemented in PostGIS, but not documented in PostGIS
docs. Before submitting any pull requests I wanted to check if these things
are not intentionally undocumented (e.g. semi-deprecated).

 

Namely these are some aliases like ST_PolyFromText is implemented, but not
documented. However, ST_PolygonFromText is documented, which seems to be
implemented as an alias to ST_PolyFromText. Also a bunch of *FromWKB
function, e.g. ST_PolygonFromWKB, ST_MLineFromWKB, ST_MPolyFromWKB. I
noticed that these are listed in RFC03 as "PUBLIC KEEP" and thus they were
intended to be documented and are mentioned in some older reference (
https://postgis.net/docs/manual-1.3/ch06.html ), but I can't find the status
of that RFC and it's from 2009 so the status of these functions might have
changed since then anyways.

 

So could you give me a little guidance and tell if these functions should be
documented?

 

--

 

One other detail that got me confused was the use of aliases in
implementations. I was looking at these sources
https://github.com/postgis/postgis/blob/master/postgis/postgis.sql.in so
please tell me if it's the wrong file for implementations :) But my question
is whether it is encouraged to use aliases or to NOT use aliases?

 

I am asking this because some functions like the aforementioned
ST_PolygonFromText seem to be a straight up alias of ST_PolyFromText
https://github.com/postgis/postgis/blob/master/postgis/postgis.sql.in#L5513

However ST_PolyFromWKB and ST_PolygonFromWKB appear to have identical
implementations without referring to one another.

Which way is preferred? Or am I missing some detail?

 

Regards,

Juris

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20220618/fb874984/attachment.htm>