On Sun, Jun 13, 2021 at 9:46 PM Jonathan S. Katz <jk...@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
