Thread: Proposal to improve uniq function documentation in intarray extension
Proposal to improve uniq function documentation in intarray extension
From
PG Doc comments form
Date:
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/14/intarray.html Description: The **uniq** function in the **intarray** extension removes **adjacent** duplicates from an integer array. The documentation[0] about this behavior is correct, but the example is a bit misleading, because it sorts the array before applying uniq. The sort can be overlooked **easily** and leads to the impression that **uniq** removes all duplicates from the array. I propse to change the example to somthing like that: uniq('{1,2,2,3,1,1}'::integer[]) → {1,2,3,1} It might be a good idea to refer to the **sort** function in case one wants to remove all duplicates. Cheers, Martin Kalcher [0] https://www.postgresql.org/docs/current/intarray.html#INTARRAY-FUNC-TABLE
PG Doc comments form <noreply@postgresql.org> writes: > The **uniq** function in the **intarray** extension removes **adjacent** > duplicates from an integer array. The documentation[0] about this behavior > is correct, but the example is a bit misleading, because it sorts the array > before applying uniq. The sort can be overlooked **easily** and leads to the > impression that **uniq** removes all duplicates from the array. > I propse to change the example to somthing like that: > uniq('{1,2,2,3,1,1}'::integer[]) → {1,2,3,1} You have a point, but the example of use with sort() is pretty useful in its own right, particularly for people for whom "blah blah | sort | uniq" is not second nature. Fortunately, there's no longer any reason we have to limit ourselves to one example. I propose this: diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index f930c08eeb..18c6f8c3ba 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -131,6 +131,11 @@ </para> <para> Removes adjacent duplicates. + Often used with <function>sort</function> to remove all duplicates. + </para> + <para> + <literal>uniq('{1,2,2,3,1,1}'::integer[])</literal> + <returnvalue>{1,2,3,1}</returnvalue> </para> <para> <literal>uniq(sort('{1,2,3,2,1}'::integer[]))</literal> regards, tom lane
Re: Proposal to improve uniq function documentation in intarray extension
From
Daniel Gustafsson
Date:
> On 3 Jun 2022, at 17:34, Tom Lane <tgl@sss.pgh.pa.us> wrote: > .. there's no longer any reason we have > to limit ourselves to one example. I propose this: > > diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml > index f930c08eeb..18c6f8c3ba 100644 > --- a/doc/src/sgml/intarray.sgml > +++ b/doc/src/sgml/intarray.sgml > @@ -131,6 +131,11 @@ > </para> > <para> > Removes adjacent duplicates. > + Often used with <function>sort</function> to remove all duplicates. > + </para> > + <para> > + <literal>uniq('{1,2,2,3,1,1}'::integer[])</literal> > + <returnvalue>{1,2,3,1}</returnvalue> > </para> > <para> > <literal>uniq(sort('{1,2,3,2,1}'::integer[]))</literal> +1 -- Daniel Gustafsson https://vmware.com/
Daniel Gustafsson <daniel@yesql.se> writes: >> On 3 Jun 2022, at 17:34, Tom Lane <tgl@sss.pgh.pa.us> wrote: >> .. there's no longer any reason we have >> to limit ourselves to one example. I propose this: > +1 Done like that, then. regards, tom lane
Thank you very much. The new documentation is way better. Am 03.06.22 um 19:55 schrieb Tom Lane: > Daniel Gustafsson <daniel@yesql.se> writes: >>> On 3 Jun 2022, at 17:34, Tom Lane <tgl@sss.pgh.pa.us> wrote: >>> .. there's no longer any reason we have >>> to limit ourselves to one example. I propose this: > >> +1 > > Done like that, then. > > regards, tom lane