Subject: Math function description issue

From: [email-masked]
Date: Mon, 06 Jun 2016 05:40:56 +0000

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 &lt; -42
So, description should be &quot;Biggest integer&quot;.

Vice versa for floor.

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Michael Paquier <[email-masked]>
Date: Tue, 7 Jun 2016 11:15:37 +0900

> So, description should be &quot;Biggest integer&quot;.

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
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ff7545d..980f1c4 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -702,7 +702,7 @@
         <literal><function>ceil(<type>dp</type> or <type>numeric</type>)</function></literal>
        </entry>
        <entry>(same as input)</entry>
-       <entry>smallest integer not less than argument</entry>
+       <entry>smallest following integer not less than argument</entry>
        <entry><literal>ceil(-42.8)</literal></entry>
        <entry><literal>-42</literal></entry>
       </row>
@@ -715,7 +715,7 @@
         <literal><function>ceiling(<type>dp</type> or <type>numeric</type>)</function></literal>
        </entry>
        <entry>(same as input)</entry>
-       <entry>smallest integer not less than argument (alias for <function>ceil</function>)</entry>
+       <entry>smallest following integer not less than argument (alias for <function>ceil</function>)</entry>
        <entry><literal>ceiling(-95.3)</literal></entry>
        <entry><literal>-95</literal></entry>
       </row>
@@ -768,7 +768,7 @@
         <literal><function>floor(<type>dp</type> or <type>numeric</type>)</function></literal>
        </entry>
        <entry>(same as input)</entry>
-       <entry>largest integer not greater than argument</entry>
+       <entry>largest previous integer not greater than argument</entry>
        <entry><literal>floor(-42.8)</literal></entry>
        <entry><literal>-43</literal></entry>
       </row>

---

From: Tom Lane <[email-masked]>
Date: Mon, 06 Jun 2016 23:06:25 -0400

> 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

---

From: Jürgen Purtz <[email-masked]>
Date: Tue, 7 Jun 2016 09:31:25 +0200

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

---

From: Tom Lane <[email-masked]>
Date: Tue, 07 Jun 2016 16:11:13 -0400

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

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".

> 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?

> 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

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 7 Jun 2016 19:11:48 -0400

> 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

---

From: Dean Rasheed <[email-masked]>
Date: Wed, 8 Jun 2016 06:20:42 +0100

> 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

---

From: Tom Lane <[email-masked]>
Date: Thu, 09 Jun 2016 11:58:57 -0400

> think about at most 2 possible values.

Hearing no objections, done that way.

			regards, tom lane