From 845cfe012fd15300cd090b05fb4029a26b848a67 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 30 Aug 2020 14:37:24 -0400 Subject: [PATCH] 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 4c5cf5431, so that there's someplace for the 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 --- doc/src/sgml/func.sgml | 21 ++++++++++++++++++++- doc/src/sgml/ref/create_operator.sgml | 9 ++++++++- doc/src/sgml/syntax.sgml | 23 ++--------------------- doc/src/sgml/typeconv.sgml | 17 ++++++++--------- src/include/catalog/pg_operator.dat | 4 ++-- src/include/catalog/pg_proc.dat | 1 + 6 files changed, 41 insertions(+), 34 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 8a5f37671f..ab7e8c7fbd 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1055,6 +1055,7 @@ repeat('Pg', 4) PgPgPgPg Factorial + (deprecated, use factorial() instead) 5 ! @@ -1068,7 +1069,8 @@ repeat('Pg', 4) PgPgPgPg numeric - Factorial (as a prefix operator) + Factorial as a prefix operator + (deprecated, use factorial() instead) !! 5 @@ -1347,6 +1349,23 @@ repeat('Pg', 4) PgPgPgPg + + + + factorial + + factorial ( bigint ) + numeric + + + Factorial + + + factorial(5) + 120 + + + 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 name ( At least one of LEFTARG and RIGHTARG must be defined. For - binary operators, both must be defined. For right unary + binary operators, both must be defined. For right unary operators, only LEFTARG should be defined, while for left unary operators only RIGHTARG should be defined. + + + Right unary, also called postfix, operators are deprecated and will be + removed in PostgreSQL version 14. + + + The function_name function must have been previously defined using CREATE diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 2f993ca2e0..0ee303cb87 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -977,27 +977,8 @@ CAST ( 'string' AS type ) Most operators have the same precedence and are left-associative. The precedence and associativity of the operators is hard-wired into the parser. - - - - You will - sometimes need to add parentheses when using combinations of - binary and unary operators. For instance: - -SELECT 5 ! - 6; - - will be parsed as: - -SELECT 5 ! (- 6); - - because the parser has no idea — until it is too late - — that ! is defined as a postfix operator, - not an infix one. To get the desired behavior in this case, you - must write: - -SELECT (5 !) - 6; - - 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. diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml index 8900d0eb38..98662fc91f 100644 --- a/doc/src/sgml/typeconv.sgml +++ b/doc/src/sgml/typeconv.sgml @@ -354,20 +354,19 @@ Some examples follow. -Factorial Operator Type Resolution +Square Root Operator Type Resolution -There is only one factorial operator (postfix !) +There is only one square root operator (prefix |/) defined in the standard catalog, and it takes an argument of type -bigint. +double precision. The scanner assigns an initial type of integer to the argument in this query expression: -SELECT 40 ! AS "40 factorial"; - - 40 factorial --------------------------------------------------- - 815915283247897734345611269596115894272000000000 +SELECT |/ 40 AS "square root of 40"; + square root of 40 +------------------- + 6.324555320336759 (1 row) @@ -375,7 +374,7 @@ So the parser does a type conversion on the operand and the query is equivalent to: -SELECT CAST(40 AS bigint) ! AS "40 factorial"; +SELECT |/ CAST(40 AS double precision) AS "square root of 40"; diff --git a/src/include/catalog/pg_operator.dat b/src/include/catalog/pg_operator.dat index 59771f606d..3b3eb955d4 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 298ff4c4d1..c2287273a9 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' },