Subject: Incomplete or misleading explanation of the data types for mathematical operators

From: PG Doc comments form <[email-masked]>
Date: Wed, 29 Jan 2020 19:35:18 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/functions-math.html
Description:

"The bitwise operators work only on integral data types, whereas the others
are available for all numeric data types. "
Many math operators silently convert integral data types to double for
calculations, so the result will not be the same data type as what was
provided.
select pg_typeof(10^2::bigint),pg_typeof(10^2::numeric)
select pg_typeof(|/25::int), pg_typeof(|/25::numeric)
select pg_typeof(10*10::bigint), pg_typeof(10*10::numeric) 

Multiplication preserves data type, exponentiation silently converts bigint
to double, but preserves numeric data type, square root silently converts
both int and numeric types to double.
The best would be to explain this behaivior of operators like it was done
for mathematical functions.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 5 Mar 2020 21:29:12 -0500

> for mathematical functions.

Uh, how does this relate to bitwise operators?  Why would we mention
type changes for things like exponentiation in the bitwise operator
documentation section?

-- 
  Bruce Momjian  <[email-masked]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

---

From: Sergei Agalakov <[email-masked]>
Date: Thu, 5 Mar 2020 20:03:19 -0700

> type changes for things like exponentiation in the bitwise operator
This chapter is named "Mathematical Functions and Operators". The table 
9.4. is named "Mathematical Operators". I don't see on this page any 
section "Bitwise operators" so I don't really understand your complaint.
How do you understand the phrase "The bitwise operators work only on 
integral data types, whereas the others are available for all numeric 
data types. "  in the context of the table "Mathematical Operators"?
I understand it that all other mathematical operators except bitwise 
operators do exist for all numeric data type.
In what place by your opinion documentation should describe that some 
mathematical operators exist only for some numeric data types but not 
others?
I have given examples of such operators - exponentiation and square root 
aren't defined for all numeric data types and do hidden conversion of 
the data types.

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 21 Mar 2020 10:31:32 -0400

On Thu, Mar  5, 2020 at 08:03:19PM -0700, Sergei Agalakov wrote:
> This chapter is named "Mathematical Functions and Operators". The table 9.4.
> is named "Mathematical Operators". I don't see on this page any section
> "Bitwise operators" so I don't really understand your complaint.
> integral data types, whereas the others are available for all numeric data
> types. "  in the context of the table "Mathematical Operators"?
> aren't defined for all numeric data types and do hidden conversion of the
> data types.

Ah, I see what you are saying now --- there are operators listed above
that are not supported by all numeric data types, so "the others are
available for all numeric data types" is false.  I think the text was
written because non-integer calls to bit-wise functions _fail_, rather
than being silently converted:

	SELECT 1::float4 | 1;
	ERROR:  operator does not exist: real | integer
	LINE 1: SELECT 1::float4 | 1;
	                         ^
	HINT:  No operator matches the given name and argument types. You might
	need to add explicit type casts.

but I see your point.  I guess we could change the word "available" to
"silently converted", but it seems best to just remove that phrase. 
Documentation patch attached.

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 464a48ed6a..e1d70c251d 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -732,9 +732,8 @@
    </table>
 
    <para>
-    The bitwise operators work only on integral data types, whereas
-    the others are available for all numeric data types.  The bitwise
-    operators are also available for the bit
+    The bitwise operators work only on integral data types, and are also
+    available for the bit
     string types <type>bit</type> and <type>bit varying</type>, as
     shown in <xref linkend="functions-bit-string-op-table"/>.
    </para>

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 31 Mar 2020 18:44:49 -0400

Patch applied through 9.5, thanks.

---------------------------------------------------------------------------