Updates for array documentation, from Joe Conway.

doc/src/sgml/array.sgml

@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.29 2003/08/09 22:50:21 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.30 2003/08/19 06:06:43 tgl Exp $ -->
 
 <sect1 id="arrays">
  <title>Arrays</title>
@@ -162,7 +162,6 @@ ERROR:  multidimensional arrays must have array expressions with matching dimens
   expression syntax is discussed in more detail in <xref
   linkend="sql-syntax-array-constructors">.
  </para>
-
  </sect2>
 
  <sect2>
@@ -326,9 +325,9 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
   <literal>||</literal>.
 <programlisting>
 SELECT ARRAY[1,2] || ARRAY[3,4];
-   ?column?
----------------
- {{1,2},{3,4}}
+ ?column?
+-----------
+ {1,2,3,4}
 (1 row)
 
 SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
@@ -337,27 +336,68 @@ SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
  {{5,6},{1,2},{3,4}}
 (1 row)
 </programlisting>
+ </para>
 
+ <para>
   The concatenation operator allows a single element to be pushed on to the
   beginning or end of a one-dimensional array. It also accepts two
   <replaceable>N</>-dimensional arrays, or an <replaceable>N</>-dimensional
-  and an <replaceable>N+1</>-dimensional array. In the former case, the two
-  <replaceable>N</>-dimension arrays become outer elements of an
-  <replaceable>N+1</>-dimensional array. In the latter, the
-  <replaceable>N</>-dimensional array is added as either the first or last
-  outer element of the <replaceable>N+1</>-dimensional array.
-
-  When extending an array by concatenation, the subscripts of its existing
-  elements are preserved. For example, when pushing
-  onto the beginning of an array with one-based subscripts, the resulting
-  array has zero-based subscripts:
+  and an <replaceable>N+1</>-dimensional array.
+ </para>
 
+ <para>
+  When a single element is pushed on to the beginning of a one-dimensional
+  array, the result is an array with a lower bound subscript equal to
+  the righthand operand's lower bound subscript, minus one. When a single
+  element is pushed on to the end of a one-dimensional array, the result is
+  an array retaining the lower bound of the lefthand operand. For example:
 <programlisting>
 SELECT array_dims(1 || ARRAY[2,3]);
  array_dims
 ------------
  [0:2]
 (1 row)
+
+SELECT array_dims(ARRAY[1,2] || 3);
+ array_dims
+------------
+ [1:3]
+(1 row)
+</programlisting>
+ </para>
+
+ <para>
+  When two arrays with an equal number of dimensions are concatenated, the
+  result retains the lower bound subscript of the lefthand operand's outer
+  dimension. The result is an array comprising every element of the lefthand
+  operand followed by every element of the righthand operand. For example:
+<programlisting>
+SELECT array_dims(ARRAY[1,2] || ARRAY[3,4,5]);
+ array_dims
+------------
+ [1:5]
+(1 row)
+
+SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]);
+ array_dims
+------------
+ [1:5][1:2]
+(1 row)
+</programlisting>
+ </para>
+
+ <para>
+  When an <replaceable>N</>-dimensional array is pushed on to the beginning
+  or end of an <replaceable>N+1</>-dimensional array, the result is
+  analogous to the element-array case above. Each <replaceable>N</>-dimensional
+  sub-array is essentially an element of the <replaceable>N+1</>-dimensional
+  array's outer dimension. For example:
+<programlisting>
+SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
+ array_dims
+------------
+ [0:2][1:2]
+(1 row)
 </programlisting>
  </para>
 
@@ -386,9 +426,9 @@ SELECT array_append(ARRAY[1,2], 3);
 (1 row)
 
 SELECT array_cat(ARRAY[1,2], ARRAY[3,4]);
-   array_cat
----------------
- {{1,2},{3,4}}
+ array_cat
+-----------
+ {1,2,3,4}
 (1 row)
 
 SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]);