Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1nx9Jv-0003G9-2o
	for pgsql-docs@arkaria.postgresql.org; Fri, 03 Jun 2022 15:34:39 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1nx9Jt-0005WZ-Ue
	for pgsql-docs@arkaria.postgresql.org; Fri, 03 Jun 2022 15:34:37 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1nx9Jt-0005WQ-ND
	for pgsql-docs@lists.postgresql.org; Fri, 03 Jun 2022 15:34:37 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1nx9Jr-0004U9-MY
	for pgsql-docs@lists.postgresql.org; Fri, 03 Jun 2022 15:34:37 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 253FYLnb219446;
	Fri, 3 Jun 2022 11:34:22 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: martin.kalcher@aboutsource.net
cc: pgsql-docs@lists.postgresql.org
Subject: Re: Proposal to improve uniq function documentation in intarray
 extension
In-reply-to: <165407884456.573551.8779012279828726162@wrigleys.postgresql.org>
References: <165407884456.573551.8779012279828726162@wrigleys.postgresql.org>
Comments: In-reply-to PG Doc comments form <noreply@postgresql.org>
	message dated "Wed, 01 Jun 2022 10:20:44 -0000"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <219444.1654270461.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Fri, 03 Jun 2022 11:34:21 -0400
Message-ID: <219445.1654270461@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/219445.1654270461%40sss.pgh.pa.us>
Precedence: bulk

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