Index: doc/src/sgml/array.sgml
===================================================================
RCS file: /opt/src/cvs/pgsql-server/doc/src/sgml/array.sgml,v
retrieving revision 1.25
diff -c -r1.25 array.sgml
*** doc/src/sgml/array.sgml 13 Mar 2003 01:30:26 -0000 1.25
--- doc/src/sgml/array.sgml 4 May 2003 05:14:04 -0000
***************
*** 9,15 ****
PostgreSQL allows columns of a table to be
! defined as variable-length multidimensional arrays. Arrays of any
built-in type or user-defined type can be created.
--- 9,15 ----
PostgreSQL allows columns of a table to be
! defined as variable-length multi-dimensional arrays. Arrays of any
built-in type or user-defined type can be created.
***************
*** 60,73 ****
! A limitation of the present array implementation is that individual
! elements of an array cannot be SQL null values. The entire array can be set
! to null, but you can't have an array with some elements null and some
! not. Fixing this is on the to-do list.
--- 60,133 ----
+
+ A limitation of the present array implementation is that individual
+ elements of an array cannot be SQL null values. The entire array can be set
+ to null, but you can't have an array with some elements null and some
+ not.
+
+
+ This can lead to surprising results. For example, the result of the
+ previous two inserts looks like this:
+
+ SELECT * FROM sal_emp;
+ name | pay_by_quarter | schedule
+ -------+---------------------------+--------------------
+ Bill | {10000,10000,10000,10000} | {{meeting},{""}}
+ Carol | {20000,25000,25000,25000} | {{talk},{meeting}}
+ (2 rows)
+
+ Because the [2][2] element of
+ schedule is missing in each of the
+ INSERT statements, the [1][2]
+ element is discarded.
+
+
+
+
+ Fixing this is on the to-do list.
+
+
+
+
+ The ARRAY expression syntax may also be used:
+
+ INSERT INTO sal_emp
+ VALUES ('Bill',
+ ARRAY[10000, 10000, 10000, 10000],
+ ARRAY[['meeting', 'lunch'], ['','']]);
+
+ INSERT INTO sal_emp
+ VALUES ('Carol',
+ ARRAY[20000, 25000, 25000, 25000],
+ ARRAY[['talk', 'consult'], ['meeting', '']]);
+ SELECT * FROM sal_emp;
+ name | pay_by_quarter | schedule
+ -------+---------------------------+-------------------------------
+ Bill | {10000,10000,10000,10000} | {{meeting,lunch},{"",""}}
+ Carol | {20000,25000,25000,25000} | {{talk,consult},{meeting,""}}
+ (2 rows)
+
+ Note that with this syntax, multi-dimesion arrays must have matching
+ extents for each dimension. This eliminates the missing-array-elements
+ problem above. For example:
+
+ INSERT INTO sal_emp
+ VALUES ('Carol',
+ ARRAY[20000, 25000, 25000, 25000],
+ ARRAY[['talk', 'consult'], ['meeting']]);
+ ERROR: Multiple dimension arrays must have array expressions with matching dimensions
+
+ Also notice that string literals are single quoted instead of double quoted.
+
+
! The examples in the rest of this section are based on the
! ARRAY expression syntax INSERTs.
+
***************
*** 132,142 ****
with the same result. An array subscripting operation is always taken to
! represent an array slice if any of the subscripts are written in the
! form
lower:upper.
A lower bound of 1 is assumed for any subscript where only one value
! is specified.
--- 192,221 ----
with the same result. An array subscripting operation is always taken to
! represent an array slice if any of the subscripts are written in the form
lower:upper.
A lower bound of 1 is assumed for any subscript where only one value
! is specified; another example follows:
!
! SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';
! schedule
! ---------------------------
! {{meeting,lunch},{"",""}}
! (1 row)
!
!
!
!
! Additionally, we can also access a single arbitrary array element of
! a one-dimensional array with the array_subscript
! function:
!
! SELECT array_subscript(pay_by_quarter, 2) FROM sal_emp WHERE name = 'Bill';
! array_subscript
! -----------------
! 10000
! (1 row)
!
***************
*** 147,153 ****
WHERE name = 'Carol';
! or updated at a single element:
UPDATE sal_emp SET pay_by_quarter[4] = 15000
--- 226,248 ----
WHERE name = 'Carol';
! or using the ARRAY expression syntax:
!
!
! UPDATE sal_emp SET pay_by_quarter = ARRAY[25000,25000,27000,27000]
! WHERE name = 'Carol';
!
!
!
!
! Anywhere you can use the curly braces
array syntax,
! you can also use the ARRAY expression syntax. The
! remainder of this section will illustrate only one or the other, but
! not both.
!
!
!
! An array may also be updated at a single element:
UPDATE sal_emp SET pay_by_quarter[4] = 15000
***************
*** 160,165 ****
--- 255,268 ----
UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
WHERE name = 'Carol';
+
+ A one-dimensional array may also be updated with the
+ array_assign function:
+
+
+ UPDATE sal_emp SET pay_by_quarter = array_assign(pay_by_quarter, 4, 15000)
+ WHERE name = 'Bill';
+
***************
*** 169,175 ****
value currently has 4 elements, it will have five elements after an
update that assigns to array[5]. Currently, enlargement in
this fashion is only allowed for one-dimensional arrays, not
! multidimensional arrays.
--- 272,278 ----
value currently has 4 elements, it will have five elements after an
update that assigns to array[5]. Currently, enlargement in
this fashion is only allowed for one-dimensional arrays, not
! multi-dimensional arrays.
***************
*** 179,184 ****
--- 282,367 ----
+ An array can also be enlarged by using the functions
+ array_prepend, array_append,
+ or array_cat. The first two only support one-dimensional
+ arrays, but array_cat supports multi-dimensional arrays.
+ Some examples:
+
+
+ SELECT array_prepend(1, ARRAY[2,3]);
+ array_prepend
+ ---------------
+ {1,2,3}
+ (1 row)
+
+ SELECT array_append(ARRAY[1,2], 3);
+ array_append
+ --------------
+ {1,2,3}
+ (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]);
+ array_cat
+ ---------------------
+ {{1,2},{3,4},{5,6}}
+ (1 row)
+
+ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
+ array_cat
+ ---------------------
+ {{5,6},{1,2},{3,4}}
+
+
+ array_prepend and array_append
+ work with a one-dimensional array and a single element to be pushed on
+ to the beginning or end of the array, respectively. The array is extended
+ in the direction of the push. Hence, by pushing onto the beginning of an
+ array with a one-based subscript, a zero-based subscript array is created:
+
+
+ SELECT array_dims(t.f) FROM (SELECT array_prepend(1, ARRAY[2,3]) AS f) AS t;
+ array_dims
+ ------------
+ [0:2]
+ (1 row)
+
+
+ array_cat works with either two
+ n-dimension arrays, or an n-dimension
+ and an n+1 dimension array. In the former case, the two
+ n-dimension arrays become outer elements of an
+ n+1 dimension array. In the latter, the
+ n-dimension array is added as either the first or last
+ outer element of the n+1 dimension array.
+
+
+
+ A final method of enlarging arrays is through the concatenation operator,
+ ||, which works exactly as array_cat
+ does.
+
+ SELECT ARRAY[1,2] || ARRAY[3,4];
+ ?column?
+ ---------------
+ {{1,2},{3,4}}
+ (1 row)
+
+ SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
+ ?column?
+ ---------------------
+ {{5,6},{1,2},{3,4}}
+ (1 row)
+
+
+
+
The syntax for CREATE TABLE allows fixed-length
arrays to be defined:
***************
*** 194,199 ****
--- 377,392 ----
+ An alternative syntax for one-dimensional arrays may be used.
+ pay_by_quarter could have been defined as:
+
+ pay_by_quarter integer ARRAY[4],
+
+ This syntax may only be used with the integer
+ constant to denote the array size.
+
+
+
Actually, the current implementation does not enforce the declared
number of dimensions either. Arrays of a particular element type are
all considered to be of the same type, regardless of size or number
***************
*** 292,298 ****
for the array's element type. (Among the standard data types provided
in the PostgreSQL distribution, type
box uses a semicolon (;) but all the others
! use comma.) In a multidimensional array, each dimension (row, plane,
cube, etc.) gets its own level of curly braces, and delimiters
must be written between adjacent curly-braced entities of the same level.
You may write whitespace before a left brace, after a right
--- 485,491 ----
for the array's element type. (Among the standard data types provided
in the PostgreSQL distribution, type
box uses a semicolon (;) but all the others
! use comma.) In a multi-dimensional array, each dimension (row, plane,
cube, etc.) gets its own level of curly braces, and delimiters
must be written between adjacent curly-braced entities of the same level.
You may write whitespace before a left brace, after a right
***************
*** 300,305 ****
--- 493,564 ----
is not ignored, however: after skipping leading whitespace, everything
up to the next right brace or delimiter is taken as the item value.
+
+
+ As illustrated earlier in this chapter, arrays may also be represented
+ using the ARRAY expression syntax. This representation
+ of an array value consists of items that are interpreted according to the
+ I/O conversion rules for the array's element type, plus decoration that
+ indicates the array structure. The decoration consists of the keyword
+ ARRAY and square brackets ([ and
+ ]) around the array values, plus delimiter characters between
+ adjacent items. The delimiter character is always a comma (,).
+ When representing multi-dimensional arrays, the keyword
+ ARRAY is only necessary for the outer level. For example,
+ '{{"hello world", "happy birthday"}}' could be written as:
+
+ SELECT ARRAY[['hello world', 'happy birthday']];
+ array
+ ------------------------------------
+ {{"hello world","happy birthday"}}
+ (1 row)
+
+ or it also could be written as:
+
+ SELECT ARRAY[ARRAY['hello world', 'happy birthday']];
+ array
+ ------------------------------------
+ {{"hello world","happy birthday"}}
+ (1 row)
+
+
+
+
+ A final method to represent an array, is through an
+ ARRAY sub-select expression. For example:
+
+ SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
+ ?column?
+ -------------------------------------------------------------
+ {2011,1954,1948,1952,1951,1244,1950,2005,1949,1953,2006,31}
+ (1 row)
+
+ The sub-select may only return a single column. The
+ resulting one-dimensional array will have an element for each row in the
+ sub-select result, with an element type matching that of the sub-select's
+ target column.
+
+
+
+ Arrays may be cast from one type to another in similar fashion to other
+ data types:
+
+
+ SELECT ARRAY[1,2,3]::oid[];
+ array
+ ---------
+ {1,2,3}
+ (1 row)
+
+ SELECT CAST(ARRAY[1,2,3] AS float8[]);
+ array
+ ---------
+ {1,2,3}
+ (1 row)
+
+
+
+
***************
*** 316,321 ****
--- 575,588 ----
Alternatively, you can use backslash-escaping to protect all data characters
that would otherwise be taken as array syntax or ignorable white space.
+
+
+
+ The discussion in the preceding paragraph with respect to double quoting does
+ not pertain to the ARRAY expression syntax. In that case,
+ each element is quoted exactly as any other literal value of the element type.
+
+
The array output routine will put double quotes around element values
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /opt/src/cvs/pgsql-server/doc/src/sgml/func.sgml,v
retrieving revision 1.153
diff -c -r1.153 func.sgml
*** doc/src/sgml/func.sgml 1 May 2003 00:57:05 -0000 1.153
--- doc/src/sgml/func.sgml 5 May 2003 00:42:26 -0000
***************
*** 6962,6967 ****
--- 6962,7194 ----
+
+ Array Functions
+
+
+ shows the operators
+ available for the array types.
+
+
+
+ <type>array</type> Operators
+
+
+
+ Operator
+ Description
+ Example
+ Result
+
+
+
+
+ =
+ equals
+ ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3]
+ t
+
+
+ ||
+ array-to-array concatenation
+ ARRAY[1,2,3] || ARRAY[4,5,6]
+ {{1,2,3},{4,5,6}}
+
+
+ ||
+ array-to-array concatenation
+ ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9]]
+ {{1,2,3},{4,5,6},{7,8,9}}
+
+
+ ||
+ element-to-array concatenation
+ 3 || ARRAY[4,5,6]
+ {3,4,5,6}
+
+
+ ||
+ array-to-element concatenation
+ ARRAY[4,5,6] || 7
+ {4,5,6,7}
+
+
+
+
+
+
+ shows the functions
+ available for use with array types. See
+ for more discussion and examples for the use of these functions.
+
+
+
+ <type>array</type> Functions
+
+
+
+ Function
+ Return Type
+ Description
+ Example
+ Result
+
+
+
+
+
+
+ array_accum
+ (anyarray, anyelement)
+
+
+ anyarray
+
+ append an element to the end of an array, ignoring
+ NULL elements, and creating an array if needed
+
+ array_accum(null, 1)
+ {1}
+
+
+
+
+ array_append
+ (anyarray, anyelement)
+
+
+ anyarray
+
+ append an element to the end of an array, returning
+ NULL for NULL inputs
+
+ array_append(ARRAY[1,2], 3)
+ {1,2,3}
+
+
+
+
+ array_assign
+ (anyarray, integer, anyelement)
+
+
+ anyarray
+
+ assign a value to a specific array element, returning
+ NULL for NULL inputs
+
+ array_assign(ARRAY[1,2,3], 2, 99)
+ {1,99,3}
+
+
+
+
+ array_cat
+ (anyarray, anyarray)
+
+
+ anyarray
+
+ concatenate two arrays, returning NULL
+ for NULL inputs
+
+ array_cat(ARRAY[1,2,3], ARRAY[4,5,6])
+ {{1,2,3},{4,5,6}}
+
+
+
+
+ array_dims
+ (anyarray)
+
+
+ text
+
+ returns a text representation of array dimension lower and upper bounds,
+ generating an ERROR for NULL inputs
+
+ array_dims(array[[1,2,3],[4,5,6]])
+ [1:2][1:3]
+
+
+
+
+ array_lower
+ (anyarray, integer)
+
+
+ integer
+
+ returns lower bound of the requested array dimension, returning
+ NULL for NULL inputs
+
+ array_lower(array_prepend(0, ARRAY[1,2,3]), 1)
+ 0
+
+
+
+
+ array_prepend
+ (anyelement, anyarray)
+
+
+ anyarray
+
+ append an element to the beginning of an array, returning
+ NULL for NULL inputs
+
+ array_prepend(1, ARRAY[2,3])
+ {1,2,3}
+
+
+
+
+ array_subscript
+ (anyarray, integer)
+
+
+ anyelement
+
+ returns requested array element, returning
+ NULL for NULL inputs
+
+ array_subscript(ARRAY[1,2,3], 3)
+ 3
+
+
+
+
+ array_upper
+ (anyarray, integer)
+
+
+ integer
+
+ returns upper bound of the requested array dimension, returning
+ NULL for NULL inputs
+
+ array_upper(array_append(ARRAY[1,2,3], 4), 1)
+ 4
+
+
+
+
+ singleton_array
+ (anyelement)
+
+
+ anyarray
+
+ create an array from the provided element, returning
+ NULL for NULL inputs
+
+ singleton_array(1)
+ {1}
+
+
+
+
+
Aggregate Functions