PostgreSQL › PostgreSQL - docs

Documentation of return values of range functions lower and upper

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

5 messages Options

apt.postgresql.org Repository Update

Documentation of return values of range functions lower and upper

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.

Laurenz Albe

Re: 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

Laurenz Albe

Re: Documentation of return values of range functions lower and upper

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

0001-Improve-upper-lower-documentation-for-ranges.patch (1K) Download Attachment

Fujii Masao-4

Re: Documentation of return values of range functions lower and upper

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

Laurenz Albe

Re: Documentation of return values of range functions lower and upper

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