Documentation of return values of range functions lower and upper

On Wed, 2020-11-11 at 09:25 +0000, PG Doc comments form wrote:

Table 9.54 in page
https://www.postgresql.org/docs/current/functions-range.html states that the
functions lower and upper return NULL if the requested bound is infinite. If
the element type of the range contains the special values infinity and
-infinity, this is not correct, as those values are returned if explicitly
used as either bound.

+1

Perhaps it would be better to say

NULL if the range is empty or has no lower/upper bound

Yours,
Laurenz Albe

On Wed, 2020-11-11 at 18:19 +0100, Laurenz Albe wrote:

Table 9.54 in page
https://www.postgresql.org/docs/current/functions-range.html states that the
functions lower and upper return NULL if the requested bound is infinite. If
the element type of the range contains the special values infinity and
-infinity, this is not correct, as those values are returned if explicitly
used as either bound.

+1

Perhaps it would be better to say

NULL if the range is empty or has no lower/upper bound

Here is a patch for this.

Yours,
Laurenz Albe

On 2020/11/12 17:14, Laurenz Albe wrote:

On Wed, 2020-11-11 at 18:19 +0100, Laurenz Albe wrote:

Table 9.54 in page
https://www.postgresql.org/docs/current/functions-range.html states that the
functions lower and upper return NULL if the requested bound is infinite. If
the element type of the range contains the special values infinity and
-infinity, this is not correct, as those values are returned if explicitly
used as either bound.

+1

Perhaps it would be better to say

NULL if the range is empty or has no lower/upper bound

I agree this description looks a bit confusing. But according to the section
"Infinite (Unbounded) Ranges" (*1), we already call "lower/upper bound
omitted" just infinite. So I don't think the current description is incorrect.

(*1)
https://www.postgresql.org/docs/devel/rangetypes.html#RANGETYPES-INFINITE

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

On Wed, 2020-11-18 at 22:49 +0900, Fujii Masao wrote:

On 2020/11/12 17:14, Laurenz Albe wrote:

On Wed, 2020-11-11 at 18:19 +0100, Laurenz Albe wrote:

Table 9.54 in page
https://www.postgresql.org/docs/current/functions-range.html states that the
functions lower and upper return NULL if the requested bound is infinite. If
the element type of the range contains the special values infinity and
-infinity, this is not correct, as those values are returned if explicitly
used as either bound.

+1
Perhaps it would be better to say
NULL if the range is empty or has no lower/upper bound

I agree this description looks a bit confusing. But according to the section
"Infinite (Unbounded) Ranges" (*1), we already call "lower/upper bound
omitted" just infinite. So I don't think the current description is incorrect.

(*1)
https://www.postgresql.org/docs/devel/rangetypes.html#RANGETYPES-INFINITE

That is correct, but I'd argue that it would be better to clarify the paragraph too,
in particular:

The functions lower_inf and upper_inf test for infinite lower and upper bounds of a range, respectively.

should better read

The functions lower_inf and upper_inf test for omitted lower and upper bounds of a range, respectively.

The rest of the paragraph is pretty unambiguous.

Independent of this, I think that my patch for "upper" and "lower" would make the
documentation clearer.

Yours,
Laurenz Albe

On Wed, Nov 18, 2020 at 05:28:44PM +0100, Laurenz Albe wrote:

On Wed, 2020-11-18 at 22:49 +0900, Fujii Masao wrote:

On 2020/11/12 17:14, Laurenz Albe wrote:

On Wed, 2020-11-11 at 18:19 +0100, Laurenz Albe wrote:

Table 9.54 in page
https://www.postgresql.org/docs/current/functions-range.html states that the
functions lower and upper return NULL if the requested bound is infinite. If
the element type of the range contains the special values infinity and
-infinity, this is not correct, as those values are returned if explicitly
used as either bound.

+1
Perhaps it would be better to say
NULL if the range is empty or has no lower/upper bound

I agree this description looks a bit confusing. But according to the section
"Infinite (Unbounded) Ranges" (*1), we already call "lower/upper bound
omitted" just infinite. So I don't think the current description is incorrect.

(*1)
https://www.postgresql.org/docs/devel/rangetypes.html#RANGETYPES-INFINITE

That is correct, but I'd argue that it would be better to clarify the paragraph too,
in particular:

The functions lower_inf and upper_inf test for infinite lower and upper bounds of a range, respectively.

should better read

The functions lower_inf and upper_inf test for omitted lower and upper bounds of a range, respectively.

The rest of the paragraph is pretty unambiguous.

Independent of this, I think that my patch for "upper" and "lower" would make the
documentation clearer.

