Subject: Functions example results incorrect

From: Thom Brown <[email-masked]>
Date: Thu, 23 Jun 2011 10:46:09 +0100

I've been looking at some of the functions listed in the docs and
noticed some apparent discrepancies.

This page of the docs doesn't seem to match real output for exp or ln:
http://www.postgresql.org/docs/9.0/static/functions-math.html

It says that exp(1.0) yields 2.71828182845905.

Testing on 3 different systems shows an answer with two more
significant figures: 2.7182818284590452

The same for ln(2.0), which the example gives as 0.693147180559945,
but for me it's 0.6931471805599453.

And sqrt(2.0) has the example output of 1.4142135623731, but I get
1.414213562373095.

For log(100.0), the output is 2, which doesn't match the definition
since it claims the return type should be the same as the input, which
in this case it clearly isn't.  Trying this out returns
2.0000000000000000.

The log function for which the base is passed, and the type of which
should always be numeric shows an example output for log(2.0, 64.0) as
6.0000000000.  My output returns 6.0000000000000000, so 6 extra
digits.

The power function appears on 2 lines showing that it accepts double
precision or numeric.  The double precision example appears to be
wrong because it will be assumed the value is double precision unless
the value is explicitly cast.  In either case, the output wouldn't
have zero decimal places as shown in the example output.

Also, on the string functions page
(http://www.postgresql.org/docs/9.0/static/functions-string.html), the
output for the decode example shows an escape formatted output.  This
isn't the case by default in 9.0, so that should be changed, and maybe
a reference to a page explaining how the output depends on the
configuration of bytea_output.

The quote literal example of quote_literal('O\'Reilly') doesn't work
on my installation by default.  It assumes I'm using a client encoding
that allows backslash within a multibyte character and that I have
backslash_quote set to safe_encoding.

Can someone confirm whether these are valid complaints?

-- 
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

---

From: Thom Brown <[email-masked]>
Date: Thu, 23 Jun 2011 11:41:26 +0100

> And sqrt(2.0) has the example output of 1.4142135623731, but I get

The same non-default bytea output representations are also shown on
all examples on
http://www.postgresql.org/docs/9.0/static/functions-binarystring.html
where bytea is the output type.

---

From: Tom Lane <[email-masked]>
Date: Fri, 01 Jul 2011 14:17:31 -0400

> It says that exp(1.0) yields 2.71828182845905.

exp(1.0) invokes numeric exp() these days, but when the examples were
written, it would have invoked float8 exp().  At least on my machine,
float8 does give the cited results, eg

regression=# select exp(1.0::float8) ;
       exp        
------------------
 2.71828182845905
(1 row)

regression=# select ln(2.0::float8) ;
        ln         
-------------------
 0.693147180559945
(1 row)

regression=# select sqrt(2.0::float8);
      sqrt       
-----------------
 1.4142135623731
(1 row)

regression=# select log(100.0::float8);
 log 
-----
   2
(1 row)

Not sure if we want to change the examples or not.  As per the comment
above the table, these results are inherently a bit platform-dependent,
so someone who is expecting to match the results exactly is likely to be
disappointed anyhow.

> on my installation by default.

Hmm, should we use an E'' literal there, or change the input to be
'O''Reilly'?  The former would confuse people who didn't understand E''
literals, while the latter would make it look like quote_literal wasn't
doing anything at all, so neither alternative seems to offer much
clarity.

			regards, tom lane

---

From: Thom Brown <[email-masked]>
Date: Fri, 1 Jul 2011 19:33:18 +0100

On 1 July 2011 19:17, Tom Lane <[email-masked]> wrote:
> float8 does give the cited results
>

Fair enough.

> doing anything at all, so neither alternative seems to offer much

My concern is that people copying the example as a way to quote their
string literal will find that, by default, it doesn't work.  I'll
leave it to your better judgement though as I can see that the E''
notation could potentially confuse.   It is possible, either way, to
add a footnote to the example?

---

From: Tom Lane <[email-masked]>
Date: Thu, 07 Jul 2011 19:16:54 -0400

> add a footnote to the example?

On further study, I notice that somebody already E-ified all the other
examples where it was important; the quote_literal example simply got
overlooked, I think.  It seems better to use E'' there than make the
example potentially confusing as to what the function accomplishes.

Also, I looked at the examples for binary strings, and decided that
converting the sample outputs to hex format would render the examples
a lot less readable (since the inputs are not shown in that format).
So instead I'm going to add this:

   <note>
    <para>
     The sample results shown on this page assume that the server parameter
     <link linkend="guc-bytea-output"><varname>bytea_output</></link> is set
     to <literal>escape</literal> (the traditional PostgreSQL format).
    </para>
   </note>

			regards, tom lane

---

From: Thom Brown <[email-masked]>
Date: Fri, 8 Jul 2011 00:26:46 +0100

>     to <literal>escape</literal> (the traditional PostgreSQL format).

Sounds good to me.  Thanks.

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 11 Jul 2011 18:25:03 -0400 (EDT)

>      to <literal>escape</literal> (the traditional PostgreSQL format).

Please consider that the "traditional PostgreSQL format" is now not the
_default_ bytea_output format.  I think a lot of people equate
"traditional" with "default".

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

  + It's impossible for everything to be true. +

---

From: Tom Lane <[email-masked]>
Date: Mon, 11 Jul 2011 19:05:02 -0400

> "traditional" with "default".

Well, feel free to adjust the wording, but I saw at least one other
place that referred to "escape" as being the "traditional" format;
I borrowed that wording, I didn't invent it.

			regards, tom lane