[postgis-commits] svn - r3128 - trunk/doc

[postgis-commits at postgis.refractions.net]

Author: robe
Date: 2008-10-16 11:35:35 -0700 (Thu, 16 Oct 2008)
New Revision: 3128

Modified:
   trunk/doc/reference.xml
   trunk/doc/reference_new.xml
Log:
Move over ST_NumGeometries

Modified: trunk/doc/reference.xml
===================================================================
--- trunk/doc/reference.xml	2008-10-16 18:17:32 UTC (rev 3127)
+++ trunk/doc/reference.xml	2008-10-16 18:35:35 UTC (rev 3128)
@@ -179,16 +179,7 @@
           </listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term>ST_NumGeometries(geometry)</term>
-
-          <listitem>
-            <para>If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
-            number of geometries, otherwise return NULL.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
+        <varlistentry id="ST_GeometryN">
           <term>ST_GeometryN(geometry,nth integer)</term>
 
           <listitem>
@@ -203,16 +194,6 @@
           </listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term>ST_NumPoints(geometry)</term>
-
-          <listitem>
-            <para>Find and return the number of points in the first linestring
-            in the geometry. Return NULL if there is no linestring in the
-            geometry.</para>
-          </listitem>
-        </varlistentry>
-
         <varlistentry id="ST_PointN">
           <term>ST_PointN(geometry,nth integer)</term>
 
@@ -1609,17 +1590,6 @@
       </varlistentry>
 
       <varlistentry>
-        <term>ST_NumGeometries</term>
-
-        <listitem>
-          <para>Return the number of geometries in an
-          ST_GeomCollection.</para>
-
-          <para>SQL-MM 3: 9.1.4</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
         <term>ST_Point</term>
 
         <listitem>

Modified: trunk/doc/reference_new.xml
===================================================================
--- trunk/doc/reference_new.xml	2008-10-16 18:17:32 UTC (rev 3127)
+++ trunk/doc/reference_new.xml	2008-10-16 18:35:35 UTC (rev 3128)
@@ -2358,6 +2358,60 @@
 		</refsection>
 	</refentry>
 	
+	<refentry id="ST_NumGeometries">
+		<refnamediv>
+			<refname>ST_NumGeometries</refname>
+			<refpurpose>If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
+            number of geometries, otherwise return NULL.</refpurpose>
+		</refnamediv>
+		
+		<refsynopsisdiv>
+		<funcsynopsis>
+		  <funcprototype>
+			<funcdef>integer <function>ST_NumGeometries</function></funcdef>
+			<paramdef><type>geometry </type> <parameter>a_multi_or_geomcollection</parameter></paramdef>
+		  </funcprototype>
+		</funcsynopsis>
+		</refsynopsisdiv>
+		
+		<refsection>
+			<title>Description</title>
+			
+			<para>Returns the number of Geometries. If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
+            number of geometries, otherwise return NULL.</para>
+			
+			    <para><inlinemediaobject>
+        <imageobject>
+          <imagedata fileref="images/check.png" />
+        </imageobject>
+      </inlinemediaobject> This method implements the SQL/MM specification: SQL-MM 3: 9.1.4</para>
+		
+		</refsection>
+		
+		<refsection>
+			<title>Examples</title>
+			
+<programlisting>
+--Although ST_NumGeometries will return null when passed a single, you can wrap in ST_Multi to force 1 or more for all geoms
+SELECT ST_NumGeometries(ST_Multi(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)')));
+--result
+1
+
+--Geometry Collection Example - multis count as one geom in a collection
+SELECT ST_NumGeometries(ST_GeomFromEWKT('GEOMETRYCOLLECTION(MULTIPOINT(-2 3 , -2 2),
+LINESTRING(5 5 ,10 10),
+POLYGON((-7 4.2,-7.1 5,-7.1 4.3,-7 4.2)))'));
+--result
+3
+</programlisting>
+		</refsection>
+		<refsection>
+			<title>See Also</title>
+			
+			<para><xref linkend="ST_GeometryN" />, <xref linkend="ST_Multi" /></para>
+		</refsection>
+	</refentry>
+	
 	<refentry id="ST_NumInteriorRings">
 	  <refnamediv>
 		<refname>ST_NumInteriorRings</refname>