pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedDocumentation of return values of range functions lower and upper
14+ messages / 4 participants
[nested] [flat]
* Documentation of return values of range functions lower and upper
@ 2020-11-11 09:25 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 14+ messages in thread
From: PG Doc comments form @ 2020-11-11 09:25 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: jani.rahkola@iki.fi
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/13/functions-range.html
Description:
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.
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2020-11-11 17:19 Laurenz Albe <laurenz.albe@cybertec.at>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 14+ messages in thread
From: Laurenz Albe @ 2020-11-11 17:19 UTC (permalink / raw)
To: jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2020-11-12 08:14 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 14+ messages in thread
From: Laurenz Albe @ 2020-11-12 08:14 UTC (permalink / raw)
To: jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] 0001-Improve-upper-lower-documentation-for-ranges.patch (1.4K, ../../16601466752e40543051369fac722c0a200bb4e6.camel@cybertec.at/2-0001-Improve-upper-lower-documentation-for-ranges.patch)
download | inline diff:
From b17d2d968268257c5d1385bb834747fe3c33834b Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Thu, 12 Nov 2020 09:13:09 +0100
Subject: [PATCH] Improve upper/lower documentation for ranges
The old wording could give the impression that these
functions would return NULL if the range is bounded
by a value "infinity". Report by Jani Rahkola.
Discussion: https://postgr.es/m/160508672127.25505.8356390205508789564@wrigleys.postgresql.org
---
doc/src/sgml/func.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2783985b55..d290653ae8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18176,7 +18176,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the range (<literal>NULL</literal> if the
- range is empty or the lower bound is infinite).
+ range is empty or has no lower bound).
</para>
<para>
<literal>lower(numrange(1.1,2.2))</literal>
@@ -18194,7 +18194,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the range (<literal>NULL</literal> if the
- range is empty or the upper bound is infinite).
+ range is empty or has no upper bound).
</para>
<para>
<literal>upper(numrange(1.1,2.2))</literal>
--
2.26.2
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2020-11-18 13:49 Fujii Masao <masao.fujii@oss.nttdata.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 14+ messages in thread
From: Fujii Masao @ 2020-11-18 13:49 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2020-11-18 16:28 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Fujii Masao <masao.fujii@oss.nttdata.com>
0 siblings, 1 reply; 14+ messages in thread
From: Laurenz Albe @ 2020-11-18 16:28 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-01 20:28 Bruce Momjian <bruce@momjian.us>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 14+ messages in thread
From: Bruce Momjian @ 2023-11-01 20:28 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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.
Attachments:
[text/x-diff] range.diff (3.0K, ../../ZUK0-gzxmfHdDila@momjian.us/2-range.diff)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c76ec52c55..fd390b03ac 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -19905,7 +19905,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the range (<literal>NULL</literal> if the
- range is empty or the lower bound is infinite).
+ range is empty or unspecified).
</para>
<para>
<literal>lower(numrange(1.1,2.2))</literal>
@@ -19923,7 +19923,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the range (<literal>NULL</literal> if the
- range is empty or the upper bound is infinite).
+ range is empty or unspecified).
</para>
<para>
<literal>upper(numrange(1.1,2.2))</literal>
@@ -19991,7 +19991,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's lower bound infinite?
+ Is the range's lower bound unspecified? A +/-Infinity lower
+ bound returns false.
</para>
<para>
<literal>lower_inf('(,)'::daterange)</literal>
@@ -20008,7 +20009,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's upper bound infinite?
+ Is the range's upper bound unspecified? A +/-Infinity upper
+ bound returns false.
</para>
<para>
<literal>upper_inf('(,)'::daterange)</literal>
@@ -20063,7 +20065,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the lower bound is infinite).
+ multirange is empty or unspecified).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20081,7 +20083,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the upper bound is infinite).
+ multirange is empty or unspecified).
</para>
<para>
<literal>upper('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20149,7 +20151,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's lower bound infinite?
+ Is the multirange's lower bound unspecified? A +/-Infinity lower
+ bound returns false.
</para>
<para>
<literal>lower_inf('{(,)}'::datemultirange)</literal>
@@ -20166,7 +20169,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's upper bound infinite?
+ Is the multirange's upper bound unspecified? A +/-Infinity upper
+ bound returns false.
</para>
<para>
<literal>upper_inf('{(,)}'::datemultirange)</literal>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-01 20:40 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 14+ messages in thread
From: Laurenz Albe @ 2023-11-01 20:40 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-01 22:03 Bruce Momjian <bruce@momjian.us>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 14+ messages in thread
From: Bruce Momjian @ 2023-11-01 22:03 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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.
Attachments:
[text/x-diff] range.diff (3.0K, ../../ZULLQ0Zycz8PmfsT@momjian.us/2-range.diff)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c76ec52c55..aa82f8dd81 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -19905,7 +19905,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the range (<literal>NULL</literal> if the
- range is empty or the lower bound is infinite).
+ range is empty or unbounded).
</para>
<para>
<literal>lower(numrange(1.1,2.2))</literal>
@@ -19923,7 +19923,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the range (<literal>NULL</literal> if the
- range is empty or the upper bound is infinite).
+ range is empty or unbounded).
</para>
<para>
<literal>upper(numrange(1.1,2.2))</literal>
@@ -19991,7 +19991,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's lower bound infinite?
+ Is the range's lower bound unbounded? A +/-Infinity lower
+ bound returns false.
</para>
<para>
<literal>lower_inf('(,)'::daterange)</literal>
@@ -20008,7 +20009,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's upper bound infinite?
+ Is the range's upper bound unbounded? A +/-Infinity upper
+ bound returns false.
</para>
<para>
<literal>upper_inf('(,)'::daterange)</literal>
@@ -20063,7 +20065,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the lower bound is infinite).
+ multirange is empty or unbounded).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20081,7 +20083,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the upper bound is infinite).
+ multirange is empty or unbounded).
</para>
<para>
<literal>upper('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20149,7 +20151,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's lower bound infinite?
+ Is the multirange's lower bound unbounded? A +/-Infinity lower
+ bound returns false.
</para>
<para>
<literal>lower_inf('{(,)}'::datemultirange)</literal>
@@ -20166,7 +20169,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's upper bound infinite?
+ Is the multirange's upper bound unbounded? A +/-Infinity upper
+ bound returns false.
</para>
<para>
<literal>upper_inf('{(,)}'::datemultirange)</literal>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-02 07:56 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 14+ messages in thread
From: Laurenz Albe @ 2023-11-02 07:56 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-02 14:14 Bruce Momjian <bruce@momjian.us>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 14+ messages in thread
From: Bruce Momjian @ 2023-11-02 14:14 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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.
Attachments:
[text/x-diff] range.diff (3.0K, ../../ZUOu4maaCXivToUE@momjian.us/2-range.diff)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c76ec52c55..c2f266ea24 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -19905,7 +19905,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the range (<literal>NULL</literal> if the
- range is empty or the lower bound is infinite).
+ range is empty or unbounded).
</para>
<para>
<literal>lower(numrange(1.1,2.2))</literal>
@@ -19923,7 +19923,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the range (<literal>NULL</literal> if the
- range is empty or the upper bound is infinite).
+ range is empty or unbounded).
</para>
<para>
<literal>upper(numrange(1.1,2.2))</literal>
@@ -19991,7 +19991,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's lower bound infinite?
+ Is the range's lower end unbounded? A +/-Infinity lower
+ bound returns false.
</para>
<para>
<literal>lower_inf('(,)'::daterange)</literal>
@@ -20008,7 +20009,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's upper bound infinite?
+ Is the range's upper end unbounded? A +/-Infinity upper
+ bound returns false.
</para>
<para>
<literal>upper_inf('(,)'::daterange)</literal>
@@ -20063,7 +20065,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the lower bound is infinite).
+ multirange is empty or unbounded).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20081,7 +20083,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the upper bound is infinite).
+ multirange is empty or unbounded).
</para>
<para>
<literal>upper('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20149,7 +20151,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's lower bound infinite?
+ Is the multirange's lower end unbounded? A +/-Infinity lower
+ bound returns false.
</para>
<para>
<literal>lower_inf('{(,)}'::datemultirange)</literal>
@@ -20166,7 +20169,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's upper bound infinite?
+ Is the multirange's upper end unbounded? A +/-Infinity upper
+ bound returns false.
</para>
<para>
<literal>upper_inf('{(,)}'::datemultirange)</literal>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-02 14:42 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 14+ messages in thread
From: Laurenz Albe @ 2023-11-02 14:42 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] range.V2.diff (3.1K, ../../687683a11c0d8bd0466cedbcb99d098c11f31f97.camel@cybertec.at/2-range.V2.diff)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c76ec52c55..c2f266ea24 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -19905,7 +19905,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the range (<literal>NULL</literal> if the
- range is empty or the lower bound is infinite).
+ range is empty or has no lower bound).
</para>
<para>
<literal>lower(numrange(1.1,2.2))</literal>
@@ -19923,7 +19923,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the range (<literal>NULL</literal> if the
- range is empty or the upper bound is infinite).
+ range is empty or has no upper bound).
</para>
<para>
<literal>upper(numrange(1.1,2.2))</literal>
@@ -19991,7 +19991,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's lower bound infinite?
+ Does the range have no lower bound? (A lower bound of
+ <literal>-Infinity</literal> returns false.)
</para>
<para>
<literal>lower_inf('(,)'::daterange)</literal>
@@ -20008,7 +20009,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the range's upper bound infinite?
+ Does the range have no upper bound? (An upper bound of
+ <literal>Infinity</literal> returns false.)
</para>
<para>
<literal>upper_inf('(,)'::daterange)</literal>
@@ -20063,7 +20065,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the lower bound is infinite).
+ multirange is empty has no lower bound).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20081,7 +20083,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
- multirange is empty or the upper bound is infinite).
+ multirange is empty or has no upper bound).
</para>
<para>
<literal>upper('{[1.1,2.2)}'::nummultirange)</literal>
@@ -20149,7 +20151,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's lower bound infinite?
+ Does the multirange have no lower bound? (A lower bound of
+ <literal>-Infinity</literal> returns false.)
</para>
<para>
<literal>lower_inf('{(,)}'::datemultirange)</literal>
@@ -20166,7 +20169,8 @@ SELECT NULLIF(value, '(none)') ...
<returnvalue>boolean</returnvalue>
</para>
<para>
- Is the multirange's upper bound infinite?
+ Does the multirange have no upper bound? (An upper bound of
+ <literal>Infinity</literal> returns false.)
</para>
<para>
<literal>upper_inf('{(,)}'::datemultirange)</literal>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-02 22:22 Bruce Momjian <bruce@momjian.us>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 14+ messages in thread
From: Bruce Momjian @ 2023-11-02 22:22 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-13 21:08 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 14+ messages in thread
From: Bruce Momjian @ 2023-11-13 21:08 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: Documentation of return values of range functions lower and upper
@ 2023-11-14 04:21 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 14+ messages in thread
From: Laurenz Albe @ 2023-11-14 04:21 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Fujii Masao <masao.fujii@oss.nttdata.com>; jani.rahkola@iki.fi; pgsql-docs@lists.postgresql.org
On Mon, 2023-11-13 at 16:08 -0500, Bruce Momjian wrote:
> Backpatched to PG 16.
Thanks!
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 14+ messages in thread
end of thread, other threads:[~2023-11-14 04:21 UTC | newest]
Thread overview: 14+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-11-11 09:25 Documentation of return values of range functions lower and upper PG Doc comments form <noreply@postgresql.org>
2020-11-11 17:19 ` Laurenz Albe <laurenz.albe@cybertec.at>
2020-11-12 08:14 ` Laurenz Albe <laurenz.albe@cybertec.at>
2020-11-18 13:49 ` Fujii Masao <masao.fujii@oss.nttdata.com>
2020-11-18 16:28 ` Laurenz Albe <laurenz.albe@cybertec.at>
2023-11-01 20:28 ` Bruce Momjian <bruce@momjian.us>
2023-11-01 20:40 ` Laurenz Albe <laurenz.albe@cybertec.at>
2023-11-01 22:03 ` Bruce Momjian <bruce@momjian.us>
2023-11-02 07:56 ` Laurenz Albe <laurenz.albe@cybertec.at>
2023-11-02 14:14 ` Bruce Momjian <bruce@momjian.us>
2023-11-02 14:42 ` Laurenz Albe <laurenz.albe@cybertec.at>
2023-11-02 22:22 ` Bruce Momjian <bruce@momjian.us>
2023-11-13 21:08 ` Bruce Momjian <bruce@momjian.us>
2023-11-14 04:21 ` Laurenz Albe <laurenz.albe@cybertec.at>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox