From: Bruce Momjian <bruce@momjian.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Fujii Masao <masao.fujii@oss.nttdata.com>
Cc: jani.rahkola@iki.fi
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Documentation of return values of range functions lower and upper
Date: Thu, 2 Nov 2023 10:14:58 -0400
Message-ID: <ZUOu4maaCXivToUE@momjian.us> (raw)
In-Reply-To: <ed4f1dcba4aa0f1f00023a9346e2f925f3cc62c8.camel@cybertec.at>
References: <160508672127.25505.8356390205508789564@wrigleys.postgresql.org>
<53ec9f116bea9252d7fa9341e024530553656c42.camel@cybertec.at>
<16601466752e40543051369fac722c0a200bb4e6.camel@cybertec.at>
<27d690d8-0987-5f2b-a2da-fc2ec7c19e3c@oss.nttdata.com>
<02f3fa3a592fa6c1f8ec1a9f539ae376f744eb42.camel@cybertec.at>
<ZUK0-gzxmfHdDila@momjian.us>
<a0f9f8fa5de833acd7cf9e74352ef347ade6572d.camel@cybertec.at>
<ZULLQ0Zycz8PmfsT@momjian.us>
<ed4f1dcba4aa0f1f00023a9346e2f925f3cc62c8.camel@cybertec.at>
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.sgmlindex 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>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, laurenz.albe@cybertec.at, masao.fujii@oss.nttdata.com, jani.rahkola@iki.fi, pgsql-docs@lists.postgresql.org
Subject: Re: Documentation of return values of range functions lower and upper
In-Reply-To: <ZUOu4maaCXivToUE@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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