1+ <!--
2+ $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.8 2000/12/18 23:39:37 tgl Exp $
3+ -->
4+
15<Chapter Id="arrays">
26<Title>Arrays</Title>
37
@@ -30,7 +34,7 @@ CREATE TABLE sal_emp (
3034 (pay_by_quarter), which represents the employee's
3135 salary by quarter, and a two-dimensional array of <FirstTerm>text</FirstTerm>
3236 (schedule), which represents the employee's weekly
33- schedule. Now we do some <FirstTerm>INSERTS </FirstTerm>s; note that when
37+ schedule. Now we do some <FirstTerm>INSERT </FirstTerm>s; note that when
3438 appending to an array, we enclose the values within
3539 braces and separate them by commas. If you know <FirstTerm>C</FirstTerm>,
3640 this is not unlike the syntax for initializing structures.
@@ -82,9 +86,10 @@ SELECT pay_by_quarter[3] FROM sal_emp;
8286</Para>
8387
8488<Para>
85- We can also access arbitrary slices of an array, or
89+ We can also access arbitraryrectangular slices of an array, or
8690 subarrays. An array slice is denoted by writing
87- "lower subscript : upper subscript" for one or more array
91+ <replaceable>lower subscript</replaceable> <literal>:</literal>
92+ <replaceable>upper subscript</replaceable> for one or more array
8893 dimensions. This query retrieves the first item on
8994 Bill's schedule for the first two days of the week:
9095
@@ -103,7 +108,11 @@ SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';
103108SELECT schedule[1:2][1] FROM sal_emp WHERE name = 'Bill';
104109</ProgramListing>
105110
106- with the same result.
111+ with the same result. An array subscripting operation is taken to
112+ represent an array slice if any of the subscripts are written in
113+ the form <replaceable>lower</replaceable> <literal>:</literal>
114+ <replaceable>upper</replaceable>. A lower bound of 1 is assumed
115+ for any subscript where only one value is specified.
107116</Para>
108117
109118<Para>
@@ -114,7 +123,7 @@ UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}'
114123 WHERE name = 'Carol';
115124</ProgramListing>
116125
117- or updated at a singleentry :
126+ or updated at a singleelement :
118127
119128<ProgramListing>
120129UPDATE sal_emp SET pay_by_quarter[4] = 15000
@@ -132,10 +141,11 @@ UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
132141<Para>
133142 An array can be enlarged by assigning to an element adjacent to
134143 those already present, or by assigning to a slice that is adjacent
135- to or overlaps the data already present. Currently, this is only
136- allowed for one-dimensional arrays, not multidimensional arrays.
144+ to or overlaps the data already present.
137145 For example, if an array value currently has 4 elements, it will
138146 have five elements after an update that assigns to array[5].
147+ Currently, enlargement in this fashion is only
148+ allowed for one-dimensional arrays, not multidimensional arrays.
139149</Para>
140150
141151<Para>
@@ -160,4 +170,22 @@ CREATE TABLE tictactoe (
160170 number of dimensions.
161171</Para>
162172
173+ <Para>
174+ The current dimensions of any array value can be retrieved with
175+ the <function>array_dims</function> function:
176+
177+ <ProgramListing>
178+ SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';
179+
180+ array_dims
181+ ------------
182+ [1:2][1:1]
183+ (1 row)
184+ </ProgramListing>
185+
186+ <function>array_dims</function> produces a <type>text</type> result,
187+ which is convenient for people to read but perhaps not so convenient
188+ for programs.
189+ </Para>
190+
163191</Chapter>