Move over ST_GeometryType, ST_MakePolygon

git-svn-id: http://svn.osgeo.org/postgis/trunk@2871 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/doc/reference.xml b/doc/reference.xml
index 7fb8db45ea61e55f9e9b04c35970c9e72d009de8..70350f400ff81a0840246aa1397b6e005a6aa835 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -637,18 +637,6 @@ GROUP BY gid, field1,field2;
           </listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term>ST_GeometryType(geometry)</term>
-
-          <listitem>
-            <para>Returns the type of the geometry as a string. EG:
-            'ST_Linestring', 'ST_Polygon','ST_MultiPolygon' etc. This function differs from
-            GeometryType(geometry) in the case of the string and ST in front that is returned,
-            as well as the fact that it will not indicate whether the geometry
-            is measured.</para>
-          </listitem>
-        </varlistentry>
-
         <varlistentry>
           <term>ST_X(geometry)</term>
 
@@ -1589,89 +1577,6 @@ GROUP BY gid, field1,field2;
           </listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term>ST_MakePolygon(linestring geometry)</term>
-
-          <listitem>
-            <para>Creates a Polygon formed by the given shell. Input
-            geometries must be closed LINESTRINGS (see <link
-            linkend="IsClosed">ST_IsClosed</link> and <link
-            linkend="GeometryType">ST_GeometryType</link>). This function will
-            not accept a MULTILINESTRING.</para>
-
-            <programlisting>
-SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'));
---If linestring is not closed
---you can add the start point to close it
-SELECT ST_MakePolygon(ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)))
-FROM (
-SELECT ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5)') As open_line) As foo
-                         </programlisting>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term>ST_MakePolygon(linestring geometry, linestrings
-          geometry[])</term>
-
-          <listitem>
-            <para>Creates a Polygon formed by the given shell and array of
-            holes. You can construct a geometry array using <link
-            linkend="Accum">ST_Accum</link> or the PostgreSQL ARRAY[] and
-            ARRAY() constructs. Input geometries must be closed LINESTRINGS
-            (see <link linkend="IsClosed">ST_IsClosed</link> and <link
-            linkend="GeometryType">ST_GeometryType</link>).</para>
-
-            <programlisting>
---Build a donut with an ant hole
-SELECT ST_MakePolygon(
-               ST_ExteriorRing(ST_Buffer(foo.line,10)),
-       ARRAY[ST_Translate(foo.line,1,1),
-               ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ]
-       )
-FROM 
-       (SELECT ST_ExteriorRing(ST_Buffer(ST_MakePoint(10,10),10,10))
-               As line )
-               As foo;
-               
---Build province boundaries with holes
---representing lakes in the province from a set of 
---province polygons/multipolygons and water line strings
---this is an example of using PostGIS ST_Accum
---NOTE: the use of CASE because feeding a null array into 
---ST_MakePolygon results in NULL
---NOTE: the use of left join to guarantee we get all provinces back even if they have no lakes
-SELECT p.gid, p.province_name, 
-       CASE WHEN
-               ST_Accum(w.the_geom) IS NULL THEN p.the_geom
-       ELSE  ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), ST_Accum(w.the_geom)) END
-FROM 
-       provinces p LEFT JOIN waterlines w 
-               ON (ST_Within(w.the_geom, p.the_geom) AND ST_IsClosed(w.the_geom))
-GROUP BY p.gid, p.province_name, p.the_geom;
-
---Same example above but utilizing a correlated subquery
---and PostgreSQL built-in ARRAY() function that converts a row set to an array
---NOTE: use of case because ST_MakePolygon 
---evidentally doesn't like empty arrays either
-SELECT p.gid,  p.province_name, CASE WHEN 
-       EXISTS(SELECT w.the_geom 
-               FROM waterlines w 
-               WHERE ST_Within(w.the_geom, p.the_geom) 
-               AND ST_IsClosed(w.the_geom))
-       THEN 
-       ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), 
-               ARRAY(SELECT w.the_geom 
-                       FROM waterlines w 
-                       WHERE ST_Within(w.the_geom, p.the_geom) 
-                       AND ST_IsClosed(w.the_geom)))
-       ELSE p.the_geom END As the_geom
-FROM 
-       provinces p; 
-                         </programlisting>
-          </listitem>
-        </varlistentry>
-
         <varlistentry>
           <term>ST_Polygonize(geometry set)</term>
 
@@ -2656,15 +2561,6 @@ WHERE n*100.00/length &lt; 1;
         </listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term>ST_GeometryType</term>
-
-        <listitem>
-          <para>Return the geometry type of the ST_Geometry value.</para>
-
-          <para>SQL-MM 3: 5.1.4</para>
-        </listitem>
-      </varlistentry>
 
       <varlistentry>
         <term>ST_GeomFromText</term>

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index 5304b3ef8dc433a8a8bdea369d72b7691b913acb..aeb8772b068baf3e09d34a26331e71afcd07fb1e 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -580,6 +580,113 @@ SELECT userpoints.id, ST_MakeLine(startpoint, endpoint) As drawn_line
                        </programlisting>
                </refsection>
        </refentry>
