Rename the "point is strictly above/below point" comparison operators.

Historically these were called >^ and <^, but that is inconsistent
with the similar box, polygon, and circle operators, which are named
|>> and <<| respectively.  Worse, the >^ and <^ names are used for
*not* strict above/below tests for the box type.

Hence, invent new operators following the more common naming.  The
old operators remain available for now, and are still accepted by
the relevant index opclasses too.  But there's a deprecation notice,
so maybe we can get rid of them someday.

Emre Hasegeli, reviewed by Pavel Borisov

Discussion: https://postgr.es/m/24348.1587444160@sss.pgh.pa.us

3 files changed, 23 insertions, 41 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7d06b979ebf..507bc1a6683 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10609,7 +10609,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
        </para>
        <para>
         Is first object strictly below second?
-        Available for <type>box</type>, <type>polygon</type>,
+        Available for <type>point</type>, <type>box</type>, <type>polygon</type>,
         <type>circle</type>.
        </para>
        <para>
@@ -10625,7 +10625,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
        </para>
        <para>
         Is first object strictly above second?
-        Available for <type>box</type>, <type>polygon</type>,
+        Available for <type>point</type>, <type>box</type>, <type>polygon</type>,
         <type>circle</type>.
        </para>
        <para>
@@ -10682,21 +10682,6 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
 
       <row>
        <entry role="func_table_entry"><para role="func_signature">
-        <type>point</type> <literal>&lt;^</literal> <type>point</type>
-        <returnvalue>boolean</returnvalue>
-       </para>
-       <para>
-        Is first object strictly below second?
-        (This operator is misnamed; it should be <literal>&lt;&lt;|</literal>.)
-       </para>
-       <para>
-        <literal>point '(1,0)' &lt;^ point '(1,1)'</literal>
-        <returnvalue>t</returnvalue>
-       </para></entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
         <type>box</type> <literal>&gt;^</literal> <type>box</type>
         <returnvalue>boolean</returnvalue>
        </para>
@@ -10711,21 +10696,6 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
 
       <row>
        <entry role="func_table_entry"><para role="func_signature">
-        <type>point</type> <literal>&gt;^</literal> <type>point</type>
-        <returnvalue>boolean</returnvalue>
-       </para>
-       <para>
-        Is first object strictly above second?
-        (This operator is misnamed; it should be <literal>|&gt;&gt;</literal>.)
-       </para>
-       <para>
-        <literal>point '(1,1)' &gt;^ point '(1,0)'</literal>
-        <returnvalue>t</returnvalue>
-       </para></entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
         <replaceable>geometric_type</replaceable> <literal>?#</literal> <replaceable>geometric_type</replaceable>
         <returnvalue>boolean</returnvalue>
        </para>
@@ -10877,6 +10847,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
     </para>
    </caution>
 
+   <note>
+    <para>
+     Before <productname>PostgreSQL</productname> 14, the point
+     is strictly below/above comparison operators <type>point</type>
+     <literal>&lt;&lt;|</literal> <type>point</type> and <type>point</type>
+     <literal>|&gt;&gt;</literal> <type>point</type> were respectively
+     called <literal>&lt;^</literal> and <literal>&gt;^</literal>.  These
+     names are still available, but are deprecated and will eventually be
+     removed.
+    </para>
+   </note>
+
    <table id="functions-geometry-func-table">
     <title>Geometric Functions</title>
     <tgroup cols="1">
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 1bf5f096591..d1b6cc9a01a 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -118,12 +118,12 @@
 
      <row>
       <entry valign="middle" morerows="7"><literal>point_ops</literal></entry>
-      <entry><literal>&gt;^ (point,point)</literal></entry>
+      <entry><literal>|&gt;&gt; (point,point)</literal></entry>
       <entry valign="middle" morerows="7"><literal>&lt;-&gt; (point,point)</literal></entry>
      </row>
      <row><entry><literal>&lt;&lt; (point,point)</literal></entry></row>
      <row><entry><literal>&gt;&gt; (point,point)</literal></entry></row>
