moved over &&, &<, and = from reference.xml to reference_new.xml in the documentation

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 65e7c4d20c9fc8931fb8a02a6c8e9c55da181f52..c0192c22e2afd23ec436c2ffbe1b8415f3326483 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -157,28 +157,7 @@
     <sect2>
       <title>Operators</title>
 
-      <variablelist>
-               <varlistentry>
-          <term>A = B</term>
-
-          <listitem>
-            <para>The "=" operator returns true if A's bounding box
-            is the same as B's bounding box.</para>
-                       <note><para>This is cause for a lot of confusion.  When you compare geometryA = geometryB it will return 
-                       true even when the geometries are clearly different if their bounding boxes are the same.  To check for 
-                       true equality use <xref linkend="ST_OrderingEquals"/> or <xref linkend="ST_Equals"/></para></note>
-          </listitem>
-        </varlistentry>
-               
-        <varlistentry>
-          <term>A &amp;&lt; B</term>
-
-          <listitem>
-            <para>The "&amp;&lt;" operator returns true if A's bounding box
-            overlaps or is to the left of B's bounding box.</para>
-          </listitem>
-        </varlistentry>
-
+      <variablelist>           
         <varlistentry>
           <term>A &amp;&gt; B</term>
 
@@ -269,16 +248,6 @@
             contains B's bounding box.</para>
           </listitem>
         </varlistentry>
-
-        <varlistentry>
-          <term>A &amp;&amp; B</term>
-
-          <listitem>
-            <para>The "&amp;&amp;" operator is the "overlaps" operator. If A's
-            bounding box overlaps B's bounding box the operator returns
-            true.</para>
-          </listitem>
-        </varlistentry>
       </variablelist>
     </sect2>
   </sect1>

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index e64f80f418ddae7e41546f2ab280013a1efad87f..7beac1695f24fb713181d4563756f5a23925ab13 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -7639,9 +7639,221 @@ F000000000000000000000000000000000000000000000000');
   </sect1>
   
   <sect1>
