8000 Doc: improve documentation about width_bucket(). · postgres/postgres@34a6c67 · GitHub
[go: up one dir, main page]
Skip to content

Commit 34a6c67

Browse files
tglsfdctglsfdc
committed
Doc: improve documentation about width_bucket().
Specify whether the bucket bounds are inclusive or exclusive, and improve some other vague language. Explain the behavior that occurs when the "low" bound is greater than the "high" bound. Make width_bucket_numeric's comment more like that for width_bucket_float8, in particular noting that infinite bounds are rejected (since they became possible in v14). Reported-by: Ben Peachey Higdon <bpeacheyhigdon@gmail.com> Author: Robert Treat <rob@xzilla.net> Co-authored-by: Tom Lane <tgl@sss.pgh.pa.us> Reviewed-by: Dean Rasheed <dean.a.rasheed@gmail.com> Discussion: https://postgr.es/m/2BD74F86-5B89-4AC1-8F13-23CED3546AC1@gmail.com Backpatch-through: 13
1 parent 4b66cb1 commit 34a6c67

File tree

3 files changed

+19
-9
lines changed

3 files changed

+19
-9
lines changed

‎doc/src/sgml/func.sgml

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1788,13 +1788,23 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
17881788
which <parameter>operand</parameter> falls in a histogram
17891789
having <parameter>count</parameter> equal-width buckets spanning the
17901790
range <parameter>low</parameter> to <parameter>high</parameter>.
1791-
Returns <literal>0</literal>
1791+
The buckets have inclusive lower bounds and exclusive upper bounds.
1792+
Returns <literal>0</literal> for an input less
1793+
than <parameter>low</parameter>,
17921794
or <literal><parameter>count</parameter>+1</literal> for an input
1793-
outside that range.
1795+
greater than or equal to <parameter>high</parameter>.
1796+
If <parameter>low</parameter> &gt; <parameter>high</parameter>,
1797+
the behavior is mirror-reversed, with bucket <literal>1</literal>
1798+
now being the one just below <parameter>low</parameter>, and the
1799+
inclusive bounds now being on the upper side.
17941800
</para>
17951801
<para>
17961802
<literal>width_bucket(5.35, 0.024, 10.06, 5)</literal>
17971803
<returnvalue>3</returnvalue>
1804+
</para>
1805+
<para>
1806+
<literal>width_bucket(9, 10, 0, 10)</literal>
1807+
<returnvalue>2</returnvalue>
17981808
</para></entry>
17991809
</row>
18001810

@@ -1806,8 +1816,8 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
18061816
<para>
18071817
Returns the number of the bucket in
18081818
which <parameter>operand</parameter> falls given an array listing the
1809-
lower bounds of the buckets. Returns <literal>0</literal> for an
1810-
input less than the first lower
1819+
inclusive lower bounds of the buckets.
1820+
Returns <literal>0</literal> for an input less than the first lower
18111821
bound. <parameter>operand</parameter> and the array elements can be
18121822
of any type having standard comparison operators.
18131823
The <parameter>thresholds</parameter> array <emphasis>must be

‎src/backend/utils/adt/float.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3918,8 +3918,8 @@ float84ge(PG_FUNCTION_ARGS)
39183918
* in the histogram. width_bucket() returns an integer indicating the
39193919
* bucket number that 'operand' belongs to in an equiwidth histogram
39203920
* with the specified characteristics. An operand smaller than the
3921-
* lower bound is assigned to bucket 0. An operand greater than the
3922-
* upper bound is assigned to an additional bucket (with number
3921+
* lower bound is assigned to bucket 0. An operand greater than or equal
3922+
* to the upper bound is assigned to an additional bucket (with number
39233923
* count+1). We don't allow "NaN" for any of the float8 inputs, and we
39243924
* don't allow either of the histogram bounds to be +/- infinity.
39253925
*/

‎src/backend/utils/adt/numeric.c

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1495,9 +1495,9 @@ generate_series_step_numeric(PG_FUNCTION_ARGS)
14951495
* in the histogram. width_bucket() returns an integer indicating the
14961496
* bucket number that 'operand' belongs to in an equiwidth histogram
14971497
* with the specified characteristics. An operand smaller than the
1498-
* lower bound is assigned to bucket 0. An operand greater than the
1499-
* upper bound is assigned to an additional bucket (with number
1500-
* count+1). We don't allow "NaN" for any of the numeric arguments.
1498+
* lower bound is assigned to bucket 0. An operand greater than or equal
1499+
* to the upper bound is assigned to an additional bucket (with number
1500+
* count+1). We don't allow "NaN" for any of the numeric inputs.
15011501
*/
15021502
Datum
15031503
width_bucket_numeric(PG_FUNCTION_ARGS)

0 commit comments

Comments
 (0)
0