+       
+       <refentry id="ST_MakePolygon">
+               <refnamediv>
+               <refname>ST_MakePolygon</refname>
+               
+               <refpurpose>Creates a Polygon formed by the given shell. Input
+            geometries must be closed LINESTRINGS.</refpurpose>
+               </refnamediv>
+               
+               <refsynopsisdiv>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>geometry <function>ST_MakePolygon</function></funcdef>
+                       <paramdef><type>geometry</type> <parameter>linestring</parameter></paramdef>
+                 </funcprototype>
+               </funcsynopsis>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>geometry <function>ST_MakePolygon</function></funcdef>
+                       <paramdef><type>geometry</type> <parameter>outerlinestring</parameter></paramdef>
+                       <paramdef><type>geometry[]</type> <parameter>interiorlinestrings</parameter></paramdef>
+                 </funcprototype>
+               </funcsynopsis>
+               </refsynopsisdiv>
+               
+               <refsection>
+                       <title>Description</title>
+                       
+                       <para>Creates a Polygon formed by the given shell. Input
+                               geometries must be closed LINESTRINGS. Comes in 2 variants.</para>
+                       <para>Variant 1: takes one closed linestring.</para>
+                       <para>Variant 2:  Creates a Polygon formed by the given shell and array of
+            holes. You can construct a geometry array using ST_Accum or the PostgreSQL ARRAY[] and
+            ARRAY() constructs. Input geometries must be closed LINESTRINGS.</para>
+                       <note>
+                               <para>This function will not accept a MULTILINESTRING.  Use ST_LineMerge or ST_Dump to generate line strings.</para>
+                       </note>
+                       
+               </refsection>
+               
+               <refsection>
+               <title>Examples: Single closed LINESTRING</title>               
+                <programlisting>
+SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'));
+--If linestring is not closed
+--you can add the start point to close it
+SELECT ST_MakePolygon(ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)))
+FROM (
+SELECT ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5)') As open_line) As foo
+                         </programlisting>
+               </refsection>
+               <refsection>
+                       <title>Examples: Outter shell with inner shells</title>
+                       
+                       <para>Build a donut with an ant hole</para>
+           <programlisting>
+SELECT ST_MakePolygon(
+               ST_ExteriorRing(ST_Buffer(foo.line,10)),
+       ARRAY[ST_Translate(foo.line,1,1),
+               ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ]
+       )
+FROM 
+       (SELECT ST_ExteriorRing(ST_Buffer(ST_MakePoint(10,10),10,10))
+               As line )
+               As foo;
+               </programlisting>
+               <para>Build province boundaries with holes
+               representing lakes in the province from a set of 
+               province polygons/multipolygons and water line strings
+               this is an example of using PostGIS ST_Accum
+               <note><para>The use of CASE because feeding a null array into 
+               ST_MakePolygon results in NULL</para></note>
+               <note><para>the use of left join to guarantee we get all provinces back even if they have no lakes</para></note></para>
+               <programlisting>
+       SELECT p.gid, p.province_name, 
+               CASE WHEN
+                       ST_Accum(w.the_geom) IS NULL THEN p.the_geom
+               ELSE  ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), ST_Accum(w.the_geom)) END
+       FROM 
+               provinces p LEFT JOIN waterlines w 
+                       ON (ST_Within(w.the_geom, p.the_geom) AND ST_IsClosed(w.the_geom))
+       GROUP BY p.gid, p.province_name, p.the_geom;
+       
+       --Same example above but utilizing a correlated subquery
+       --and PostgreSQL built-in ARRAY() function that converts a row set to an array
+       
+       SELECT p.gid,  p.province_name, CASE WHEN 
+               EXISTS(SELECT w.the_geom 
+                       FROM waterlines w 
+                       WHERE ST_Within(w.the_geom, p.the_geom) 
+                       AND ST_IsClosed(w.the_geom))
+               THEN 
+               ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), 
+                       ARRAY(SELECT w.the_geom 
+                               FROM waterlines w 
+                               WHERE ST_Within(w.the_geom, p.the_geom) 
+                               AND ST_IsClosed(w.the_geom)))
+               ELSE p.the_geom END As the_geom
+       FROM 
+               provinces p; 
+                         </programlisting>
+               </refsection>
+               <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="ST_Accum" />, <xref linkend="ST_AddPoint" />, <xref linkend="ST_GeometryType" />, <xref linkend="ST_IsClose" />, <xref linkend="ST_LineMerge" /></para>
+               </refsection>
+       </refentry>
   </sect1>
    
   <sect1>
@@ -676,6 +783,49 @@ SELECT userpoints.id, ST_MakeLine(startpoint, endpoint) As drawn_line
        (1 row)</programlisting>
          </refsection>
        </refentry>
+       
+       <refentry id="ST_GeometryType">
+        <refnamediv>
+                       <refname>ST_GeometryType</refname>
+                       <refpurpose>Return the geometry type of the ST_Geometry value.</refpurpose>
+               </refnamediv>
+               
+               <refsynopsisdiv>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>text <function>ST_GeometryType</function></funcdef>
+                       <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+                 </funcprototype>
+               </funcsynopsis>
+               </refsynopsisdiv>
+               <refsection>
+                       <title>Description</title>
+                       
+                       <para>Returns the type of the geometry as a string. EG: 'ST_Linestring', 'ST_Polygon','ST_MultiPolygon' etc. This function differs from GeometryType(geometry) in the case of the string and ST in front that is returned, as well as the fact that it will not indicate whether the geometry is measured.</para>
+                       
+                        <!-- Optionally mention SQL/MM compliancy if appropriate -->
+                               <para><inlinemediaobject>
+                                       <imageobject>
+                                         <imagedata fileref="images/check.png" />
+                                       </imageobject>
+                                 </inlinemediaobject> This method implements the SQL/MM specification:
+                               SQL-MM 3: 5.1.4</para>
+               </refsection>
+               
+               <refsection>
+                       <title>Examples</title>
+                       
+                       <programlisting>SELECT ST_GeometryType(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
+                       --result
+                       ST_LineString
+                       </programlisting>
+               </refsection>
+               <refsection>
+                       <title>See Also</title>
+                       
+                       <para><xref linkend="GeometryType" /></para>
+               </refsection>
+       </refentry>
        <refentry id="ST_NPoints">
                <refnamediv>
                        <refname>ST_NPoints</refname>