From 5acc7730c8c93d5755bc6a0bf36df407f48b2b27 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 9 Jul 2015 18:50:31 -0400
Subject: [PATCH] Improve documentation about array concat operator vs.
 underlying functions.

The documentation implied that there was seldom any reason to use the
array_append, array_prepend, and array_cat functions directly.  But that's
not really true, because they can help make it clear which case is meant,
which the || operator can't do since it's overloaded to represent all three
cases.  Add some discussion and examples illustrating the potentially
confusing behavior that can ensue if the parser misinterprets what was
meant.

Per a complaint from Michael Herold.  Back-patch to 9.2, which is where ||
started to behave this way.
---
 doc/src/sgml/array.sgml | 47 +++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 5e4130aa6d..4385a09cd9 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -346,7 +346,7 @@ SELECT array_length(schedule, 1) FROM sal_emp WHERE name = 'Carol';
 <programlisting>
 SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol';
 
- cardinality 
+ cardinality
 -------------
            4
 (1 row)
@@ -494,11 +494,7 @@ SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
   <function>array_prepend</function>, <function>array_append</function>,
   or <function>array_cat</function>. The first two only support one-dimensional
   arrays, but <function>array_cat</function> supports multidimensional arrays.
-
-  Note that the concatenation operator discussed above is preferred over
-  direct use of these functions. In fact, these functions primarily exist for use
-  in implementing the concatenation operator. However, they might be directly
-  useful in the creation of user-defined aggregates. Some examples:
+  Some examples:
 
 <programlisting>
 SELECT array_prepend(1, ARRAY[2,3]);
@@ -531,6 +527,45 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
  {{5,6},{1,2},{3,4}}
 </programlisting>
  </para>
+
+ <para>
+  In simple cases, the concatenation operator discussed above is preferred
+  over direct use of these functions.  However, because the concatenation
+  operator is overloaded to serve all three cases, there are situations where
+  use of one of the functions is helpful to avoid ambiguity.  For example
+  consider:
+
+<programlisting>
+SELECT ARRAY[1, 2] || '{3, 4}';  -- the untyped literal is taken as an array
+ ?column?
+-----------
+ {1,2,3,4}
+
+SELECT ARRAY[1, 2] || '7';                 -- so is this one
+ERROR:  malformed array literal: "7"
+
+SELECT ARRAY[1, 2] || NULL;                -- so is an undecorated NULL
+ ?column?
+----------
+ {1,2}
+(1 row)
+
+SELECT array_append(ARRAY[1, 2], NULL);    -- this might have been meant
+ array_append
+--------------
+ {1,2,NULL}
+</programlisting>
+
+  In the examples above, the parser sees an integer array on one side of the
+  concatenation operator, and a constant of undetermined type on the other.
+  The heuristic it uses to resolve the constant's type is to assume it's of
+  the same type as the operator's other input &mdash; in this case,
+  integer array.  So the concatenation operator is presumed to
+  represent <function>array_cat</>, not <function>array_append</>.  When
+  that's the wrong choice, it could be fixed by casting the constant to the
+  array's element type; but explicit use of <function>array_append</> might
+  be a preferable solution.
+ </para>
  </sect2>
 
  <sect2 id="arrays-searching">