Date: Tue, 31 Mar 2020 18:44:49 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Sergei Agalakov <sergei.agalakov@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Incomplete or misleading explanation of the data types for
 mathematical operators
Message-ID: <20200331224449.GI17676@momjian.us>
References: <158032651854.19851.16261832706661813796@wrigleys.postgresql.org>
 <20200306022912.GB10548@momjian.us>
 <4d9d1083-b876-f90c-ace6-95df64153ecb@gmail.com>
 <20200321143132.GG10066@momjian.us>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20200321143132.GG10066@momjian.us>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk


Patch applied through 9.5, thanks.

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

On Sat, Mar 21, 2020 at 10:31:32AM -0400, Bruce Momjian wrote:
> On Thu, Mar  5, 2020 at 08:03:19PM -0700, Sergei Agalakov wrote:
> > On 3/5/2020 7:29 PM, Bruce Momjian wrote:
> > > On Wed, Jan 29, 2020 at 07:35:18PM +0000, PG Doc comments form wrote:
> > > > 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.
> > > Uh, how does this relate to bitwise operators?  Why would we mention
> > > type changes for things like exponentiation in the bitwise operator
> > > documentation section?
> > > 
> > 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.
> 
> 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.
> 
> -- 
>   Bruce Momjian  <bruce@momjian.us>        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 +

> 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>


-- 
  Bruce Momjian  <bruce@momjian.us>        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 +