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: 
 <CAJSLCQ2aNwXntHfFZdLnrAqrhPUbm7YqytobFOid5mX3VU-C5g@mail.gmail.com>
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>
Comments: In-reply-to Robert Treat <rob@xzilla.net>
	message dated "Wed, 18 Jun 2025 21:51:39 -0400"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <1391432.1750345913.1@sss.pgh.pa.us>
Date: Thu, 19 Jun 2025 11:11:53 -0400
Message-ID: <1391433.1750345913@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/1391433.1750345913%40sss.pgh.pa.us>
Precedence: bulk

Robert Treat <rob@xzilla.net> writes:
> Since they are all lower bounds, they all operate the same way, so it
> isn't quite as clear that it needs documenting. Are you thinking
> something like this?

> Returns the number of the bucket in which operand falls given an array
> listing the lower bounds (inclusive) of the buckets

Yeah, though I might write "inclusive lower bounds" rather than use
parens.  What's bugging me though is the lack of any mention of the
bucket upper bounds: you have to deduce that the upper bounds must
be exclusive if the lower bounds are inclusive.  If that's obvious
here, why is it non-obvious for the other case?  Maybe instead of
the parenthetical form you suggested, add a sentence like

    Buckets have inclusive lower bounds, and therefore exclusive
    upper bounds.

and then we could either rely on the reader remembering that,
or else repeat it, for the second form of width_bucket.

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!
I think we need to document that, perhaps along the lines of

    If low > high, the behavior is mirror-reversed, with bucket 1
    now being the one just below low, and the inclusive bounds
    now being on the upper side.

plus an example.

			regards, tom lane