postgres.git / summary / log / commit / refs

commit    216bcf583802011365b8bb038b4e73f143e857b2
Author:   Tom Lane <tgl@sss.pgh.pa.us>
Date:     Mon Sep 23 16:37:04 2019 +0000
First released in: 13.0, 9.4.25, 9.5.20, 9.6.16, 10.11, 11.6, 12.0

    Doc: clarify handling of duplicate elements in array containment tests.
    
    The array <@ and @> operators do not worry about duplicates: if every
    member of array X matches some element of array Y, then X is contained
    in Y, even if several members of X get matched to the same Y member.
    This was not explicitly stated in the docs though, so improve matters.
    
    Discussion: https://postgr.es/m/156614120484.1310.310161642239149585@wrigleys.postgresql.org


 doc/src/sgml/func.sgml | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index f5c1db6873d..432dbad8684 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14004,14 +14004,14 @@ SELECT NULLIF(value, '(none)') ...
        <row>
         <entry> <literal>@&gt;</literal> </entry>
         <entry>contains</entry>
-        <entry><literal>ARRAY[1,4,3] @&gt; ARRAY[3,1]</literal></entry>
+        <entry><literal>ARRAY[1,4,3] @&gt; ARRAY[3,1,3]</literal></entry>
         <entry><literal>t</literal></entry>
        </row>
 
        <row>
         <entry> <literal>&lt;@</literal> </entry>
         <entry>is contained by</entry>
-        <entry><literal>ARRAY[2,7] &lt;@ ARRAY[1,7,4,2,6]</literal></entry>
+        <entry><literal>ARRAY[2,2,7] &lt;@ ARRAY[1,7,4,2,6]</literal></entry>
         <entry><literal>t</literal></entry>
        </row>
 
@@ -14054,8 +14054,10 @@ SELECT NULLIF(value, '(none)') ...
     </table>
 
   <para>
-   Array comparisons compare the array contents element-by-element,
-   using the default B-tree comparison function for the element data type.
+   The array ordering operators (<literal>&lt;</literal>,
+   <literal>&gt;=</literal>, etc) compare the array contents
+   element-by-element, using the default B-tree comparison function for
+   the element data type, and sort based on the first difference.
    In multidimensional arrays the elements are visited in row-major order
    (last subscript varies most rapidly).
    If the contents of two arrays are equal but the dimensionality is
@@ -14066,6 +14068,15 @@ SELECT NULLIF(value, '(none)') ...
    number of dimensions or subscript ranges were different.)
   </para>
 
+  <para>
+   The array containment operators (<literal>&lt;@</literal>
+   and <literal>@&gt;</literal>) consider one array to be contained in
+   another one if each of its elements appears in the other one.
+   Duplicates are not treated specially, thus <literal>ARRAY[1]</literal>
+   and <literal>ARRAY[1,1]</literal> are each considered to contain the
+   other.
+  </para>
+
   <para>
    See <xref linkend="arrays"/> for more details about array operator
    behavior.  See <xref linkend="indexes-types"/> for more details about
@@ -18223,7 +18234,7 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
        <row>
         <entry> <literal>@&gt;</literal> </entry>
         <entry>contains element</entry>
-        <entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*w/hobbes'::aclitem</literal></entry>
+        <entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @&gt; 'calvin=r*w/hobbes'::aclitem</literal></entry>
         <entry><literal>t</literal></entry>
        </row>
 


[parent: a25fb9ceb1a6]