Mark factorial operator, and postfix operators in general, as deprecated.

Per discussion, we're planning to remove parser support for postfix
operators in order to simplify the grammar.  So it behooves us to
put out a deprecation notice at least one release before that.

There is only one built-in postfix operator, ! for factorial.
Label it deprecated in the docs and in pg_description, and adjust
some examples that formerly relied on it.  (The sister prefix
operator !! is also deprecated.  We don't really have to remove
that one, but since we're suggesting that people use factorial()
instead, it seems better to remove both operators.)

Also state in the CREATE OPERATOR ref page that postfix operators
in general are going away.

Although this changes the initial contents of pg_description,
I did not force a catversion bump; it doesn't seem essential.

In v13, also back- 4c5cf5431, so that there's someplace for
the <link>s to point to.

Mark Dilger and John Naylor, with some adjustments by me

Discussion: https://postgr.es/m/BE2DF53D-251A-4E26-972F-930E523580E9@enterprisedb.com

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bbbffd9d5bbc1cfd22649cfbce2b996307e06176..b9f591296a5d0fb7cf67ebdc7b18996a2da87110 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1055,6 +1055,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
        </para>
        <para>
         Factorial
+        (deprecated, use <link linkend="function-factorial"><function>factorial()</function></link> instead)
        </para>
        <para>
         <literal>5 !</literal>
@@ -1068,7 +1069,8 @@ 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="function-factorial"><function>factorial()</function></link> instead)
        </para>
        <para>
         <literal>!! 5</literal>
@@ -1349,7 +1351,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
 
       <row>
        <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
+        <indexterm id="function-factorial">
          <primary>factorial</primary>
         </indexterm>
         <function>factorial</function> ( <type>bigint</type> )

diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index d5c385c087f5c936410030711c203243ceddca2b..66c34e0072f0df989661c0a107417a7983d56fe7 100644 (file)
--- 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/syntax.sgml b/doc/src/sgml/syntax.sgml
index 2f993ca2e037c858979416f545f07594ecb5b14c..0ee303cb87f381db2a51bb96857bde04ce02d641 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -977,27 +977,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
     Most operators have the same precedence and are left-associative.
     The precedence and associativity of the operators is hard-wired
     into the parser.
-   </para>
-
-   <para>
-    You will
-    sometimes need to add parentheses when using combinations of
-    binary and unary operators.  For instance:
-<programlisting>
-SELECT 5 ! - 6;
-</programlisting>
-   will be parsed as:
-<programlisting>
-SELECT 5 ! (- 6);
-</programlisting>
-    because the parser has no idea &mdash; until it is too late
-    &mdash; that <token>!</token> is defined as a postfix operator,
-    not an infix one.  To get the desired behavior in this case, you
-    must write:
-<programlisting>
-SELECT (5 !) - 6;
-</programlisting>
-    This is the price one pays for extensibility.
+    Add parentheses if you want an expression with multiple operators
+    to be parsed in some other way than what the precedence rules imply.
    </para>
 
    <table id="sql-precedence-table">

diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 8900d0eb383209c1d21b8907fc52c01093ead417..98662fc91fb6d8404201e78233f51f9872308e30 100644 (file)
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -354,20 +354,19 @@ Some examples follow.
 </para>
 
 <example>
-<title>Factorial Operator Type Resolution</title>
+<title>Square Root Operator Type Resolution</title>
 
 <para>
-There is only one factorial operator (postfix <literal>!</literal>)
+There is only one square root operator (prefix <literal>|/</literal>)
 defined in the standard catalog, and it takes an argument of type
-<type>bigint</type>.
+<type>double precision</type>.
 The scanner assigns an initial type of <type>integer</type> to the argument
 in this query expression:
 <screen>
-SELECT 40 ! AS "40 factorial";
-
-                   40 factorial
---------------------------------------------------
- 815915283247897734345611269596115894272000000000
+SELECT |/ 40 AS "square root of 40";
+ square root of 40
+-------------------
+ 6.324555320336759
 (1 row)
 </screen>
 
@@ -375,7 +374,7 @@ So the parser does a type conversion on the operand and the query
 is equivalent to:
 
 <screen>
-SELECT CAST(40 AS bigint) ! AS "40 factorial";
+SELECT |/ CAST(40 AS double precision) AS "square root of 40";
 </screen>
 </para>
 </example>

diff --git a/src/include/catalog/pg_operator.dat b/src/include/catalog/pg_operator.dat
index 5b0e063655d33d85348a47cafd77cf998aaa4b38..4f8b9865effc4cc6f1407f656699c6916f4f9bfd 100644 (file)
--- 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 27989971db74d5303a1c1379a73caf3a75b2fec3..1dd325e0e6fdce4df46aa4d0b4dc8bfe17b37e32 100644 (file)
--- 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' },