Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1uSj8x-00CHov-CD
	for pgsql-docs@arkaria.postgresql.org; Fri, 20 Jun 2025 21:19:27 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.94.2)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1uSj8v-004Pxe-Da
	for pgsql-docs@arkaria.postgresql.org; Fri, 20 Jun 2025 21:19:26 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.94.2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1uSj8v-004PxW-5O
	for pgsql-docs@lists.postgresql.org; Fri, 20 Jun 2025 21:19:25 +0000
Received: from sss.pgh.pa.us ([68.162.161.243])
	by magus.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1uSj8t-003DHW-1g
	for pgsql-docs@lists.postgresql.org;
	Fri, 20 Jun 2025 21:19:25 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 55KLJLii2525555;
	Fri, 20 Jun 2025 17:19:21 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Treat <rob@xzilla.net>
cc: Ben Peachey Higdon <bpeacheyhigdon@gmail.com>,
        pgsql-docs@lists.postgresql.org
Subject: Re: Document if width_bucket's low and high are inclusive/exclusive
In-reply-to: <1391433.1750345913@sss.pgh.pa.us>
References: <2BD74F86-5B89-4AC1-8F13-23CED3546AC1@gmail.com>
 <CABV9wwPh9+JAYBudAhTY8yPj5VJACA_FpHfEAaHMX1s4z05VkQ@mail.gmail.com>
 <1167135.1750277532@sss.pgh.pa.us>
 <CAJSLCQ2aNwXntHfFZdLnrAqrhPUbm7YqytobFOid5mX3VU-C5g@mail.gmail.com>
 <1391433.1750345913@sss.pgh.pa.us>
Comments: In-reply-to Tom Lane <tgl@sss.pgh.pa.us>
	message dated "Thu, 19 Jun 2025 11:11:53 -0400"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <2525476.1750454297.0@sss.pgh.pa.us>
Date: Fri, 20 Jun 2025 17:19:21 -0400
Message-ID: <2525554.1750454361@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/2525554.1750454361%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <2525476.1750454297.1@sss.pgh.pa.us>

I wrote:
> Another thing I just remembered (think I knew it once) is the
> behavior of the first form when low > high.  It's not an error!

So concretely, how about the attached?  In addition to what we
mentioned so far, I made the sentence about out-of-range cases
more explicit.

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff;
	name*0="v2-0001-Document-width_bucket-range-as-inclusive-exclusiv.p";
	name*1="atch"; charset="us-ascii"
Content-ID: <2525476.1750454297.2@sss.pgh.pa.us>
Content-Description: 
 v2-0001-Document-width_bucket-range-as-inclusive-exclusiv.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 8d7d9a2f3e8..11676b63c82 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1824,13 +1824,24 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -=
- detect at least one null in
         which <parameter>operand</parameter> falls in a histogram
         having <parameter>count</parameter> equal-width buckets spanning =
the
         range <parameter>low</parameter> to <parameter>high</parameter>.
-        Returns <literal>0</literal>
+        The buckets have inclusive lower bounds, and therefore exclusive
+        upper bounds.
+        Returns <literal>0</literal> for an input less
+        than <parameter>low</parameter>,
         or <literal><parameter>count</parameter>+1</literal> for an input
-        outside that range.
+        greater than or equal to <parameter>high</parameter>.
+        If <parameter>low</parameter> &gt; <parameter>high</parameter>,
+        the behavior is mirror-reversed, with bucket <literal>1</literal>
+        now being the one just below <parameter>low</parameter>, and the
+        inclusive bounds now being on the upper side.
        </para>
        <para>
         <literal>width_bucket(5.35, 0.024, 10.06, 5)</literal>
         <returnvalue>3</returnvalue>
+       </para>
+       <para>
+        <literal>width_bucket(9, 10, 0, 10)</literal>
+        <returnvalue>2</returnvalue>
        </para></entry>
       </row>
 =

@@ -1842,8 +1853,8 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- =
detect at least one null in
        <para>
         Returns the number of the bucket in
         which <parameter>operand</parameter> falls given an array listing=
 the
-        lower bounds of the buckets.  Returns <literal>0</literal> for an
-        input less than the first lower
+        inclusive lower bounds of the buckets.
+        Returns <literal>0</literal> for an input less than the first low=
er
         bound.  <parameter>operand</parameter> and the array elements can=
 be
         of any type having standard comparison operators.
         The <parameter>thresholds</parameter> array <emphasis>must be

------- =_aaaaaaaaaa0--