Skip to content

Commit 6ca547c

Browse files
tglsfdctglsfdc
committed
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-patch 4c5cf54, 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
1 parent 3d351d9 commit 6ca547c

File tree

6 files changed

+25
-35
lines changed

6 files changed

+25
-35
lines changed

‎doc/src/sgml/func.sgml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1055,6 +1055,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
10551055
</para>
10561056
<para>
10571057
Factorial
1058+
(deprecated, use <link linkend="function-factorial"><function>factorial()</function></link> instead)
10581059
</para>
10591060
<para>
10601061
<literal>5 !</literal>
@@ -1068,7 +1069,8 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
10681069
<returnvalue>numeric</returnvalue>
10691070
</para>
10701071
<para>
1071-
Factorial (as a prefix operator)
1072+
Factorial as a prefix operator
1073+
(deprecated, use <link linkend="function-factorial"><function>factorial()</function></link> instead)
10721074
</para>
10731075
<para>
10741076
<literal>!! 5</literal>
@@ -1349,7 +1351,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
13491351

13501352
<row>
13511353
<entry role="func_table_entry"><para role="func_signature">
1352-
<indexterm>
1354+
<indexterm id="function-factorial">
13531355
<primary>factorial</primary>
13541356
</indexterm>
13551357
<function>factorial</function> ( <type>bigint</type> )

‎doc/src/sgml/ref/create_operator.sgml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,11 +87,18 @@ CREATE OPERATOR <replaceable>name</replaceable> (
8787

8888
<para>
8989
At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined. For
90-
binary operators, both must be defined. For right unary
90+
binary operators, both must be defined. For right unary
9191
operators, only <literal>LEFTARG</literal> should be defined, while for left
9292
unary operators only <literal>RIGHTARG</literal> should be defined.
9393
</para>
9494

95+
<note>
96+
<para>
97+
Right unary, also called postfix, operators are deprecated and will be
98+
removed in <productname>PostgreSQL</productname> version 14.
99+
</para>
100+
</note>
101+
95102
<para>
96103
The <replaceable class="parameter">function_name</replaceable>
97104
function must have been previously defined using <command>CREATE

‎doc/src/sgml/syntax.sgml

Lines changed: 2 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -977,27 +977,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
977977
Most operators have the same precedence and are left-associative.
978978
The precedence and associativity of the operators is hard-wired
979979
into the parser.
980-
</para>
981-
982-
<para>
983-
You will
984-
sometimes need to add parentheses when using combinations of
985-
binary and unary operators. For instance:
986-
<programlisting>
987-
SELECT 5 ! - 6;
988-
</programlisting>
989-
will be parsed as:
990-
<programlisting>
991-
SELECT 5 ! (- 6);
992-
</programlisting>
993-
because the parser has no idea &mdash; until it is too late
994-
&mdash; that <token>!</token> is defined as a postfix operator,
995-
not an infix one. To get the desired behavior in this case, you
996-
must write:
997-
<programlisting>
998-
SELECT (5 !) - 6;
999-
</programlisting>
1000-
This is the price one pays for extensibility.
980+
Add parentheses if you want an expression with multiple operators
981+
to be parsed in some other way than what the precedence rules imply.
1001982
</para>
1002983

1003984
<table id="sql-precedence-table">

‎doc/src/sgml/typeconv.sgml

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -354,28 +354,27 @@ Some examples follow.
354354
</para>
355355

356356
<example>
357-
<title>Factorial Operator Type Resolution</title>
357+
<title>Square Root Operator Type Resolution</title>
358358

359359
<para>
360-
There is only one factorial operator (postfix <literal>!</literal>)
360+
There is only one square root operator (prefix <literal>|/</literal>)
361361
defined in the standard catalog, and it takes an argument of type
362-
<type>bigint</type>.
362+
<type>double precision</type>.
363363
The scanner assigns an initial type of <type>integer</type> to the argument
364364
in this query expression:
365365
<screen>
366-
SELECT 40 ! AS "40 factorial";
367-
368-
40 factorial
369-
--------------------------------------------------
370-
815915283247897734345611269596115894272000000000
366+
SELECT |/ 40 AS "square root of 40";
367+
square root of 40
368+
-------------------
369+
6.324555320336759
371370
(1 row)
372371
</screen>
373372

374373
So the parser does a type conversion on the operand and the query
375374
is equivalent to:
376375

377376
<screen>
378-
SELECT CAST(40 AS bigint) ! AS "40 factorial";
377+
SELECT |/ CAST(40 AS double precision) AS "square root of 40";
379378
</screen>
380379
</para>
381380
</example>

‎src/include/catalog/pg_operator.dat

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -218,10 +218,10 @@
218218
oprname => '>=', oprleft => 'xid8', oprright => 'xid8', oprresult => 'bool',
219219
oprcom => '<=(xid8,xid8)', oprnegate => '<(xid8,xid8)', oprcode => 'xid8ge',
220220
oprrest => 'scalargesel', oprjoin => 'scalargejoinsel' },
221-
{ oid => '388', descr => 'factorial',
221+
{ oid => '388', descr => 'deprecated, use factorial() instead',
222222
oprname => '!', oprkind => 'r', oprleft => 'int8', oprright => '0',
223223
oprresult => 'numeric', oprcode => 'numeric_fac' },
224-
{ oid => '389', descr => 'deprecated, use ! instead',
224+
{ oid => '389', descr => 'deprecated, use factorial() instead',
225225
oprname => '!!', oprkind => 'l', oprleft => '0', oprright => 'int8',
226226
oprresult => 'numeric', oprcode => 'numeric_fac' },
227227
{ oid => '385', descr => 'equal',

‎src/include/catalog/pg_proc.dat

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,7 @@
328328
proname => 'unknownout', prorettype => 'cstring', proargtypes => 'unknown',
329329
prosrc => 'unknownout' },
330330
{ oid => '111',
331+
descr => 'implementation of deprecated ! and !! factorial operators',
331332
proname => 'numeric_fac', prorettype => 'numeric', proargtypes => 'int8',
332333
prosrc => 'numeric_fac' },
333334

0 commit comments

Comments
 (0)