Yes, I agree this documentation needs help. Look at this output I
verified in PG 11 and master:

SELECT upper('[now,]'::tstzrange);
upper
--------
(null)

SELECT upper('[now,infinity]'::tstzrange);
upper
----------
infinity

SELECT upper('[-infinity,-infinity]'::tstzrange);
upper
-----------
-infinity

SELECT upper_inf('[now,]'::tstzrange);
upper_inf
-----------
t

SELECT upper_inf('[now,infinity]'::tstzrange);
upper_inf
-----------
f

SELECT upper_inf('[-infinity,-infinity]'::tstzrange);
upper_inf
-----------
f

For upper/lower(), it is clear that the documentation is better saying
"unspecified" rather than infinite. The fact that upper/lower_inf()
returns false for +/-Infinity is quite odd, but should at least be
documented.

Patch attached. It is odd that +Infinity (vs. Infinity) wasn't
supported for datetime input until PG 16, but I think we have to say
+/-infinity vs (blank)/-Infinity.

Patch attached.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Wed, 2023-11-01 at 16:28 -0400, Bruce Momjian wrote:

On Wed, Nov 18, 2020 at 05:28:44PM +0100, Laurenz Albe wrote:

On Wed, 2020-11-18 at 22:49 +0900, Fujii Masao wrote:

On 2020/11/12 17:14, Laurenz Albe wrote:

On Wed, 2020-11-11 at 18:19 +0100, Laurenz Albe wrote:

Table 9.54 in page
https://www.postgresql.org/docs/current/functions-range.html states that the
functions lower and upper return NULL if the requested bound is infinite. If
the element type of the range contains the special values infinity and
-infinity, this is not correct, as those values are returned if explicitly
used as either bound.

+1
Perhaps it would be better to say
NULL if the range is empty or has no lower/upper bound

I agree this description looks a bit confusing. But according to the section
"Infinite (Unbounded) Ranges" (*1), we already call "lower/upper bound
omitted" just infinite. So I don't think the current description is incorrect.

(*1)
https://www.postgresql.org/docs/devel/rangetypes.html#RANGETYPES-INFINITE

That is correct, but I'd argue that it would be better to clarify the paragraph too,
in particular:

The functions lower_inf and upper_inf test for infinite lower and upper bounds of a range, respectively.

should better read

The functions lower_inf and upper_inf test for omitted lower and upper bounds of a range, respectively.

The rest of the paragraph is pretty unambiguous.

Independent of this, I think that my patch for "upper" and "lower" would make the
documentation clearer.

Yes, I agree this documentation needs help.

For upper/lower(), it is clear that the documentation is better saying
"unspecified" rather than infinite. The fact that upper/lower_inf()
returns false for +/-Infinity is quite odd, but should at least be
documented.

Patch attached. It is odd that +Infinity (vs. Infinity) wasn't
supported for datetime input until PG 16, but I think we have to say
+/-infinity vs (blank)/-Infinity.

Patch attached.

I am unhappy with "unspecified". A NULL value as upper or lower bound has a very
specific meaning, namely that the range is unbounded in that direction. This is
a bit confusing, since NULL is typically used for unknown or undefined values.

I think it would be better to say "returns NULL if the range is empty or unbounded"
and "is the range unbounded on the upper end?".

Yours,
Laurenz Albe

On Wed, Nov 1, 2023 at 09:40:43PM +0100, Laurenz Albe wrote:

Yes, I agree this documentation needs help.

For upper/lower(), it is clear that the documentation is better saying
"unspecified" rather than infinite. The fact that upper/lower_inf()
returns false for +/-Infinity is quite odd, but should at least be
documented.

Patch attached. It is odd that +Infinity (vs. Infinity) wasn't
supported for datetime input until PG 16, but I think we have to say
+/-infinity vs (blank)/-Infinity.

Patch attached.

I am unhappy with "unspecified". A NULL value as upper or lower bound has a very
specific meaning, namely that the range is unbounded in that direction. This is
a bit confusing, since NULL is typically used for unknown or undefined values.

I think it would be better to say "returns NULL if the range is empty or unbounded"
and "is the range unbounded on the upper end?".

I had to go with "Is the multirange's lower bound unbounded?" because
the surrounding items use that sentence structure. Patch attached.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Wed, 2023-11-01 at 18:03 -0400, Bruce Momjian wrote:

On Wed, Nov 1, 2023 at 09:40:43PM +0100, Laurenz Albe wrote:

Yes, I agree this documentation needs help.

For upper/lower(), it is clear that the documentation is better saying
"unspecified" rather than infinite. The fact that upper/lower_inf()
returns false for +/-Infinity is quite odd, but should at least be
documented.