-      <title>Operators</title>
-      <para></para> 
-  </sect1>
+       <title>Operators</title>
+               <refentry id="ST_Geometry_Overlaps">    
+                 <refnamediv>
+                   <refname>&amp;&amp;</refname>
+               
+                   <refpurpose>Returns <varname>TRUE</varname> if A overlaps B.</refpurpose>
+                 </refnamediv>
+               
+                 <refsynopsisdiv>
+                   <funcsynopsis>
+                     <funcprototype>
+                       <!-- TODO: Ideally, it would be nice if this coule be reordered to 
+                       "boolean (geometry A && geometry B)" instead of 
+                       "boolean &&( geometry A, geometry B)" -->
+                       <funcdef>boolean <function>&amp;&amp;</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>The <varname>&amp;&amp;</varname> operator returns <varname>TRUE</varname> if the bounding box of geometry A overlaps the bounding box of geometry B.</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>
+                 </refsection>
+               
+                 <refsection>
+                   <title>Examples</title>
+               
+                   <programlisting>SELECT tbl1.column1, tbl2.column1, tbl1.column2 &amp;&amp; tbl2.column2 AS overlaps
+FROM ( VALUES
+       (1, 'LINESTRING(0 0, 3 3)'::geometry), 
+       (2, 'LINESTRING(0 1, 0 5)'::geometry)) AS tbl1,
+( VALUES
+       (3, 'LINESTRING(1 2, 4 6)'::geometry)) AS tbl2;
+
+ column1 | column1 | overlaps 
+---------+---------+----------
+       1 |       3 | t
+       2 |       3 | f
+(2 rows)</programlisting>
+                 </refsection>
+               
+                 <refsection>
+                   <title>See Also</title>
+               
+                   <para><xref linkend="ST_Geometry_Overleft" /></para>
+                 </refsection>
+               </refentry>
+
+               <refentry id="ST_Geometry_Overleft">    
+                 <refnamediv>
+                   <refname>&amp;&lt;</refname>
+               
+                   <refpurpose>Returns <varname>TRUE</varname> if A overlaps or is to the left of B.</refpurpose>
+                 </refnamediv>
+               
+                 <refsynopsisdiv>
+                   <funcsynopsis>
+                     <funcprototype>
+                       <!-- TODO: Ideally, it would be nice if this coule be reordered to 
+                       "boolean (geometry A &< geometry B)" instead of 
+                       "boolean &&( geometry A, geometry B)" -->
+                       <funcdef>boolean <function>&amp;&lt;</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>The <varname>&amp;&lt;</varname> operator returns <varname>TRUE</varname> if the bounding box of geometry A
+            overlaps or is to the left of the bounding box of geometry B.</para>
+                 </refsection>
+               
+                 <refsection>
+                   <title>Examples</title>
+               
+                   <programlisting>SELECT tbl1.column1, tbl2.column1, tbl1.column2 &amp;&lt; tbl2.column2 AS overlaps
+FROM 
+  ( VALUES
+       (1, 'LINESTRING(1 2, 4 6)'::geometry)) AS tbl1,
+  ( VALUES
+       (2, 'LINESTRING(0 0, 3 3)'::geometry), 
+       (3, 'LINESTRING(0 1, 0 5)'::geometry), 
+       (4, 'LINESTRING(6 0, 6 1)'::geometry)) AS tbl2;
+
+ column1 | column1 | overlaps 
+---------+---------+----------
+       1 |       2 | f        &lt;---- FIXME: this looks like a bug.
+       1 |       3 | f
+       1 |       4 | t
+(3 rows)</programlisting>
+                 </refsection>
+               
+                 <refsection>
+                   <title>See Also</title>
+               
+                   <para><xref linkend="ST_Geometry_Overlaps" /></para>
+                 </refsection>
+               </refentry>
+       
+               <refentry id="ST_Geometry_EQ">  
+                 <refnamediv>
+                   <refname>&#61;</refname>
+               
+                   <refpurpose>Returns <varname>TRUE</varname> if A is the same as B.</refpurpose>
+                 </refnamediv>
+               
+                 <refsynopsisdiv>
+                   <funcsynopsis>
+                     <funcprototype>
+                       <!-- TODO: Ideally, it would be nice if this coule be reordered to 
+                       "boolean (geometry A = geometry B)" instead of 
+                       "boolean =( geometry A, geometry B)" -->
+                       <funcdef>boolean <function>&#61;</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>The <varname>&#61;</varname> operator returns <varname>TRUE</varname> if the bounding box of geometry A
+                   is the same as the bounding box of geometry B.  PostgreSQL uses the =, &lt;, and &gt; operators defined for geometries to 
+                   perform internal orderings and comparison of geometries (ie. in a GROUP BY or ORDER BY clause).</para>
+               
+                   <note>
+                     <para>This is cause for a lot of confusion. When you compare geometryA =
+                     geometryB it will return true even when the geometries are clearly
+                     different IF their bounding boxes are the same. To check for true
+                     equality use <xref linkend="ST_OrderingEquals" /> or <xref
+                     linkend="ST_Equals" /></para>
+                   </note>
+                 </refsection>
+               
+                 <refsection>
+                   <title>Examples</title>
+               
+                   <programlisting>SELECT 'LINESTRING(0 0, 0 1, 1 0)'::geometry = 'LINESTRING(1 1, 0 0)'::geometry;
+ ?column? 
+----------
+ t
+(1 row)
+
+SELECT ST_AsText(column1)
+FROM ( VALUES
+       ('LINESTRING(0 0, 1 1)'::geometry), 
+       ('LINESTRING(1 1, 0 0)'::geometry)) AS foo;
+      st_astext      
+---------------------
+ LINESTRING(0 0,1 1)
+ LINESTRING(1 1,0 0)
+(2 rows)
+
+-- Note: the GROUP BY uses the "=" to compare for geometry equivalency.
+SELECT ST_AsText(column1)
+FROM ( VALUES
+       ('LINESTRING(0 0, 1 1)'::geometry), 
+       ('LINESTRING(1 1, 0 0)'::geometry)) AS foo
+GROUP BY column1;
+      st_astext      
+---------------------
+ LINESTRING(0 0,1 1)
+(1 row)</programlisting>
+                 </refsection>
+               
+                 <refsection>
+                   <title>See Also</title>
+               
+                   <para><xref linkend="ST_Equals" />, <xref linkend="ST_OrderingEquals" />
+                   <!--, <xref linkend="ST_Geometry_LT" />, <xref linkend="ST_Geometry_GT" /> --></para>
+                 </refsection>
+               </refentry>
+       
+       </sect1>
   
   
   <sect1 id="Spatial_Relationships_Measurements">