move over ST_Within and provide example

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 7b17c44a9369b585ad8ff42022c529686b52340c..d848cf8b4c6f3dd5b68a412da18203513a8ff2f4 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -64,30 +64,6 @@
           </listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term>ST_Within(A geometry, B geometry)</term>
-
-          <listitem>
-            <para>Returns TRUE if Geometry A is "spatially within"
-            Geometry B. A has to be completely inside B.</para>
-
-            <para>Performed by the GEOS module</para>
-
-            <para>Do not call with a GeometryCollection as an argument</para>
-
-            <para>This function call will automatically include a bounding box
-            comparison that will make use of any indexes that are available on
-            the geometries. To avoid index use, use the function
-            _ST_Within.</para>
-
-            <para>NOTE: this is the "allowable" version that returns a
-            boolean, not an integer.</para>
-
-            <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - a.Relate(b,
-            'T*F**F***')</para>
-          </listitem>
-        </varlistentry>
-
         <varlistentry>
           <term>ST_Overlaps(A geometry, B geometry)</term>
 
@@ -3265,16 +3241,7 @@ WHERE n*100.00/length &lt; 1;
         </listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term>ST_Within</term>
-
-        <listitem>
-          <para>Test if an ST_Geometry value is spatially within another
-          ST_Geometry value.</para>
-
-          <para>SQL-MM 3: 5.1.30</para>
-        </listitem>
-      </varlistentry>
+   
 
       <varlistentry>
         <term>ST_WKBToSQL</term>

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index 70b9eacf3c6220db5a48778bfd580174e5c57148..47fb4c41bb550608cab90a03668809e44121b01a 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -982,9 +982,11 @@ SELECT DISTINCT ON (s.gid) s.gid, s.school_name, s.the_geom, h.hospital_name
        
                <para>Returns TRUE if the given Geometries are "spatially
             equal". Use this for a 'better' answer than '='.
-                       Note by spatially equal we also mean ordering of points can be different but
+                       Note by spatially equal we mean ST_Within(A,B) = true and ST_Within(B,A) = true and
+                       also mean ordering of points can be different but
                        represent the same geometry structure.  To verify the order of points is consistent, use 
-                       ST_OrderingEquals.</para>
+                       ST_OrderingEquals (it must be noted ST_OrderingEquals is a little more stringent than simply verifying order of
+                       points are the same).</para>
 
                <para>
                  <inlinegraphic class="sfs_compliant" fileref="images/check.png" />
@@ -1017,7 +1019,7 @@ SELECT ST_Equals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
          <refsection>
                <title>See Also</title>
        
-               <para><xref linkend="ST_OrderingEquals"/>, <xref linkend="ST_Reverse"/></para>
+               <para><xref linkend="ST_OrderingEquals"/>, <xref linkend="ST_Reverse"/>, <xref linkend="ST_Within" /></para>
          </refsection>
          
        </refentry>
@@ -1167,6 +1169,100 @@ SELECT ST_OrderingEquals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
          </refsection>
          
        </refentry>
+       
+    <refentry id="ST_Within">
+      <refnamediv>
+        <refname>ST_Within</refname>
+
+        <refpurpose>Returns true if the geometry A is completely inside geometry B</refpurpose>
+      </refnamediv>
+
+      <refsynopsisdiv>
+        <funcsynopsis>
+          <funcprototype>
+            <funcdef>boolean <function>ST_Within</function></funcdef>
+
+            <paramdef><type>geometry </type>
+            <parameter>A</parameter></paramdef>
+
+            <paramdef><type>geometry </type>
+            <parameter>B</parameter></paramdef>
+          </funcprototype>
+        </funcsynopsis>
+      </refsynopsisdiv>
+
+      <refsection>
+        <title>Description</title>
+
+        <para>Returns TRUE if geometry A is completely inside geometry B. For this function to make
+        sense, the source geometries must both be of the same coorindate projection, 
+        having the same SRID.  It is a given that if ST_Within(A,B) is true and ST_Within(B,A) is true, then
+               the two geometries are considered spatially equal.</para>
+       
+        <para>Performed by the GEOS module</para>
+
+        <note><para>Do not call with a GeometryCollection as an argument</para></note>
+
+        <para>This function call will automatically include a bounding box
+            comparison that will make use of any indexes that are available on
+            the geometries. To avoid index use, use the function
+            _ST_Within.</para>
+
+        <para>NOTE: this is the "allowable" version that returns a
+            boolean, not an integer.</para>
+
+        <note>
+          <para>This function call will automatically include a bounding box
+          comparison that will make use of any indexes that are available on
+          the geometries.</para>
+        </note>
+
+        <para>
+          <inlinemediaobject>
+        <imageobject>
+          <imagedata fileref="images/check.png" />
+        </imageobject>
+      </inlinemediaobject> This method implements the 
+         <ulink url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
+    Implementation Specification for SQL.</ulink>
+                  OGC SPEC s2.1.1.2 // s2.1.13.3 - a.Relate(b,
+            'T*F**F***')
+        </para>
+               
+               <para>
+                       <inlinemediaobject>
+                               <imageobject>
+                                 <imagedata fileref="images/check.png" />
+                               </imageobject>
+                         </inlinemediaobject> This method implements the SQL/MM specification:
+                       SQL-MM 3: 5.1.30</para>
+      </refsection>
+
+      <refsection>
+        <title>Examples</title>
+          <programlisting>
+--a circle within a circle
+SELECT ST_Within(smallc,smallc) As smallinsmall,
+       ST_Within(smallc, bigc) As smallinbig, 
+       ST_Within(bigc,smallc) As biginsmall,
+       ST_Within(ST_Union(smallc, bigc), bigc) as unioninbig,
+       ST_Within(bigc, ST_Union(smallc, bigc)) as biginunion,
+       ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion
+FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc, 
+       ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
+--Result
+ smallinsmall | smallinbig | biginsmall | unioninbig | biginunion | bigisunion
+--------------+------------+------------+------------+------------+------------
+ t            | t          | f          | t          | t          | t
+(1 row)
+               </programlisting>
+      </refsection>
+      
+      <refsection>
+        <title>See Also</title>
+        <para><xref linkend="ST_Equals"/></para>
+      </refsection>
+    </refentry>
   </sect1>
   
   <sect1>