For consideration - clarification of multi-dimensional arrays in our docs.

Hey all!

This doesn't come up that often but enough that it seems hammering home
that multi-dimension <> array-of-array seems warranted.

The first and last chuck cover definition and iteration respectively. The
second chuck removes the mention of "subarray" since that's what we don't
want people to think.

If the note seems a bit heavy-handed working it in as a normal paragraph in
the same or nearby location would work too.

Thoughts?

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index f4d4a610ef..a2dfd4de0a 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -14,6 +14,12 @@
or domain can be created.
</para>

+ <note>
+ A multi-dimensional array is not the same as an array-of-arrays. In
+ particular it is not useful to access a two-dimensional array with
+ a single dimension - you will be given null instead of an array
+ containing the elements of the specified row.
+ </note>
<sect2 id="arrays-declaration">
<title>Declaration of Array Types</title>

@@ -115,7 +121,7 @@ CREATE TABLE tictactoe (
'{{1,2,3},{4,5,6},{7,8,9}}'
</programlisting>
This constant is a two-dimensional, 3-by-3 array consisting of
- three subarrays of integers.
+ nine integers.
</para>

<para>
@@ -374,6 +380,25 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name =
'Carol';
(1 row)
</programlisting>
</para>
+
+ <para>
+ <function>unnest</function>, and other iteration access of arrays, is
performed
+ depth-first, for each lower dimension all higher dimension cells are
returned
+ before the next lower bound index. For a two-dimensional array this is
termed
+ row-first.
+
+<programlisting>
+SELECT unnest(schedule) FROM sal_emp WHERE name = 'Bill';
+
+ unnest
+--------------
+ meeting
+ lunch
+ training
+ presentation
+(4 rows)
+</programlisting>
+ </para>
</sect2>

<sect2 id="arrays-modifying">

David J.