From: Regina Obe <lr@pcorp.us>
Date: Thu, 16 Oct 2008 18:35:35 +0000 (+0000)
Subject: Move over ST_NumGeometries
X-Git-Tag: 1.4.0b1~609
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=af28063e7cad5bc13c55a21d0bfb50ccd9ffc63f;p=postgis

Move over ST_NumGeometries

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 02502ab4b..057fbc330 100644
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -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>
 
@@ -1608,17 +1589,6 @@ WHERE n*100.00/length &lt; 1;
         </listitem>
       </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>
 
diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index 93c96606d..f43bf8a03 100644
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -2358,6 +2358,60 @@ NOTICE:  Self-intersection at or near point 0 0
 		</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>