diff options
| -rw-r--r-- | doc/src/sgml/advanced.sgml | 9 | ||||
| -rw-r--r-- | doc/src/sgml/array.sgml | 42 | ||||
| -rw-r--r-- | 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 7876eac4104..13cdf168634 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.16 2000/09/29 20:21:33 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.17 2000/12/18 23:39:37 tgl Exp $ --> <chapter id="advanced"> @@ -178,7 +178,7 @@ CREATE TABLE SAL_EMP ( salary by quarter and a two-dimensional array of <firstterm>text</firstterm> (schedule), which represents the employee's weekly - schedule. Now we do some <firstterm>INSERTS</firstterm>s; + schedule. Now we do some <firstterm>INSERT</firstterm>s; 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; </para> <para> - 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. <programlisting> diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml index 5947df26c7a..427a3956cd3 100644 --- a/doc/src/sgml/array.sgml +++ b/doc/src/sgml/array.sgml @@ -1,3 +1,7 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.8 2000/12/18 23:39:37 tgl Exp $ +--> + <Chapter Id="arrays"> <Title>Arrays</Title> @@ -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 <FirstTerm>text</FirstTerm> (schedule), which represents the employee's weekly - schedule. Now we do some <FirstTerm>INSERTS</FirstTerm>s; note that when + schedule. Now we do some <FirstTerm>INSERT</FirstTerm>s; note that when appending to an array, we enclose the values within braces and separate them by commas. If you know <FirstTerm>C</FirstTerm>, this is not unlike the syntax for initializing structures. @@ -82,9 +86,10 @@ SELECT pay_by_quarter[3] FROM sal_emp; </Para> <Para> - 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 + <replaceable>lower subscript</replaceable> <literal>:</literal> + <replaceable>upper subscript</replaceable> 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'; </ProgramListing> - 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 <replaceable>lower</replaceable> <literal>:</literal> + <replaceable>upper</replaceable>. A lower bound of 1 is assumed + for any subscript where only one value is specified. </Para> <Para> @@ -114,7 +123,7 @@ UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}' WHERE name = 'Carol'; </ProgramListing> - or updated at a single entry: + or updated at a single element: <ProgramListing> UPDATE sal_emp SET pay_by_quarter[4] = 15000 @@ -132,10 +141,11 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' <Para> 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. </Para> <Para> @@ -160,4 +170,22 @@ CREATE TABLE tictactoe ( number of dimensions. </Para> +<Para> + The current dimensions of any array value can be retrieved with + the <function>array_dims</function> function: + +<ProgramListing> +SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol'; + + array_dims +------------ + [1:2][1:1] +(1 row) +</ProgramListing> + + <function>array_dims</function> produces a <type>text</type> result, + which is convenient for people to read but perhaps not so convenient + for programs. +</Para> + </Chapter> diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 596f91f818a..ee249b684a3 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.28 2000/12/17 05:47:57 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.29 2000/12/18 23:39:37 tgl Exp $ --> <chapter id="syntax"> @@ -555,12 +555,10 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> ) </para> <para> - 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 (<literal>"</literal>) to avoid ambiguity problems with respect to + white space. + Without quote marks, the array-value parser will skip leading white space. </para> </sect2> </sect1> |