Move over ST_Overlaps to new reference section and provide some examples

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 01d4f8e431d1edff070dce6833203d554f7503aa..17df10ccf5a9f9b1a94f3d7ba8189ff55a8539c6 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -24,29 +24,6 @@
 
       <variablelist>
 
-        <varlistentry>
-          <term>ST_Overlaps(A geometry, B geometry)</term>
-
-          <listitem>
-            <para>Returns TRUE if the Geometries "spatially
-            overlap".</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_Overlaps.</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</para>
-          </listitem>
-        </varlistentry>
-
         <varlistentry>
           <term>ST_Contains(A geometry, B geometry)</term>
 
@@ -2177,17 +2154,6 @@ WHERE n*100.00/length &lt; 1;
         </listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term>ST_Overlaps</term>
-
-        <listitem>
-          <para>Test if an ST_Geometry value spatially overlays another
-          ST_Geometry value.</para>
-
-          <para>SQL-MM 3: 5.1.32</para>
-        </listitem>
-      </varlistentry>
-
       <varlistentry>
         <term>ST_Point</term>
 

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index 8bead3f4e9965bcd55c8ab522de529b48784b713..c248f7bf4b450e6098b55b6c684938b130ee8ee1 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -3937,13 +3937,104 @@ SELECT ST_OrderingEquals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
  f
 (1 row)
 </programlisting>
-         </refsection>
+                 </refsection>
+                 <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="ST_Equals"/></para>
+                 </refsection>
+       </refentry>
+
+       <refentry id="ST_Overlaps">
+         <refnamediv>
+               <refname>ST_Overlaps</refname>
+       
+               <refpurpose>Returns TRUE if the Geometries share space, are of the same dimension, but are not completely contained by each other.</refpurpose>
+         </refnamediv>
+       
+         <refsynopsisdiv>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>boolean <function>ST_Overlaps</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 the Geometries "spatially
+            overlap".  By that we mean they intersect, but one does not completely contain another. </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_Overlaps.</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</para>
+
+               <para>
+                 <inlinegraphic class="sql_mm_compliant" fileref="images/check.png" />
+                 This method implements the SQL/MM specification: SQL-MM 3: 5.1.32
+               </para> 
+       
+         </refsection>
+       
+         <refsection>
+               <title>Examples</title>
+       
+               <programlisting>--a point on a line is contained by the line and is of a lower dimension, and therefore does not overlap the line
+                       nor crosses
+               
+SELECT ST_Overlaps(a,b) As a_overlap_b, 
+       ST_Crosses(a,b) As a_crosses_b, 
+               ST_Intersects(a, b) As a_intersects_b, ST_Contains(b,a) As b_contains_a
+FROM (SELECT ST_GeomFromText('POINT(1 0.5)') As a, ST_GeomFromText('LINESTRING(1 0, 1 1, 3 5)')  As b)
+       As foo
+       
+a_overlap_b | a_crosses_b | a_intersects_b | b_contains_a
+------------+-------------+----------------+--------------
+f           | f           | t              | t
+
+--a line that is partly contained by circle, but not fully is defined as intersecting and crossing,
+-- but since of different dimension it does not overlap
+SELECT ST_Overlaps(a,b) As a_overlap_b, ST_Crosses(a,b) As a_crosses_b, 
+       ST_Intersects(a, b) As a_intersects_b, 
+       ST_Contains(a,b) As a_contains_b
+FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 0.5)'), 3)  As a, ST_GeomFromText('LINESTRING(1 0, 1 1, 3 5)')  As b)
+       As foo;
+
+ a_overlap_b | a_crosses_b | a_intersects_b | a_contains_b
+-------------+-------------+----------------+--------------
+ f           | t           | t              | f
+ 
+ -- a 2-dimensional bent hot dog (aka puffered line string) that intersects a circle, 
+ --    but is not fully contained by the circle is defined as overlapping since they are of the same dimension,
+--     but it does not cross, because the intersection of the 2 is of the same dimension 
+--     as the maximum dimension of the 2
+
+SELECT ST_Overlaps(a,b) As a_overlap_b, ST_Crosses(a,b) As a_crosses_b, ST_Intersects(a, b) As a_intersects_b, ST_Contains(b,a) As b_contains_a, ST_Dimension(a) As dim_a, ST_Dimension(b) as dim_b
+FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 0.5)'), 3)  As a, ST_Buffer(ST_GeomFromText('LINESTRING(1 0, 1 1, 3 5)'),0.5)  As b)
+       As foo;
+       
+a_overlap_b | a_crosses_b | a_intersects_b | b_contains_a | dim_a | dim_b
+------------+-------------+----------------+--------------+-------+-------
+t           | f           | t              | f            |     2 |     2
+</programlisting>
+         </refsection>
 
          <refsection>
                <title>See Also</title>
        
-               <para><xref linkend="ST_Equals"/>, <xref linkend="ST_Reverse"/></para>
+               <para><xref linkend="ST_Contains"/>, <xref linkend="ST_Crosses"/>, <xref linkend="ST_Intersects"/></para>
          </refsection>
        </refentry>
        <refentry id="ST_Perimeter">