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

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.