Обсуждение: Proposal to improve uniq function documentation in intarray extension

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

> 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