Document array behavior for out-of-range subscripts.

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 94a1b8aacce8a73334c8d0653b636df668dc8e9f..b712b9c34d2e04809ab81d9261d07928fa27cc4e 100644 (file)
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.42 2004/12/23 05:37:39 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.43 2005/02/06 20:59:30 tgl Exp $ -->
 
 <sect1 id="arrays">
  <title>Arrays</title>
@@ -149,7 +149,7 @@ INSERT INTO sal_emp
    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.
+   null and some not.  (This is likely to change in the future.)
   </para>
 
  <para>
@@ -261,6 +261,18 @@ SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';
 </programlisting>
  </para>
 
+ <para>
+  Fetching from outside the current bounds of an array yields a
+  SQL null value, not an error.  For example, if <literal>schedule</>
+  currently has the dimensions <literal>[1:3][1:2]</> then referencing
+  <literal>schedule[3][3]</> yields NULL.  Similarly, an array reference
+  with the wrong number of subscripts yields a null rather than an error.
+  Fetching an array slice that
+  is completely outside the current bounds likewise yields a null array;
+  but if the requested slice partially overlaps the array bounds, then it
+  is silently reduced to just the overlapping region.
+ </para>
+
  <para>
   The current dimensions of any array value can be retrieved with the
   <function>array_dims</function> function: