Message-ID: <a0f9f8fa5de833acd7cf9e74352ef347ade6572d.camel@cybertec.at>
Subject: Re: Documentation of return values of range functions lower and
 upper
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Bruce Momjian <bruce@momjian.us>
Cc: Fujii Masao <masao.fujii@oss.nttdata.com>, jani.rahkola@iki.fi,
	pgsql-docs@lists.postgresql.org
Date: Wed, 01 Nov 2023 21:40:43 +0100
In-Reply-To: <ZUK0-gzxmfHdDila@momjian.us>
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>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.48.4 (3.48.4-1.fc38) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/a0f9f8fa5de833acd7cf9e74352ef347ade6572d.camel%40cybertec.at>
Precedence: bulk

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 st=
ates 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 infin=
ity 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
> > >=20
> > > I agree this description looks a bit confusing. But according to the =
section
> > > "Infinite (Unbounded) Ranges" (*1), we already call "lower/upper boun=
d
> > > omitted" just infinite. So I don't think the current description is i=
ncorrect.
> > >=20
> > > (*1)
> > > https://www.postgresql.org/docs/devel/rangetypes.html#RANGETYPES-INFI=
NITE
> >=20
> > That is correct, but I'd argue that it would be better to clarify the p=
aragraph too,
> > in particular:
> >=20
> >   The functions lower_inf and upper_inf test for infinite lower and upp=
er bounds of a range, respectively.
> >=20
> > should better read
> >=20
> >   The functions lower_inf and upper_inf test for omitted lower and uppe=
r bounds of a range, respectively.
> >=20
> > The rest of the paragraph is pretty unambiguous.
> >=20
> >=20
> > Independent of this, I think that my patch for "upper" and "lower" woul=
d make the
> > documentation clearer.
>=20
> Yes, I agree this documentation needs help.
>=20
> 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.
>=20
> 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.
>=20
> 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.  Th=
is is
a bit confusing, since NULL is typically used for unknown or undefined valu=
es.

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

Yours,
Laurenz Albe