To: pgsql-docs@lists.postgresql.org
From: Anton Voloshin <a.voloshin@postgrespro.ru>
Subject: operator @@ is not supported by path; doc says otherwise
Message-ID: <5405b243-4523-266e-6139-ad9f80a9d9fc@postgrespro.ru>
Date: Mon, 6 Dec 2021 23:46:16 +0700
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.14.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 8bit
Archived-At: 
 <https://www.postgresql.org/message-id/5405b243-4523-266e-6139-ad9f80a9d9fc%40postgrespro.ru>
Precedence: bulk

Hello,

The documentation for 13 and 14 says in "Geometric Functions and
Operators" https://www.postgresql.org/docs/14/functions-geometry.html:

 > @@ geometric_type → point
 > Computes the center point. Available for box, lseg, path, polygon,
circle.
 > @@ box '(2,2),(0,0)' → (1,1)

However, apparently, this operator does not work for path:

 > $ psql
 > psql (14.1)
 > Type "help" for help.
 >
 > postgres=# SELECT @@ path '[(0,0),(0,1)]';
 > ERROR:  function "path_center" not implemented
 > postgres=#

Same for a closed path:
 > postgres=# SELECT @@ path '((0,0),(0,1))';
 > ERROR:  function "path_center" not implemented

Quick tests show that other types listed (box, lseg, polygon, circle) 
are supported, so only the path is extra.

This sentence in the documentation came from 791090bd775b (REL_13_STABLE 
and later). What slightly confuses me is that path_center has been 
listed in src/include/catalog/pg_operator.dat and pg_proc.dat (and 
pg_operator.h/pg_proc.h before that) since 3c2d74d2a (1997!), but since 
a3d284485 (2018) we have a regression test ensuring that "function 
"path_center" not implemented".

The easiest fix is, obviously, removing 'path' from the list in the 
documentation. Or, if that would be an actual improvement, I could 
submit a patch to support a path_center as well. Not sure if there is 
any actual need for that, though: I found this by just goofing around, 
not because I actually needed to calculate the center for some path. 
Also, converting to polygon might be a workaround for those who might 
need that feature. Please let me know if implementing path_center would 
be a useful addition.

P.S. I've sent a report though a submit web form on a documentation web 
site two days ago, but, apparently, that email was not delivered to this 
list.

Anton Voloshin
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru