Date: Wed, 1 Nov 2023 18:03:47 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Fujii Masao <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
Message-ID: <ZULLQ0Zycz8PmfsT@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>
 <a0f9f8fa5de833acd7cf9e74352ef347ade6572d.camel@cybertec.at>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="Q9b1z+4l7YDmP0e0"
Content-Disposition: inline
In-Reply-To: <a0f9f8fa5de833acd7cf9e74352ef347ade6572d.camel@cybertec.at>
Archived-At: 
 <https://www.postgresql.org/message-id/ZULLQ0Zycz8PmfsT%40momjian.us>
Precedence: bulk


--Q9b1z+4l7YDmP0e0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

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.

--Q9b1z+4l7YDmP0e0
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="range.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>

--Q9b1z+4l7YDmP0e0--