On Sun, Jun 13, 2021 at 9:46 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 6/13/21 11:49 AM, Justin Pryzby wrote:
> > On Sun, Jun 13, 2021 at 11:25:05AM -0400, Jonathan S. Katz wrote:
> >> On 6/13/21 10:57 AM, Zhihong Yu wrote:
> >>> +/* Turn multirange into a set of ranges */
> >>>
> >>> set of ranges: sequence of ranges
> >>
> >> I believe "set of ranges" is accurate here, as the comparable return is
> >> a "SETOF rangetype". Sequences are objects unto themselves.
> >>
> >
> > I believe the point was that (in mathematics) a "set" is unordered, and a
> > sequence is ordered. Also, a "setof" tuples in postgres can contain
> > duplicates.
>
> The comment in question is part of the header for the
> "multirange_unnest" function in the code and AFAICT it is accurate: it
> is returning a "set of" ranges as it's literally calling into the
> set-returning function framework.
>
> I would suggest leaving it as is.
+1
> > The docs say "The ranges are read out in storage order (ascending).", so I
> > think this is just a confusion between what "set" means in math vs in postgres.
>
> This is nearly identical to the language in the array unnest[1]
> function, which is what I believed Alexander borrowed from:
Yes, that's it! :)
> "Expands an array into a set of rows. The array's elements are read out
> in storage order."
>
> If we tweaked the multirange "unnest" function, we could change it to:
>
> + <para>
> + Expands a multirange into a set of rows.
> + The ranges are read out in storage order (ascending).
> + </para>
>
> to match what the array "unnest" function docs, or
>
> + <para>
> + Expands a multirange into a set of rows that each
> + contain an individual range.
> + The ranges are read out in storage order (ascending).
> + </para>
>
> to be a bit more specific. However, I think this is also bordering on
> overengineering the text, given there has been a lack of feedback on the
> "unnest" array function description being confusing.
I think it's not necessarily to say about rows here. Our
documentation already has already a number of examples, where we
describe set of returned values without speaking about rows including:
json_array_elements, json_array_elements_text, json_object_keys,
pg_listening_channels, pg_tablespace_databases...
------
Regards,
Alexander Korotkov