Re: "box" type description

At Mon, 29 Mar 2021 22:44:29 +0200, Christoph Berg <myon(at)debian(dot)org> wrote in
> I believe the "box" type description is slightly incorrect:
>
> # \dT box
> Liste der Datentypen
> Schema │ Name │ Beschreibung
> ────────────┼──────┼──────────────────────────────────────────
> pg_catalog │ box │ geometric box '(lower left,upper right)'
>
> While the syntax '((3,4),(1,2))'::box works, the canonical spelling is
> '(3,4),(1,2)' and hence the description should be:
> geometric box '(lower left),(upper right)'

Maybe the reason you think so is that a box is printed in that format.

postgres=# select '((1,1),(2,2))'::box;
box
-------------
(2,2),(1,1)
(1 row)

It doesn't use the word "canonical", but the documentation is saying
that it is the output format. So I think you're right in that point.

https://www.postgresql.org/docs/13/datatype-geometric.html

Table 8.20. Geometric Types

point 16 bytes Point on a plane (x,y)
line 32 bytes Infinite line {A,B,C}
lseg 32 bytes Finite line segment ((x1,y1),(x2,y2))
box 32 bytes Rectangular box ((x1,y1),(x2,y2))
path 16+16n bytes Closed path (similar to polygon) ((x1,y1),...)
path 16+16n bytes Open path [(x1,y1),...]
polygon 40+16n bytes Polygon (similar to closed path) ((x1,y1),...)
circle 24 bytes Circle <(x,y),r> (center point and radius)

Similary, lseg seems inconsistent... (It is correctly described in
later sections.)

select '(1,1),(2,2)'::lseg; => [(1,1),(2,2)]

Surely it would be better that the documentation is consistent with
the output function. Perhaps we prefer to fix documentation rather
than to fix implementation to give impacts on applications that may
exist. (I don't like the notation since the representation of box
doesn't look like one object, though..)

Returing to the description of pg_types, it should be changed like
this following the discussion here.

- pg_catalog | box | geometric box '(lower left,upper right)'
+ pg_catalog | box | geometric box 'lower left,upper right'

But I find it hard to read. I fixed it instead as the following in the
attached. However, it might rather be better not changing it..

+ pg_catalog | box | geometric box 'pt-lower-left,pt-upper-right'

I added a space after commas, since point has it and (I think) it is
easier to read having the ones.

Is there any opinions?

regards.

--
Kyotaro Horiguchi
NTT Open Source Software Center