documentation update for doc/src/sgml/func.sgml
Hi,
attached is a small patch which updates doc/src/sgml/func.sgml. The
change explains that functions like round() and others might behave
different depending on your operating system (because of rint(3)) and
that this is according to an IEEE standard. It also points out that #.5
is not always rounded up, as expected from a mathematical point of view.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Attachments:
func.sgml.patchtext/x-patch; name=func.sgml.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 13c71af..da30991 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -924,6 +924,25 @@
</tgroup>
</table>
+ <para>
+ For functions like round(), log() and sqrt() which run against
+ either fixed-precision (NUMERIC) or floating-point numbers (e.g. REAL),
+ note that the results of these operations will differ according
+ to the input type due to rounding. This is most observable with
+ round(), which can end up rounding down as well as up for
+ any #.5 value. We use the
+ <a xmlns="http://en.wikipedia.org/w/index.php?title=IEEE_floating_point&oldid=622007055#Rounding_rules">IEEE's rules</a>
+ for rounding floating-point numbers which can be machine-specific.
+ The bitwise operators work only on integral data types, whereas
+ the others are available for all numeric data types.
+ </para>
+
+ <para>
+ The bitwise operators 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>
+
<para>
<xref linkend="functions-math-random-table"> shows functions for
generating random numbers.
attached is a small patch which updates doc/src/sgml/func.sgml. The change
explains that functions like round() and others might behave different
depending on your operating system (because of rint(3)) and that this is
according to an IEEE standard. It also points out that #.5 is not always
rounded up, as expected from a mathematical point of view.
Applied on head & read. I'm not a native English speaker, but the English
looked right to me.
Comments:
I'm not sure that the "note that" on the third line is useful.
I do not understand why the last sentence in the first paragraph about
bitwise ops is put there with rounding issues, which seem unrelated. It
seems to me that it belongs to the second paragraph which is about bitwise
operators.
The wikipedia link can be simplified to a much cleaner:
http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules
Also, I submitted docs with relevant wikipedia links which was stripped of
these before committing. I'm wondering whether there is a general policy
not to put external links from within the text in the documentation. There
are very few of them, most in "acronym.sgml".
I would suggest to put relevant tags around functions and types, like:
"<function>round()</>" and "<type>NUMERIC</>".
--
Fabien.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On 08/21/2014 11:53 AM, Fabien COELHO wrote:
attached is a small patch which updates doc/src/sgml/func.sgml. The
change explains that functions like round() and others might behave
different depending on your operating system (because of rint(3)) and
that this is according to an IEEE standard. It also points out that
#.5 is not always rounded up, as expected from a mathematical point of
view.Applied on head & read. I'm not a native English speaker, but the
English looked right to me.
Thanks.
Comments:
I'm not sure that the "note that" on the third line is useful.
I do not understand why the last sentence in the first paragraph about
bitwise ops is put there with rounding issues, which seem unrelated. It
seems to me that it belongs to the second paragraph which is about
bitwise operators.
That's the part which came from Josh Berkus. We discussed this patch on IRC.
The wikipedia link can be simplified to a much cleaner:
http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules
It can, but then you always refer to the latest version of the Wikipedia
page, which might or might not be a good idea. The link in the patch
points to the current version from yesterday, no matter how many changes
are introduced afterwards.
But yes:
Also, I submitted docs with relevant wikipedia links which was stripped
of these before committing. I'm wondering whether there is a general
policy not to put external links from within the text in the
documentation. There are very few of them, most in "acronym.sgml".
It would be nice to have a general rule how to handle external links.
I would suggest to put relevant tags around functions and types, like:
"<function>round()</>" and "<type>NUMERIC</>".
Can do.
Thanks,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
I do not understand why the last sentence in the first paragraph about
bitwise ops is put there with rounding issues, which seem unrelated. It
seems to me that it belongs to the second paragraph which is about
bitwise operators.That's the part which came from Josh Berkus. We discussed this patch on IRC.
Hmmm. I do think the last sentence belongs to the next paragraph. The
identity of the author does not change my opinion on that point:-) If you
have another argument, maybe.
The wikipedia link can be simplified to a much cleaner:
http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules
It can, but then you always refer to the latest version of the Wikipedia
page, which might or might not be a good idea. The link in the patch points
to the current version from yesterday, no matter how many changes are
introduced afterwards.
I doubt that IEEE floating point rounding rules are likely to change much,
so referencing the latest version is both safe & cleaner. Also, wikipedia
would change its implementation from php to something else (well,
unlikely, probably as unlikely as a change in IEEE fp rounding rules:-).
--
Fabien.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On 08/21/2014 12:35 PM, Fabien COELHO wrote:
I do not understand why the last sentence in the first paragraph
about bitwise ops is put there with rounding issues, which seem
unrelated. It seems to me that it belongs to the second paragraph
which is about bitwise operators.That's the part which came from Josh Berkus. We discussed this patch
on IRC.Hmmm. I do think the last sentence belongs to the next paragraph. The
identity of the author does not change my opinion on that point:-) If
you have another argument, maybe.
Attached is an updated version of the patch.
The wikipedia link can be simplified to a much cleaner:
http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules
It can, but then you always refer to the latest version of the
Wikipedia page, which might or might not be a good idea. The link in
the patch points to the current version from yesterday, no matter how
many changes are introduced afterwards.I doubt that IEEE floating point rounding rules are likely to change
much, so referencing the latest version is both safe & cleaner. Also,
wikipedia would change its implementation from php to something else
(well, unlikely, probably as unlikely as a change in IEEE fp rounding
rules:-).
It's really not about the IEEE changing something, but about someone
changing the Wikipedia page. The way I linked it makes sure it always
displays the same version of the page.
Of course a general rule how to link to WP would be nice ...
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Attachments:
func.sgml.patchtext/x-patch; name=func.sgml.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 13c71af..15742f8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -924,6 +924,25 @@
</tgroup>
</table>
+ <para>
+ For functions like round(), log() and sqrt() which run against
+ either fixed-precision (NUMERIC) or floating-point numbers (e.g. REAL),
+ note that the results of these operations will differ according
+ to the input type due to rounding. This is most observable with
+ round(), which can end up rounding down as well as up for
+ any #.5 value. We use the
+ <a xmlns="http://en.wikipedia.org/w/index.php?title=IEEE_floating_point&oldid=622007055#Rounding_rules">IEEE's rules</a>
+ for rounding floating-point numbers which can be machine-specific.
+ </para>
+
+ <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 string types
+ <type>bit</type> and <type>bit varying</type>, as
+ shown in <xref linkend="functions-bit-string-op-table">.
+ </para>
+
<para>
<xref linkend="functions-math-random-table"> shows functions for
generating random numbers.
Attached is an updated version of the patch.
Ok.
I notice that you decided against adding tags around function and type
names.
It's really not about the IEEE changing something, but about someone
changing the Wikipedia page. The way I linked it makes sure it always
displays the same version of the page.
I understood that. I think that the likelyhood of someone removing the
section about rounding in the IEEE standard is very low, and the current
php link is pretty ugly from a REST perspective, and would prevent to see
the possible improved version of the page. Well, no big deal.
Of course a general rule how to link to WP would be nice ...
I'm afraid that the current implicit rule is more or less "no links", at
least there are very few of them but in the glossary, and when I submitted
docs with them they were removed before committing.
However I do support the idea that these links are useful references and
should be put where appropriate, even if it means that there must be some
updates from time to time.
--
Fabien.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
Fabien COELHO-3 wrote
Of course a general rule how to link to WP would be nice ...
I'm afraid that the current implicit rule is more or less "no links", at
least there are very few of them but in the glossary, and when I submitted
docs with them they were removed before committing.
Ideally if external links were to be allowed PostgreSQL.org would maintain a
URL shortening service and those shortened links would be in the
documentation so that any necessary pointers could be changed immediately
and without source updates.
David J.
--
View this message in context: http://postgresql.1045698.n5.nabble.com/documentation-update-for-doc-src-sgml-func-sgml-tp5815621p5818924.html
Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
Of course a general rule how to link to WP would be nice ...
I'm afraid that the current implicit rule is more or less "no links", at
least there are very few of them but in the glossary, and when I submitted
docs with them they were removed before committing.Ideally if external links were to be allowed PostgreSQL.org would maintain a
URL shortening service and those shortened links would be in the
documentation so that any necessary pointers could be changed immediately
and without source updates.
Why not. This would mean maintaining the redirection table somewhere. That
would also be a place to check whether some links become dandling
pointers. However there are also implications on the infrastructure to
host these redirections. Maybe one page on wiki.postgresql.org could be
used for this purpose.
--
Fabien.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On 9/12/14 3:13 PM, Andreas 'ads' Scherbaum wrote:
Of course a general rule how to link to WP would be nice ...
I think Wikipedia links should be avoided altogether. We can assume
that readers are technically proficient to look up general technical
concepts on their own using a reference system of their choice.
In cases where a link is warranted, it is better to construct a proper
bibliographic citation to the primary source material, such as an IEEE
standard or an academic paper, in a way that will stand the test of time.
Another problem, which the bibliography system partially addresses, is
that if we patch things like proposed here, we'll end up with
inconsistent linking all over the documentation wherever the concept is
mentioned. For example, we already make reference to the relevant IEEE
standard where floating-point types are first introduced in section
8.1.3, and we probably don't need to repeat "floating-point numbers are
weird" every time they are mentioned later on.
Independent of that, it is actually not correct that "we use the IEEE's
rules", because "we" don't use any rules, that is up to the operating
system/platform. While most platforms indeed do use the IEEE
floating-point standard more less, some don't. Section 8.1.3 tries to
point that out.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On 09/14/2014 06:32 PM, Peter Eisentraut wrote:
On 9/12/14 3:13 PM, Andreas 'ads' Scherbaum wrote:
Of course a general rule how to link to WP would be nice ...
I think Wikipedia links should be avoided altogether. We can assume
that readers are technically proficient to look up general technical
concepts on their own using a reference system of their choice.In cases where a link is warranted, it is better to construct a proper
bibliographic citation to the primary source material, such as an IEEE
standard or an academic paper, in a way that will stand the test of time.
That's a clear statement, and makes sense. Should be written down
somewhere, so it can be found again.
Independent of that, it is actually not correct that "we use the IEEE's
rules", because "we" don't use any rules, that is up to the operating
system/platform. While most platforms indeed do use the IEEE
floating-point standard more less, some don't. Section 8.1.3 tries to
point that out.
New version attached, WP link removed, wording changed.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Attachments:
func.sgml.patchtext/x-patch; name=func.sgml.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 13c71af..d54cf58 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -924,6 +924,25 @@
</tgroup>
</table>
+ <para>
+ For functions like round(), log() and sqrt() which run against
+ either fixed-precision (NUMERIC) or floating-point numbers (e.g. REAL),
+ note that the results of these operations will differ according
+ to the input type due to rounding. This is most observable with
+ round(), which can end up rounding down as well as up for
+ any #.5 value. <productname>PostgreSQL</productname>'s handling
+ of floating-point values depends on the operating system, which
+ may or may not follow the IEEE floating-point standard.
+ </para>
+
+ <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 string types
+ <type>bit</type> and <type>bit varying</type>, as
+ shown in <xref linkend="functions-bit-string-op-table">.
+ </para>
+
<para>
<xref linkend="functions-math-random-table"> shows functions for
generating random numbers.
On Sat, Oct 18, 2014 at 4:12 AM, Andreas 'ads' Scherbaum
<adsmail@wars-nicht.de> wrote:
On 09/14/2014 06:32 PM, Peter Eisentraut wrote:
On 9/12/14 3:13 PM, Andreas 'ads' Scherbaum wrote:
Of course a general rule how to link to WP would be nice ...
I think Wikipedia links should be avoided altogether. We can assume
that readers are technically proficient to look up general technical
concepts on their own using a reference system of their choice.In cases where a link is warranted, it is better to construct a proper
bibliographic citation to the primary source material, such as an IEEE
standard or an academic paper, in a way that will stand the test of time.That's a clear statement, and makes sense. Should be written down somewhere,
so it can be found again.Independent of that, it is actually not correct that "we use the IEEE's
rules", because "we" don't use any rules, that is up to the operating
system/platform. While most platforms indeed do use the IEEE
floating-point standard more less, some don't. Section 8.1.3 tries to
point that out.New version attached, WP link removed, wording changed.
Documentation format is still incorrect. The function names should be
put in a block <function>, same for the value 0.5 with <literal> and
the data types NUMERIC and REAL. Corrected patch is attached. The rest
looks fine to me, I am switching it to Ready for committer.
--
Michael
Attachments:
20141222_funcs_docfix.patchtext/x-patch; charset=US-ASCII; name=20141222_funcs_docfix.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6f30946..f6b865e 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -939,6 +939,26 @@
</tgroup>
</table>
+ <para>
+ For functions like <function>round()</>, <function>log()</> and
+ <function>sqrt()</> which run against either fixed-precision
+ (<literal>NUMERIC</>) or floating-point numbers (e.g. <literal>REAL</>),
+ note that the results of these operations will differ according
+ to the input type due to rounding. This is most observable with
+ <function>round()</>, which can end up rounding down as well as up for
+ any <literal>0.5</> value. <productname>PostgreSQL</productname>'s
+ handling of floating-point values depends on the operating system, which
+ may or may not follow the IEEE floating-point standard.
+ </para>
+
+ <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 string types
+ <type>bit</type> and <type>bit varying</type>, as
+ shown in <xref linkend="functions-bit-string-op-table">.
+ </para>
+
<para>
<xref linkend="functions-math-random-table"> shows functions for
generating random numbers.
Here is a slight update so that type names are treated homogeneously
between both added paragraphs.
ITSM that this patch should be committed without further ado.
--
Fabien.
Attachments:
funcs_docfix-20141231.patchtext/x-diff; name=funcs_docfix-20141231.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2016c5a..f91033b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -939,6 +939,26 @@
</tgroup>
</table>
+ <para>
+ For functions like <function>round()</>, <function>log()</> and
+ <function>sqrt()</> which run against either fixed-precision
+ (<type>numeric</>) or floating-point numbers (e.g. <type>real</>),
+ note that the results of these operations will differ according
+ to the input type due to rounding. This is most observable with
+ <function>round()</>, which can end up rounding down as well as up for
+ any <literal>0.5</> value. <productname>PostgreSQL</productname>'s
+ handling of floating-point values depends on the operating system, which
+ may or may not follow the IEEE floating-point standard.
+ </para>
+
+ <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 string types
+ <type>bit</> and <type>bit varying</>, as
+ shown in <xref linkend="functions-bit-string-op-table">.
+ </para>
+
<para>
<xref linkend="functions-math-random-table"> shows functions for
generating random numbers.
On Wed, Dec 31, 2014 at 9:44 AM, Fabien COELHO <coelho@cri.ensmp.fr> wrote:
Here is a slight update so that type names are treated homogeneously between
both added paragraphs.ITSM that this patch should be committed without further ado.
I had a look at this patch. This patch adds some text below a table
of functions. Immediately above that table, there is this existing
language:
The functions working with <type>double precision</type> data are mostly
implemented on top of the host system's C library; accuracy and behavior in
boundary cases can therefore vary depending on the host system.
This seems to me to substantially duplicate the information added by the patch.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
I had a look at this patch. This patch adds some text below a table
of functions. Immediately above that table, there is this existing
language:The functions working with <type>double precision</type> data are mostly
implemented on top of the host system's C library; accuracy and behavior in
boundary cases can therefore vary depending on the host system.This seems to me to substantially duplicate the information added by the patch.
I would rather say that it explicites the potential issues. Taking that
into account, maybe the part about floating point could be moved up after
the above sentence, or the above sentence moved down as an introduction,
with some pruning so that it fits in?
The second paragraph about bitwise ops is not related to these.
--
Fabien.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO <coelho@cri.ensmp.fr> wrote:
I had a look at this patch. This patch adds some text below a table
of functions. Immediately above that table, there is this existing
language:The functions working with <type>double precision</type> data are mostly
implemented on top of the host system's C library; accuracy and behavior
in
boundary cases can therefore vary depending on the host system.This seems to me to substantially duplicate the information added by the
patch.I would rather say that it explicites the potential issues. Taking that into
account, maybe the part about floating point could be moved up after the
above sentence, or the above sentence moved down as an introduction, with
some pruning so that it fits in?
Possibly. If anyone still cares about this patch, then they should
try revising it along those lines and submit an updated version. If
no one is excited enough about this to do that, we should just flag
this as rejected and move on. Since this patch has been kicking
around since August, my reading is nobody's very excited about it, but
maybe I'm misinterpreting the situation.
The second paragraph about bitwise ops is not related to these.
Yeah, I'm not quite sure how that got in here; I don't see discussion
of it upthread. It looks like it ought to be a completely separate
patch with its own discussion, FWICS.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On Mon, Feb 2, 2015 at 10:42 PM, Robert Haas <robertmhaas@gmail.com> wrote:
On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO <coelho@cri.ensmp.fr>
wrote:I had a look at this patch. This patch adds some text below a table
of functions. Immediately above that table, there is this existing
language:The functions working with <type>double precision</type> data are
mostly
implemented on top of the host system's C library; accuracy and
behavior
in
boundary cases can therefore vary depending on the host system.This seems to me to substantially duplicate the information added by the
patch.I would rather say that it explicites the potential issues. Taking that
into
account, maybe the part about floating point could be moved up after the
above sentence, or the above sentence moved down as an introduction, with
some pruning so that it fits in?Possibly. If anyone still cares about this patch, then they should
try revising it along those lines and submit an updated version. If
no one is excited enough about this to do that, we should just flag
this as rejected and move on. Since this patch has been kicking
around since August, my reading is nobody's very excited about it, but
maybe I'm misinterpreting the situation.
Let's move on then, marked as rejected.
--
Michael