*** pgsql/doc/src/sgml/func.sgml	2008/04/17 20:56:41	1.433
--- pgsql/doc/src/sgml/func.sgml	2008/04/28 14:48:57	1.434
***************
*** 1,4 ****
! <!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.432 2008/04/15 20:28:46 momjian Exp $ -->
  
   <chapter id="functions">
    <title>Functions and Operators</title>
--- 1,4 ----
! <!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.433 2008/04/17 20:56:41 momjian Exp $ -->
  
   <chapter id="functions">
    <title>Functions and Operators</title>
*************** AND
*** 10613,10619 ****
    <para>
     This section describes functions that possibly return more than one row.
     Currently the only functions in this class are series generating functions,
!    as detailed in <xref linkend="functions-srf-series">.
    </para>
  
    <table id="functions-srf-series">
--- 10613,10620 ----
    <para>
     This section describes functions that possibly return more than one row.
     Currently the only functions in this class are series generating functions,
!    as detailed in <xref linkend="functions-srf-series"> and
!    <xref linkend="functions-srf-subscripts">.
    </para>
  
    <table id="functions-srf-series">
*************** select current_date + s.a as dates from
*** 10691,10696 ****
--- 10692,10790 ----
  (3 rows)
  </programlisting>
    </para>
+ 
+   <table id="functions-srf-subscripts">
+ 
+   <indexterm>
+    <primary>generate_subscripts</primary>
+   </indexterm>
+ 
+    <title>Subscripts Generating Functions</title>
+    <tgroup cols="3">
+     <thead>
+      <row>
+       <entry>Function</entry>
+       <entry>Return Type</entry>
+       <entry>Description</entry>
+      </row>
+     </thead>
+ 
+     <tbody>
+      <row>
+       <entry><literal><function>generate_subscripts</function>(<parameter>array annyarray</parameter>, <parameter>dim int</parameter>)</literal></entry>
+       <entry><type>setof int</type></entry>
+       <entry>
+        Generate a series comprising the given array's subscripts.
+       </entry>
+      </row>
+ 
+      <row>
+       <entry><literal><function>generate_subscripts</function>(<parameter>array annyarray</parameter>, <parameter>dim int</parameter>, <parameter>reverse boolean</parameter>)</literal></entry>
+       <entry><type>setof int</type></entry>
+       <entry>
+        Generate a series comprising the given array's subscripts. When
+        <parameter>reverse</parameter> is true, the series is returned in
+        reverse order.
+       </entry>
+      </row>
+ 
+     </tbody>
+    </tgroup>
+   </table>
+ 
+   <para>
+    Zero rows are returned for arrays that do not have the requested dimension,
+    or for NULL arrays (but valid subscripts are returned for NULL array
+    elements.) Some examples follow:
+ <programlisting>
+ -- basic usage
+ select generate_subscripts('{NULL,1,NULL,2}'::int[], 1) as s;
+  s 
+ ---
+  1
+  2
+  3
+  4
+ (4 rows)
+ 
+ -- presenting an array, the subscript and the subscripted
+ -- value requires a subquery
+ select * from arrays;
+          a          
+ --------------------
+  {-1,-2}
+  {100,200}
+ (2 rows)
+ 
+ select a as array, s as subscript, a[s] as value
+ from (select generate_subscripts(a, 1) as s, a from arrays) foo;
+    array   | subscript | value 
+ -----------+-----------+-------
+  {-1,-2}   |         1 |    -1
+  {-1,-2}   |         2 |    -2
+  {100,200} |         1 |   100
+  {100,200} |         2 |   200
+ (4 rows)
+ 
+ -- unnest a 2D array
+ create or replace function unnest2(anyarray)
+ returns setof anyelement as $$
+ select $1[i][j] 
+    from generate_subscripts($1,1) g1(i),
+         generate_subscripts($1,2) g2(j);
+ $$ language sql immutable;
+ CREATE FUNCTION
+ postgres=# select * from unnest2(array[[1,2],[3,4]]);
+  unnest2 
+ ---------
+        1
+        2
+        3
+        4
+ (4 rows)
+ </programlisting>
+   </para>
+ 
   </sect1>
  
   <sect1 id="functions-info">