Fix assorted corner-case bugs in contrib/intarray.

The array containment operators now behave per mathematical expectation
for empty arrays (ie, an empty array is contained in anything).
Both these operators and the query_int operators now work as expected in
GiST and GIN index searches, rather than having corner cases where the
index searches gave different answers.

Also, fix unexpected failures where the operators would claim that an array
contained nulls, when in fact there was no longer any null present (similar
to bug #5784).  The restriction to not have nulls is still there, as
removing it would take a lot of added code complexity and probably slow
things down significantly.

Also, remove the arbitrary restriction to 1-D arrays; unlike the other
restriction, this was buying us nothing performance-wise.

Assorted cosmetic improvements and marginal performance improvements, too.

1 files changed, 18 insertions, 9 deletions

diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml
index 1cf72a12010..449878d6716 100644
--- a/doc/src/sgml/intarray.sgml
+++ b/doc/src/sgml/intarray.sgml
@@ -9,10 +9,21 @@
 
  <para>
   The <filename>intarray</> module provides a number of useful functions
-  and operators for manipulating one-dimensional arrays of integers.
+  and operators for manipulating null-free arrays of integers.
   There is also support for indexed searches using some of the operators.
  </para>
 
+ <para>
+  All of these operations will throw an error if a supplied array contains any
+  NULL elements.
+ </para>
+
+ <para>
+  Many of these operations are only sensible for one-dimensional arrays.
+  Although they will accept input arrays of more dimensions, the data is
+  treated as though it were a linear array in storage order.
+ </para>
+
  <sect2>
   <title><filename>intarray</> Functions and Operators</title>
 
@@ -211,14 +222,12 @@
   </para>
 
   <para>
-   The containment operators <literal>@&gt;</> and <literal>&lt;@</> are
-   approximately equivalent to <productname>PostgreSQL</>'s built-in operators
-   of the same names, except that they work only on integer arrays while the
-   built-in operators work for any array type.  An important difference is
-   that <filename>intarray</>'s operators do not consider an empty array to be
-   contained in anything else.  This is consistent with the behavior of
-   GIN-indexed queries, but not with the usual mathematical definition of
-   containment.
+   The operators <literal>&amp;&amp;</>, <literal>@&gt;</> and
+   <literal>&lt;@</> are equivalent to <productname>PostgreSQL</>'s built-in
+   operators of the same names, except that they work only on integer arrays
+   that do not contain nulls, while the built-in operators work for any array
+   type.  This restriction makes them faster than the built-in operators
+   in many cases.
   </para>
 
   <para>