Обсуждение: Functions example results incorrect
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
On 23 June 2011 10:46, Thom Brown <thom@linux.com> wrote: > 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? 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. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935 EnterpriseDB UK: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Thom Brown <thom@linux.com> writes: > 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. 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. > The quote literal example of quote_literal('O\'Reilly') doesn't work > 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
On 1 July 2011 19:17, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Thom Brown <thom@linux.com> writes:
>> 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
>
> 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.
Fair enough.
>> The quote literal example of quote_literal('O\'Reilly') doesn't work
>> 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.
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?
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
Thom Brown <thom@linux.com> writes:
> On 1 July 2011 19:17, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Thom Brown <thom@linux.com> writes:
>>> The quote literal example of quote_literal('O\'Reilly') doesn't work
>>> 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.
> 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?
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
On 8 July 2011 00:16, Tom Lane <tgl@sss.pgh.pa.us> wrote: > 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> Sounds good to me. Thanks. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935 EnterpriseDB UK: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Tom Lane wrote:
> Thom Brown <thom@linux.com> writes:
> > On 1 July 2011 19:17, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >> Thom Brown <thom@linux.com> writes:
> >>> The quote literal example of quote_literal('O\'Reilly') doesn't work
> >>> 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.
>
> > 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?
>
> 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>
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 <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> 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).
> 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".
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