BUG #14695: Documentation is not accurate

yarex@pobox.sk writes:

url: https://www.postgresql.org/docs/8.1/static/functions-math.html

CEIL and FLOOR example is not accurate.

ceil(dp or numeric)
smallest integer not less than argument: ceil(-42.8) = -42

That example is just fine: it describes both the actual behavior
of the software, and the desired behavior. ceil() is effectively
"round towards plus infinity". You seem to be expecting "round
away from zero", but that's not how it's defined. For comparison,
the Linux man page for the C ceil() function says

For example, ceil(0.5) is 1.0, and ceil(-0.5) is 0.0.

regards, tom lane

--
Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-bugs

On Thursday, June 8, 2017, <yarex@pobox.sk> wrote:

url: https://www.postgresql.org/docs/8.1/static/functions-math.html

CEIL and FLOOR example is not accurate.

ceil(dp or numeric)
smallest integer not less than argument: ceil(-42.8) = -42

..... well, minus 42 is not smallest integer from -42.8, because -42 is
bigger number :-).

..... so correct number should be -43 in case of negative numbers

(positive are fine)

The key phase is "integer not less than argument" and -43 < -42 and so
cannot be a valid answer.

Like Tom said:

The integers from -41 to positive infinity are the set of potential answers
per the noted phrase. You pick the smallest of them which is -41.

David J.

=?utf-8?q?Jaroslav_Sivy?= <yarex@pobox.sk> writes:

The problem is in "largest integer not greater than argument" and "smallest integer not less than argument"
As you can see Largest integer from -42.8 is not -43, but infact its 42, because in negative numbers -42 > -43

Well, it still looks correct to me. FWIW, you're not the first to be
confused by this. In currently-supported releases we've rephrased it as

ceil(dp or numeric) nearest integer greater than or equal to argument

floor(dp or numeric) nearest integer less than or equal to argument

But 8.1 is six years out of support and its docs aren't going to be
updated any more.

regards, tom lane

--
Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-bugs

On Fri, Jun 9, 2017 at 12:59 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Well, it still looks correct to me. FWIW, you're not the first to be
confused by this. In currently-supported releases we've rephrased it as

ceil(dp or numeric) nearest integer greater than or equal to argument

floor(dp or numeric) nearest integer less than or equal to argument

While I do agree that the current docs on ceil() and floor() are good, I
also think that the description of round() is really not on par with them,
since I've seen people stumble on that more than once. So maybe this is a
good opportunity to improve it.

[3]: https://www.postgresql.org/docs/current/static/functions-math.html --
could be understood as any one of 6 deterministic plus 2 non-deterministic
methods.

In reality, the behavior is actually "half away from zero" for numeric and
"half to even" for floating point (on some machines). While this is well
documented somewhere else (last paragraph of 8.1.2 in [2]https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL), there is no
clear link between [3]https://www.postgresql.org/docs/current/static/functions-math.html -- and [2]https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL for people who who search for round().

So I think the docs on round() could be improved in one of two ways:
- copy the rounding description from [2]https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL to [3]https://www.postgresql.org/docs/current/static/functions-math.html -- so people know what they
are getting when calling round(); or,
- put a link somewhere in [3]https://www.postgresql.org/docs/current/static/functions-math.html -- pointing towards [2]https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL so that people can find
the related pages in one glance.

[1]: https://en.wikipedia.org/wiki/Rounding#Comparison_of_rounding_modes
[2]: https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL
https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL
[3]: https://www.postgresql.org/docs/current/static/functions-math.html --
--

Arthur Nascimento - tureba