Thread: Math function description issue
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.
On Mon, Jun 6, 2016 at 2:40 PM, <npistud@gmail.com> wrote: > 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. 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. -- Michael
Attachment
Michael Paquier <michael.paquier@gmail.com> writes:
> On Mon, Jun 6, 2016 at 2:40 PM, <npistud@gmail.com> wrote:
>> 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
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 On 07.06.2016 05:06, Tom Lane wrote: > Michael Paquier <michael.paquier@gmail.com> writes: >> On Mon, Jun 6, 2016 at 2:40 PM, <npistud@gmail.com> wrote: >>> 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 > >
=?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> writes:
> The standard says:
> "<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".
> 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?
> 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
Tom Lane wrote: > =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> writes: > > 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. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 8 June 2016 at 00:11, Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > Tom Lane wrote: >> =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> writes: > >> > 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
Dean Rasheed <dean.a.rasheed@gmail.com> writes:
> 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