[DOCS] Math function description issue

[n***@gmail.com]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.5/static/functions-math.html
Description:

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

Same issue for other versions.
Please, check ceil, ceiling and floor functions. Example is correct, but
description is wrong.

For ceil in docs
Description: smallest integer not less than argument.
Example: ceil(-42.8) = -42

But -42.8 < -42
So, description should be "Biggest integer".

Vice versa for floor.

[Michael Paquier]

Post by n***@gmail.com
Page: https://www.postgresql.org/docs/9.5/static/functions-math.html
https://www.postgresql.org/docs/9.5/static/functions-math.html
Same issue for other versions.
Please, check ceil, ceiling and floor functions. Example is correct, but
description is wrong.
For ceil in docs
Description: smallest integer not less than argument.
Example: ceil(-42.8) = -42
But -42.8 < -42
So, description should be "Biggest integer".
Vice versa for floor.

We could make things indeed more precise. Say for ceil, we use
"smallest *following* integer", and for floor, "largest *previous*
integer", and we keep the mention to "not less/greater than argument"
to show the fact that a numeric already rounded to an integer is equal
to itself. See the patch attached.

[Tom Lane]

Post by Michael Paquier

Post by n***@gmail.com
Please, check ceil, ceiling and floor functions. Example is correct, but
description is wrong.

We could make things indeed more precise. Say for ceil, we use
"smallest *following* integer", and for floor, "largest *previous*
integer", and we keep the mention to "not less/greater than argument"
to show the fact that a numeric already rounded to an integer is equal
to itself. See the patch attached.

Meh --- I'm not sure that adding previous/following really adds much
clarity. Either with the existing wording or with yours, the statement
is correct as long as you read "smaller" as "closer to minus infinity",
a/k/a "further left on the number line". But if you are thinking it
means "closer to zero", which is what I think the OP is thinking, this
won't do much to disabuse you of your confusion.

We had a similar complaint not long ago, so it does seem that the
wording could stand to be clarified. But I doubt this way fixes it.
Not sure how to do better ...

regards, tom lane

[Jürgen Purtz]

The standard says:

"<ceiling function> computes the least integer greater than or equal to
its argument."

a) In my opinion this wording is easier to understand because it avoids
the negation via "not less".
b) To dispel the ambiguities concerning what is greater or lesser (with
negative numbers) we may add a second example with +42.8 and an
additional comment - something like: "Please consider the situation with
negative numbers: -42 is greater than -43".

Jürgen Purtz

Post by Tom Lane

Post by Michael Paquier

Post by n***@gmail.com
Please, check ceil, ceiling and floor functions. Example is correct, but
description is wrong.

We could make things indeed more precise. Say for ceil, we use
"smallest *following* integer", and for floor, "largest *previous*
integer", and we keep the mention to "not less/greater than argument"
to show the fact that a numeric already rounded to an integer is equal
to itself. See the patch attached.

Meh --- I'm not sure that adding previous/following really adds much
clarity. Either with the existing wording or with yours, the statement
is correct as long as you read "smaller" as "closer to minus infinity",
a/k/a "further left on the number line". But if you are thinking it
means "closer to zero", which is what I think the OP is thinking, this
won't do much to disabuse you of your confusion.
We had a similar complaint not long ago, so it does seem that the
wording could stand to be clarified. But I doubt this way fixes it.
Not sure how to do better ...
regards, tom lane

[Tom Lane]

Post by Jürgen Purtz
"<ceiling function> computes the least integer greater than or equal to
its argument."

Hmm, you're looking at the SQL standard I guess. The existing wording
in our docs seems to be taken from the C/POSIX standard, which says
"[ceil(x)] shall compute the smallest integral value not less than x".

Post by Jürgen Purtz
a) In my opinion this wording is easier to understand because it avoids
the negation via "not less".

That's a fair point.

The other difference is least/greatest versus smallest/largest. I'm not
sure if using least/greatest would help the people who misunderstand
"smallest" as "closest to zero". They might; but being less-common words,
they might also confuse people whose native language isn't English.
Anyone have an opinion about which to use?

Post by Jürgen Purtz
b) To dispel the ambiguities concerning what is greater or lesser (with
negative numbers) we may add a second example with +42.8 and an
additional comment - something like: "Please consider the situation with
negative numbers: -42 is greater than -43".

I'm not terribly excited about that, and even if I were, there doesn't
seem to be a good way to shoehorn multiple examples into one entry in
these tables.

regards, tom lane

[Alvaro Herrera]

Post by Tom Lane

Post by Jürgen Purtz
a) In my opinion this wording is easier to understand because it avoids
the negation via "not less".

That's a fair point.
The other difference is least/greatest versus smallest/largest. I'm not
sure if using least/greatest would help the people who misunderstand
"smallest" as "closest to zero". They might; but being less-common words,
they might also confuse people whose native language isn't English.
Anyone have an opinion about which to use?

As a non-native, the use of "least/greatest" makes it more explicit that
it refers to arithmetic inequality, whereas "smallest" sounds like it
may be related to absolute value comparisons. It's true that
least/greatest are less common words, but that makes it more likely that
they would be looked up in a dictionary, whereas with smallest/largest
people might stick to intuitive knowledge and get them wrong.

[Dean Rasheed]

Post by Alvaro Herrera

Post by Tom Lane

Post by Jürgen Purtz
a) In my opinion this wording is easier to understand because it avoids
the negation via "not less".

That's a fair point.
The other difference is least/greatest versus smallest/largest. I'm not
sure if using least/greatest would help the people who misunderstand
"smallest" as "closest to zero". They might; but being less-common words,
they might also confuse people whose native language isn't English.
Anyone have an opinion about which to use?

As a non-native, the use of "least/greatest" makes it more explicit that
it refers to arithmetic inequality, whereas "smallest" sounds like it
may be related to absolute value comparisons. It's true that
least/greatest are less common words, but that makes it more likely that
they would be looked up in a dictionary, whereas with smallest/largest
people might stick to intuitive knowledge and get them wrong.

Matlab just uses "nearest" for both floor() and ceil(), e.g. "the
nearest integer less than or equal to ...".

To me, that seems clearer than smallest/largest or least/greatest
because you don't have to think about which set of numbers it's trying
to exclude. When thinking about the nearest integer, you only have to
think about at most 2 possible values.

Regards,
Dean

[Tom Lane]

Post by Dean Rasheed
Matlab just uses "nearest" for both floor() and ceil(), e.g. "the
nearest integer less than or equal to ...".
To me, that seems clearer than smallest/largest or least/greatest
because you don't have to think about which set of numbers it's trying
to exclude. When thinking about the nearest integer, you only have to
think about at most 2 possible values.

Hearing no objections, done that way.

regards, tom lane