Document the array_dims() function, and make some other small improvements

in the docs for arrays.

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
+     We  can  also  access  arbitrary slices of an array (subarrays)
-     subarrays.  This query  retrieves  the  first  item  on
+     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>

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
+     to or overlaps the data already present.
-     allowed for one-dimensional arrays, not multidimensional arrays.
      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>

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
+     Individual array elements can be placed between double-quote
-     marks to avoid ambiguity problems with respect to leading white space.
+     marks (<literal>"</literal>) to avoid ambiguity problems with respect to
-     Without quote marks, the array-value parser will skip white space.
+     white space.
-     Note that to write a quote mark inside a string literal that is to
+     Without quote marks, the array-value parser will skip leading white space.
-     become an array value, you must double the quote mark as described
-     previously.
     </para>
    </sect2>
   </sect1>