Patch attached. It is odd that +Infinity (vs. Infinity) wasn't
supported for datetime input until PG 16, but I think we have to say
+/-infinity vs (blank)/-Infinity.

Patch attached.

I am unhappy with "unspecified". A NULL value as upper or lower bound has a very
specific meaning, namely that the range is unbounded in that direction. This is
a bit confusing, since NULL is typically used for unknown or undefined values.

I think it would be better to say "returns NULL if the range is empty or unbounded"
and "is the range unbounded on the upper end?".

I had to go with "Is the multirange's lower bound unbounded?" because
the surrounding items use that sentence structure. Patch attached.

Better, though "Is the range's upper bound unbounded?" makes me cringe.
It is not the bound that is bounded or not, but the range.

How about "Is the range unbounded at the upper end?" or "Does the range
have no upper bound?"

Yours,
Laurenz Albe

On Thu, Nov 2, 2023 at 08:56:13AM +0100, Laurenz Albe wrote:

On Wed, 2023-11-01 at 18:03 -0400, Bruce Momjian wrote:

On Wed, Nov 1, 2023 at 09:40:43PM +0100, Laurenz Albe wrote:

Yes, I agree this documentation needs help.

For upper/lower(), it is clear that the documentation is better saying
"unspecified" rather than infinite. The fact that upper/lower_inf()
returns false for +/-Infinity is quite odd, but should at least be
documented.

Patch attached. It is odd that +Infinity (vs. Infinity) wasn't
supported for datetime input until PG 16, but I think we have to say
+/-infinity vs (blank)/-Infinity.

Patch attached.

I am unhappy with "unspecified". A NULL value as upper or lower bound has a very
specific meaning, namely that the range is unbounded in that direction. This is
a bit confusing, since NULL is typically used for unknown or undefined values.

I think it would be better to say "returns NULL if the range is empty or unbounded"
and "is the range unbounded on the upper end?".

I had to go with "Is the multirange's lower bound unbounded?" because
the surrounding items use that sentence structure. Patch attached.

Better, though "Is the range's upper bound unbounded?" makes me cringe.

Oh, yeah, totally cringe, me too. :-)

It is not the bound that is bounded or not, but the range.

How about "Is the range unbounded at the upper end?" or "Does the range
have no upper bound?"

I used your "end" idea to modify the patch, attached.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Thu, 2023-11-02 at 10:14 -0400, Bruce Momjian wrote:

Better, though "Is the range's upper bound unbounded?" makes me cringe.

Oh, yeah, totally cringe, me too.  :-)

It is not the bound that is bounded or not, but the range.

How about "Is the range unbounded at the upper end?" or "Does the range
have no upper bound?"

I used your "end" idea to modify the patch, attached.

There are still some loose ends:

- you lost the specification whether it is the upper or the lower bound

- "Infinity" is a literal

- "-Infinity" is a very unlikely value for an upper bound

How about the attached version?

Yours,
Laurenz Albe

On Thu, Nov 2, 2023 at 03:42:53PM +0100, Laurenz Albe wrote:

On Thu, 2023-11-02 at 10:14 -0400, Bruce Momjian wrote:

Better, though "Is the range's upper bound unbounded?" makes me cringe.

Oh, yeah, totally cringe, me too.  :-)

It is not the bound that is bounded or not, but the range.

How about "Is the range unbounded at the upper end?" or "Does the range
have no upper bound?"

I used your "end" idea to modify the patch, attached.

There are still some loose ends:

- you lost the specification whether it is the upper or the lower bound

- "Infinity" is a literal

- "-Infinity" is a very unlikely value for an upper bound

How about the attached version?

Agreed, yours is much better.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Thu, Nov 2, 2023 at 06:22:59PM -0400, Bruce Momjian wrote:

On Thu, Nov 2, 2023 at 03:42:53PM +0100, Laurenz Albe wrote:

On Thu, 2023-11-02 at 10:14 -0400, Bruce Momjian wrote:

Better, though "Is the range's upper bound unbounded?" makes me cringe.

Oh, yeah, totally cringe, me too.  :-)

It is not the bound that is bounded or not, but the range.

How about "Is the range unbounded at the upper end?" or "Does the range
have no upper bound?"

I used your "end" idea to modify the patch, attached.

There are still some loose ends:

- you lost the specification whether it is the upper or the lower bound

- "Infinity" is a literal

- "-Infinity" is a very unlikely value for an upper bound

How about the attached version?

Agreed, yours is much better.

Backpatched to PG 16.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Mon, 2023-11-13 at 16:08 -0500, Bruce Momjian wrote:

Backpatched to PG 16.

Thanks!

Yours,
Laurenz Albe