Re: "box" type description - Mailing list pgsql-hackers

At Mon, 29 Mar 2021 22:44:29 +0200, Christoph Berg <myon@debian.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
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 7c341c8e3f..e118a689c8 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -3264,13 +3264,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
         <entry><type>lseg</type></entry>
         <entry>32 bytes</entry>
         <entry>Finite line segment</entry>
-        <entry>((x1,y1),(x2,y2))</entry>
+        <entry>[(x1,y1),(x2,y2)]</entry>
        </row>
        <row>
         <entry><type>box</type></entry>
         <entry>32 bytes</entry>
         <entry>Rectangular box</entry>
-        <entry>((x1,y1),(x2,y2))</entry>
+        <entry>(x1,y1),(x2,y2)</entry>
        </row>
        <row>
         <entry><type>path</type></entry>
diff --git a/src/include/catalog/pg_type.dat b/src/include/catalog/pg_type.dat
index 8c145c00be..42adc184d7 100644
--- a/src/include/catalog/pg_type.dat
+++ b/src/include/catalog/pg_type.dat
@@ -185,24 +185,24 @@
   typinput => 'point_in', typoutput => 'point_out', typreceive => 'point_recv',
   typsend => 'point_send', typalign => 'd' },
 { oid => '601', array_type_oid => '1018',
-  descr => 'geometric line segment \'(pt1,pt2)\'',
+  descr => 'geometric line segment \'[pt1, pt2]\'',
   typname => 'lseg', typlen => '32', typbyval => 'f', typcategory => 'G',
   typsubscript => 'raw_array_subscript_handler', typelem => 'point',
   typinput => 'lseg_in', typoutput => 'lseg_out', typreceive => 'lseg_recv',
   typsend => 'lseg_send', typalign => 'd' },
 { oid => '602', array_type_oid => '1019',
-  descr => 'geometric path \'(pt1,...)\'',
+  descr => 'geometric path \'(pt1, ...)\'',
   typname => 'path', typlen => '-1', typbyval => 'f', typcategory => 'G',
   typinput => 'path_in', typoutput => 'path_out', typreceive => 'path_recv',
   typsend => 'path_send', typalign => 'd', typstorage => 'x' },
 { oid => '603', array_type_oid => '1020',
-  descr => 'geometric box \'(lower left,upper right)\'',
+  descr => 'geometric box \'pt-lower-left, pt-upper-right\'',
   typname => 'box', typlen => '32', typbyval => 'f', typcategory => 'G',
   typdelim => ';', typsubscript => 'raw_array_subscript_handler',
   typelem => 'point', typinput => 'box_in', typoutput => 'box_out',
   typreceive => 'box_recv', typsend => 'box_send', typalign => 'd' },
 { oid => '604', array_type_oid => '1027',
-  descr => 'geometric polygon \'(pt1,...)\'',
+  descr => 'geometric polygon \'(pt1, ...)\'',
   typname => 'polygon', typlen => '-1', typbyval => 'f', typcategory => 'G',
   typinput => 'poly_in', typoutput => 'poly_out', typreceive => 'poly_recv',
   typsend => 'poly_send', typalign => 'd', typstorage => 'x' },