From e4eb91048cd3898b9164493c92d6b82d694aa46f Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 18 Dec 2000 23:39:37 +0000 Subject: [PATCH] Document the array_dims() function, and make some other small improvements in the docs for arrays. --- doc/src/sgml/advanced.sgml | 9 ++++---- doc/src/sgml/array.sgml | 42 +++++++++++++++++++++++++++++++------- doc/src/sgml/syntax.sgml | 12 +++++------ 3 files changed, 45 insertions(+), 18 deletions(-) diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index 7876eac410..13cdf16863 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -1,5 +1,5 @@ @@ -178,7 +178,7 @@ CREATE TABLE SAL_EMP ( salary by quarter and a two-dimensional array of text (schedule), which represents the employee's weekly - schedule. Now we do some INSERTSs; + schedule. Now we do some INSERTs; note that when appending to an array, we enclose the values within braces and separate them by commas. If you know @@ -239,8 +239,9 @@ SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP; - We can also access arbitrary slices of an array, or - subarrays. This query retrieves the first item on + We can also access arbitrary slices of an array (subarrays) + by specifying both lower and upper bounds for + each subscript. This query retrieves the first item on Bill's schedule for the first two days of the week. diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml index 5947df26c7..427a3956cd 100644 --- a/doc/src/sgml/array.sgml +++ b/doc/src/sgml/array.sgml @@ -1,3 +1,7 @@ + + Arrays @@ -30,7 +34,7 @@ CREATE TABLE sal_emp ( (pay_by_quarter), which represents the employee's salary by quarter, and a two-dimensional array of text (schedule), which represents the employee's weekly - schedule. Now we do some INSERTSs; note that when + schedule. Now we do some INSERTs; note that when appending to an array, we enclose the values within braces and separate them by commas. If you know C, this is not unlike the syntax for initializing structures. @@ -82,9 +86,10 @@ SELECT pay_by_quarter[3] FROM sal_emp; - We can also access arbitrary slices of an array, or + We can also access arbitrary rectangular slices of an array, or subarrays. An array slice is denoted by writing - "lower subscript : upper subscript" for one or more array + lower subscript : + upper subscript for one or more array dimensions. This query retrieves the first item on Bill's schedule for the first two days of the week: @@ -103,7 +108,11 @@ SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; SELECT schedule[1:2][1] FROM sal_emp WHERE name = 'Bill'; - with the same result. + with the same result. An array subscripting operation is 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. @@ -114,7 +123,7 @@ UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}' WHERE name = 'Carol'; - or updated at a single entry: + or updated at a single element: UPDATE sal_emp SET pay_by_quarter[4] = 15000 @@ -132,10 +141,11 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' An array can be enlarged by assigning to an element adjacent to those already present, or by assigning to a slice that is adjacent - to or overlaps the data already present. Currently, this is only - allowed for one-dimensional arrays, not multidimensional arrays. + to or overlaps the data already present. For example, if an array 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. @@ -160,4 +170,22 @@ CREATE TABLE tictactoe ( number of dimensions. + + The current dimensions of any array value can be retrieved with + the array_dims function: + + +SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol'; + + array_dims +------------ + [1:2][1:1] +(1 row) + + + array_dims produces a text result, + which is convenient for people to read but perhaps not so convenient + for programs. + + diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 596f91f818..ee249b684a 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -555,12 +555,10 @@ CAST ( 'string' AS type ) - Individual array elements can be placed between single-quote - marks to avoid ambiguity problems with respect to leading white space. - Without quote marks, the array-value parser will skip white space. - Note that to write a quote mark inside a string literal that is to - become an array value, you must double the quote mark as described - previously. + Individual array elements can be placed between double-quote + marks (") to avoid ambiguity problems with respect to + white space. + Without quote marks, the array-value parser will skip leading white space.