Updates for array documentation, from Joe Conway.

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index fabf2e732cd9ae9b74aa82bbaf7fec37cf4c9e41..fa241d0e323b0c71f0e437700951a1db823aa3ad 100644 (file)
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Arrays
@@ -162,7 +162,6 @@ ERROR:  multidimensional arrays must have array expressions with matching dimens
   expression syntax is discussed in more detail in 
   linkend="sql-syntax-array-constructors">.
  
-
  
 
  
@@ -326,9 +325,9 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
   ||.
 
 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)
 
+ 
 
+ 
   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
   N-dimensional arrays, or an N-dimensional
-  and an N+1-dimensional array. In the former case, the two
-  N-dimension arrays become outer elements of an
-  N+1-dimensional array. In the latter, the
-  N-dimensional array is added as either the first or last
-  outer element of the 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 N+1-dimensional array.
+ 
 
+ 
+  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:
 
 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)
+
+ 
+
+ 
+  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:
+
+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)
+
+ 
+
+ 
+  When an N-dimensional array is pushed on to the beginning
+  or end of an N+1-dimensional array, the result is
+  analogous to the element-array case above. Each N-dimensional
+  sub-array is essentially an element of the N+1-dimensional
+  array's outer dimension. For example:
+
+SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
+ array_dims
+------------
+ [0:2][1:2]
+(1 row)
 
  
 
@@ -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]);


diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml

index 7fb101f90f5c8edd4cabe660f20ec649bf6fd0d6..b19a5c97ac55eb2582892e9ca5704971435179b2 100644 (file)

--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 
 
@@ -7032,7 +7032,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
 
   
     shows the operators
-   available for the array types.
+   available for array types.
   
 
     
@@ -7093,7 +7093,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
     || 
    array-to-array concatenation
    ARRAY[1,2,3] || ARRAY[4,5,6]
-   {{1,2,3},{4,5,6}}
+   {1,2,3,4,5,6}
        
 
        
@@ -7120,6 +7120,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
      
     
 
+  
+   See  for more details about array operator
+   behavior.
+  
+
   
     shows the functions
    available for use with array types. See 
@@ -7167,7 +7172,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
      for NULL inputs
     
    array_cat(ARRAY[1,2,3], ARRAY[4,5,6])
-   {{1,2,3},{4,5,6}}
+   {1,2,3,4,5,6}
        
        
    


diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml

index 8151c63c8c392f2b8d6d73bf90115777810bc83c..8372fa6b3486d8b61593b785cd9a7be12d4d79fc 100644 (file)

--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 
 
 
@@ -1270,6 +1270,23 @@ SELECT ARRAY[[1,2],[3,4]];
     at the same level must produce sub-arrays of identical dimensions.
   
 
+  
+    Multidimensional array constructor elements can be anything yielding
+    an array of the proper kind, not only a sub-ARRAY construct.
+    For example:
+
+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, '{{9,10},{11,12}}'::int[]] from arr;
+                     array
+------------------------------------------------
+ {{{1,2},{3,4}},{{5,6},{7,8}},{{9,10},{11,12}}}
+(1 row)
+
+  
+
   
    It is also possible to construct an array from the results of a
    subquery.  In this form, the array constructor is written with the

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7fb101f90f5c8edd4cabe660f20ec649bf6fd0d6..b19a5c97ac55eb2582892e9ca5704971435179b2 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 
 
@@ -7032,7 +7032,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
 
   
     shows the operators
-   available for the array types.
+   available for array types.
   
 
     
@@ -7093,7 +7093,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
     || 
    array-to-array concatenation
    ARRAY[1,2,3] || ARRAY[4,5,6]
-   {{1,2,3},{4,5,6}}
+   {1,2,3,4,5,6}
        
 
        
@@ -7120,6 +7120,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
      
     
 
+  
+   See  for more details about array operator
+   behavior.
+  
+
   
     shows the functions
    available for use with array types. See 
@@ -7167,7 +7172,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
      for NULL inputs
     
    array_cat(ARRAY[1,2,3], ARRAY[4,5,6])
-   {{1,2,3},{4,5,6}}
+   {1,2,3,4,5,6}
        
        
    

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 8151c63c8c392f2b8d6d73bf90115777810bc83c..8372fa6b3486d8b61593b785cd9a7be12d4d79fc 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 
 
 
@@ -1270,6 +1270,23 @@ SELECT ARRAY[[1,2],[3,4]];
     at the same level must produce sub-arrays of identical dimensions.
   
 
+  
+    Multidimensional array constructor elements can be anything yielding
+    an array of the proper kind, not only a sub-ARRAY construct.
+    For example:
+
+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, '{{9,10},{11,12}}'::int[]] from arr;
+                     array
+------------------------------------------------
+ {{{1,2},{3,4}},{{5,6},{7,8}},{{9,10},{11,12}}}
+(1 row)
+
+  
+
   
    It is also possible to construct an array from the results of a
    subquery.  In this form, the array constructor is written with the