-     <row><entry><literal>&lt;^ (point,point)</literal></entry></row>
+     <row><entry><literal>&lt;&lt;| (point,point)</literal></entry></row>
      <row><entry><literal>~= (point,point)</literal></entry></row>
      <row><entry><literal>&lt;@ (point,box)</literal></entry></row>
      <row><entry><literal>&lt;@ (point,polygon)</literal></entry></row>
diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml
index 68d09951d9f..ea88ae45e5b 100644
--- a/doc/src/sgml/spgist.sgml
+++ b/doc/src/sgml/spgist.sgml
@@ -76,7 +76,7 @@
      <row>
       <entry valign="middle" morerows="11"><literal>box_ops</literal></entry>
       <entry><literal>&lt;&lt; (box,box)</literal></entry>
-      <entry valign="middle" morerows="11"><literal>&lt;-&gt; (box,point)</literal></entry>      
+      <entry valign="middle" morerows="11"><literal>&lt;-&gt; (box,point)</literal></entry>
      </row>
      <row><entry><literal>&amp;&lt; (box,box)</literal></entry></row>
      <row><entry><literal>&amp;&gt; (box,box)</literal></entry></row>
@@ -92,12 +92,12 @@
 
      <row>
       <entry valign="middle" morerows="5"><literal>kd_point_ops</literal></entry>
-      <entry><literal>&gt;^ (point,point)</literal></entry>
+      <entry><literal>|&gt;&gt; (point,point)</literal></entry>
       <entry valign="middle" morerows="5"><literal>&lt;-&gt; (point,point)</literal></entry>
      </row>
      <row><entry><literal>&lt;&lt; (point,point)</literal></entry></row>
      <row><entry><literal>&gt;&gt; (point,point)</literal></entry></row>
-     <row><entry><literal>&lt;^ (point,point)</literal></entry></row>
+     <row><entry><literal>&lt;&lt;| (point,point)</literal></entry></row>
      <row><entry><literal>~= (point,point)</literal></entry></row>
      <row><entry><literal>&lt;@ (point,box)</literal></entry></row>
 
@@ -132,16 +132,16 @@
      <row><entry><literal>&lt;&lt;| (polygon,polygon)</literal></entry></row>
      <row><entry><literal>&amp;&lt;| (polygon,polygon)</literal></entry></row>
      <row><entry><literal>|&gt;&gt; (polygon,polygon)</literal></entry></row>
-     <row><entry><literal>|&amp;&gt; (polygon,polygon)</literal></entry></row>      
+     <row><entry><literal>|&amp;&gt; (polygon,polygon)</literal></entry></row>
 
      <row>
       <entry valign="middle" morerows="5"><literal>quad_point_ops</literal></entry>
-      <entry><literal>&gt;^ (point,point)</literal></entry>
+      <entry><literal>|&gt;&gt; (point,point)</literal></entry>
       <entry valign="middle" morerows="5"><literal>&lt;-&gt; (point,point)</literal></entry>
      </row>
      <row><entry><literal>&lt;&lt; (point,point)</literal></entry></row>
      <row><entry><literal>&gt;&gt; (point,point)</literal></entry></row>
-     <row><entry><literal>&lt;^ (point,point)</literal></entry></row>
+     <row><entry><literal>&lt;&lt;| (point,point)</literal></entry></row>
      <row><entry><literal>~= (point,point)</literal></entry></row>
      <row><entry><literal>&lt;@ (point,box)</literal></entry></row>
 
@@ -159,7 +159,7 @@
      <row><entry><literal>&amp;&lt; (anyrange,anyrange)</literal></entry></row>
      <row><entry><literal>&amp;&gt; (anyrange,anyrange)</literal></entry></row>
      <row><entry><literal>-|- (anyrange,anyrange)</literal></entry></row>
- 
+
      <row>
       <entry valign="middle" morerows="9"><literal>text_ops</literal></entry>
       <entry><literal>= (text,text)</literal></entry>