v3-0001-Adding-deprecation-notices.patch

From f7063a1e6556c4ac49bb98c86eda0cf62b15d087 Mon Sep 17 00:00:00 2001
From: Mark Dilger <mark.dilger@enterprisedb.com>
Date: Thu, 27 Aug 2020 08:38:56 -0700
Subject: [PATCH v3] Adding deprecation notices.

This deprecates all three of:

  Postfix factorial operator (!)
  Prefix factorial operator (!!)
  Unary right (postfix) operators
---
 doc/src/sgml/func.sgml                |  6 ++---
 doc/src/sgml/ref/create_operator.sgml |  9 ++++++-
 doc/src/sgml/ref/drop_operator.sgml   |  2 +-
 doc/src/sgml/typeconv.sgml            | 37 +++++++++++++++------------
 src/include/catalog/pg_operator.dat   |  4 +--
 src/include/catalog/pg_proc.dat       |  1 +
 6 files changed, 36 insertions(+), 23 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bbbffd9d5b..ef34e625af 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1054,7 +1054,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>numeric</returnvalue>
        </para>
        <para>
-        Factorial
+        Factorial (as a postfix operator, deprecated, use <link linkend="factorial">factorial()</link> instead)
        </para>
        <para>
         <literal>5 !</literal>
@@ -1068,7 +1068,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>numeric</returnvalue>
        </para>
        <para>
-        Factorial (as a prefix operator)
+        Factorial (as a prefix operator, deprecated, use <link linkend="factorial">factorial()</link> instead)
        </para>
        <para>
         <literal>!! 5</literal>
@@ -1348,7 +1348,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
       </row>
 
       <row>
-       <entry role="func_table_entry"><para role="func_signature">
+       <entry role="func_table_entry" id="factorial"><para role="func_signature">
         <indexterm>
          <primary>factorial</primary>
         </indexterm>
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index d5c385c087..66c34e0072 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -87,11 +87,18 @@ CREATE OPERATOR <replaceable>name</replaceable> (
 
   <para>
    At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined.  For
-   binary operators, both must be defined. For right  unary
+   binary operators, both must be defined. For right unary
    operators, only <literal>LEFTARG</literal> should be defined, while for left
    unary operators only <literal>RIGHTARG</literal> should be defined.
   </para>
 
+  <note>
+   <para>
+    Right unary, also called postfix, operators are deprecated and will be
+    removed in <productname>PostgreSQL</productname> version 14.
+   </para>
+  </note>
+
   <para>
    The <replaceable class="parameter">function_name</replaceable>
    function must have been previously defined using <command>CREATE
diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml
index 2dff050ecf..10d2b0b23b 100644
--- a/doc/src/sgml/ref/drop_operator.sgml
+++ b/doc/src/sgml/ref/drop_operator.sgml
@@ -121,7 +121,7 @@ DROP OPERATOR ~ (none, bit);
   </para>
 
   <para>
-   Remove the right unary factorial operator <literal>x!</literal>
+   Remove the deprecated right unary factorial operator <literal>x!</literal>
    for type <type>bigint</type>:
 <programlisting>
 DROP OPERATOR ! (bigint, none);
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 8900d0eb38..deba0de1c5 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -354,30 +354,35 @@ Some examples follow.
 </para>
 
 <example>
-<title>Factorial Operator Type Resolution</title>
+<title>JSONB Key Exists Operator Type Resolution</title>
 
 <para>
-There is only one factorial operator (postfix <literal>!</literal>)
-defined in the standard catalog, and it takes an argument of type
-<type>bigint</type>.
-The scanner assigns an initial type of <type>integer</type> to the argument
-in this query expression:
+There is only one key exists operator (infix <literal>?</literal>) defined in
+the standard catalog, taking a left argument of type <type>jsonb</type> and a
+right argument of type <type>text</type>.  The scanner assigns an initial type
+of <type>unknown</type> to each of the arguments in this query expression:
+</para>
 <screen>
-SELECT 40 ! AS "40 factorial";
-
-                   40 factorial
---------------------------------------------------
- 815915283247897734345611269596115894272000000000
+SELECT '{"poem":"Odyssey", "author":"Homer"}' ? 'author' AS "does author field exist";
+ does author field exist 
+-------------------------
+ t
 (1 row)
 </screen>
-
-So the parser does a type conversion on the operand and the query
-is equivalent to:
+<para>
+No types are specified in the query, so the parser looks for all candidate
+operators and finds that there is only one candidate, which accepts
+<type>jsonb</type> and <type>text</type> inputs.  The parser does type
+conversions on the operands and the query is equivalent to:
+</para>
 
 <screen>
-SELECT CAST(40 AS bigint) ! AS "40 factorial";
+SELECT CAST('{"poem":"Odyssey", "author":"Homer"}' AS jsonb) ? CAST('author' AS text) AS "does author field exist";
+ does author field exist 
+-------------------------
+ t
+(1 row)
 </screen>
-</para>
 </example>
 
 <example>
diff --git a/src/include/catalog/pg_operator.dat b/src/include/catalog/pg_operator.dat
index 5b0e063655..0d013a7fd1 100644
--- a/src/include/catalog/pg_operator.dat
+++ b/src/include/catalog/pg_operator.dat
@@ -218,10 +218,10 @@
   oprname => '>=', oprleft => 'xid8', oprright => 'xid8', oprresult => 'bool',
   oprcom => '<=(xid8,xid8)', oprnegate => '<(xid8,xid8)', oprcode => 'xid8ge',
   oprrest => 'scalargesel', oprjoin => 'scalargejoinsel' },
-{ oid => '388', descr => 'factorial',
+{ oid => '388', descr => 'deprecated, use factorial instead',
   oprname => '!', oprkind => 'r', oprleft => 'int8', oprright => '0',
   oprresult => 'numeric', oprcode => 'numeric_fac' },
-{ oid => '389', descr => 'deprecated, use ! instead',
+{ oid => '389', descr => 'deprecated, use factorial instead',
   oprname => '!!', oprkind => 'l', oprleft => '0', oprright => 'int8',
   oprresult => 'numeric', oprcode => 'numeric_fac' },
 { oid => '385', descr => 'equal',
diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 27989971db..1dd325e0e6 100644
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -328,6 +328,7 @@
   proname => 'unknownout', prorettype => 'cstring', proargtypes => 'unknown',
   prosrc => 'unknownout' },
 { oid => '111',
+  descr => 'implementation of deprecated ! and !! factorial operators',
   proname => 'numeric_fac', prorettype => 'numeric', proargtypes => 'int8',
   prosrc => 'numeric_fac' },
 
-- 
2.21.1 (Apple Git-122.3)