Re: array concat, et al patch - Mailing list pgsql-patches

Tom Lane wrote:
> You're on the hook for docs fixes...

Here's a patch for the documentation updates. Please apply.

Thanks,

Joe
Index: doc/src/sgml/array.sgml
===================================================================
RCS file: /opt/src/cvs/pgsql-server/doc/src/sgml/array.sgml,v
retrieving revision 1.29
diff -c -r1.29 array.sgml
*** doc/src/sgml/array.sgml    9 Aug 2003 22:50:21 -0000    1.29
--- doc/src/sgml/array.sgml    19 Aug 2003 05:31:16 -0000
***************
*** 162,168 ****
    expression syntax is discussed in more detail in <xref
    linkend="sql-syntax-array-constructors">.
   </para>
-
   </sect2>

   <sect2>
--- 162,167 ----
***************
*** 326,334 ****
    <literal>||</literal>.
  <programlisting>
  SELECT ARRAY[1,2] || ARRAY[3,4];
!    ?column?
! ---------------
!  {{1,2},{3,4}}
  (1 row)

  SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
--- 325,333 ----
    <literal>||</literal>.
  <programlisting>
  SELECT ARRAY[1,2] || ARRAY[3,4];
!  ?column?
! -----------
!  {1,2,3,4}
  (1 row)

  SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
***************
*** 337,363 ****
   {{5,6},{1,2},{3,4}}
  (1 row)
  </programlisting>

    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:

  <programlisting>
  SELECT array_dims(1 || ARRAY[2,3]);
   array_dims
  ------------
   [0:2]
  (1 row)
  </programlisting>
   </para>

--- 336,403 ----
   {{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.
!  </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,394 ****
  (1 row)

  SELECT array_cat(ARRAY[1,2], ARRAY[3,4]);
!    array_cat
! ---------------
!  {{1,2},{3,4}}
  (1 row)

  SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]);
--- 426,434 ----
  (1 row)

  SELECT array_cat(ARRAY[1,2], ARRAY[3,4]);
!  array_cat
! -----------
!  {1,2,3,4}
  (1 row)

  SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]);
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /opt/src/cvs/pgsql-server/doc/src/sgml/func.sgml,v
retrieving revision 1.167
diff -c -r1.167 func.sgml
*** doc/src/sgml/func.sgml    17 Aug 2003 04:52:41 -0000    1.167
--- doc/src/sgml/func.sgml    19 Aug 2003 04:32:27 -0000
***************
*** 7093,7099 ****
      <entry> <literal>||</literal> </entry>
      <entry>array-to-array concatenation</entry>
      <entry><literal>ARRAY[1,2,3] || ARRAY[4,5,6]</literal></entry>
!     <entry><literal>{{1,2,3},{4,5,6}}</literal></entry>
         </row>

         <row>
--- 7093,7099 ----
      <entry> <literal>||</literal> </entry>
      <entry>array-to-array concatenation</entry>
      <entry><literal>ARRAY[1,2,3] || ARRAY[4,5,6]</literal></entry>
!     <entry><literal>{1,2,3,4,5,6}</literal></entry>
         </row>

         <row>
***************
*** 7121,7126 ****
--- 7121,7131 ----
      </table>

    <para>
+    See <xref linkend="arrays"> for more details with regard to operator
+    behavior.
+   </para>
+
+   <para>
     <xref linkend="array-functions-table"> shows the functions
     available for use with array types. See <xref linkend="arrays">
     for more discussion and examples for the use of these functions.
***************
*** 7167,7173 ****
       for <literal>NULL</literal> inputs
      </entry>
      <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5,6])</literal></entry>
!     <entry><literal>{{1,2,3},{4,5,6}}</literal></entry>
         </row>
         <row>
      <entry>
--- 7172,7178 ----
       for <literal>NULL</literal> inputs
      </entry>
      <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5,6])</literal></entry>
!     <entry><literal>{1,2,3,4,5,6}</literal></entry>
         </row>
         <row>
      <entry>
Index: doc/src/sgml/syntax.sgml
===================================================================
RCS file: /opt/src/cvs/pgsql-server/doc/src/sgml/syntax.sgml,v
retrieving revision 1.82
diff -c -r1.82 syntax.sgml
*** doc/src/sgml/syntax.sgml    14 Aug 2003 23:13:27 -0000    1.82
--- doc/src/sgml/syntax.sgml    19 Aug 2003 05:21:49 -0000
***************
*** 1271,1276 ****
--- 1271,1298 ----
    </para>

    <para>
+     Multidimensional array constructor elements can be anything yielding
+     an array of the proper kind, not only a sub-array construct. For example:
+ <programlisting>
+ create table arr(f1 int[], f2 int[]);
+ CREATE TABLE
+ insert into arr values (ARRAY[[1,2],[3,4]],ARRAY[[5,6],[7,8]]);
+ INSERT 2635544 1
+ select ARRAY[f1,f2] from arr;
+              array
+ -------------------------------
+  {{{1,2},{3,4}},{{5,6},{7,8}}}
+ (1 row)
+
+ select ARRAY['{{1,2},{3,4}}'::int[],'{{5,6},{7,8}}'::int[]];
+              array
+ -------------------------------
+  {{{1,2},{3,4}},{{5,6},{7,8}}}
+ (1 row)
+ </programlisting>
+   </para>
+
+   <para>
     It is also possible to construct an array from the results of a
     subquery.  In this form, the array constructor is written with the
     keyword <literal>ARRAY</literal> followed by a parenthesized (not