From 97690ea6e86c412461dd5dc99953b829564d1a55 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Mon, 30 Mar 2015 16:13:21 -0300
Subject: Change array_offset to return subscripts, not offsets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

... and rename it and its sibling array_offsets to array_position and
array_positions, to account for the changed behavior.

Having the functions return subscripts better matches existing practice,
and is better suited to using the result value as a subscript into the
array directly.  For one-based arrays, the new definition is identical
to what was originally committed.

(We use the term "subscript" in the documentation, which is what we use
whenever we talk about arrays; but the functions themselves are named
using the word "position" to match the standard-defined POSITION()
functions.)

Author: Pavel Stěhule
Behavioral problem noted by Dean Rasheed.
---
 doc/src/sgml/array.sgml | 18 +++++++++---------
 doc/src/sgml/func.sgml  | 22 +++++++++++-----------
 2 files changed, 20 insertions(+), 20 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 092013b83b5..5e4130aa6df 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -601,20 +601,20 @@ SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000];
  </para>
 
  <para>
-  You can also search for specific values in an array using the <function>array_offset</>
-  and <function>array_offsets</> functions. The former returns the position of
+  You can also search for specific values in an array using the <function>array_position</>
+  and <function>array_positions</> functions. The former returns the subscript of
   the first occurrence of a value in an array; the latter returns an array with the
-  positions of all occurrences of the value in the array.  For example:
+  subscripts of all occurrences of the value in the array.  For example:
 
 <programlisting>
-SELECT array_offset(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon');
- array_offset
---------------
+SELECT array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon');
+ array_positions
+-----------------
  2
 
-SELECT array_offsets(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1);
- array_offsets 
----------------
+SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1);
+ array_positions
+-----------------
  {1,4,8}
 </programlisting>
  </para>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 3195655d111..53f31b51f54 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11481,10 +11481,10 @@ SELECT NULLIF(value, '(none)') ...
     <primary>array_lower</primary>
   </indexterm>
   <indexterm>
-    <primary>array_offset</primary>
+    <primary>array_position</primary>
   </indexterm>
   <indexterm>
-    <primary>array_offsets</primary>
+    <primary>array_positions</primary>
   </indexterm>
   <indexterm>
     <primary>array_prepend</primary>
@@ -11606,27 +11606,27 @@ SELECT NULLIF(value, '(none)') ...
        <row>
         <entry>
          <literal>
-          <function>array_offset</function>(<type>anyarray</type>, <type>anyelement</type> <optional>, <type>int</type></optional>)
+          <function>array_position</function>(<type>anyarray</type>, <type>anyelement</type> <optional>, <type>int</type></optional>)
          </literal>
         </entry>
         <entry><type>int</type></entry>
-        <entry>returns the offset of the first occurrence of the second
+        <entry>returns the subscript of the first occurrence of the second
         argument in the array, starting at the element indicated by the third
         argument or at the first element (array must be one-dimensional)</entry>
-        <entry><literal>array_offset(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon')</literal></entry>
+        <entry><literal>array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon')</literal></entry>
         <entry><literal>2</literal></entry>
        </row>
        <row>
         <entry>
          <literal>
-          <function>array_offsets</function>(<type>anyarray</type>, <type>anyelement</type>)
+          <function>array_positions</function>(<type>anyarray</type>, <type>anyelement</type>)
          </literal>
         </entry>
         <entry><type>int[]</type></entry>
-        <entry>returns an array of offsets of all occurrences of the second
+        <entry>returns an array of subscripts of all occurrences of the second
         argument in the array given as first argument (array must be
         one-dimensional)</entry>
-        <entry><literal>array_offsets(ARRAY['A','A','B','A'], 'A')</literal></entry>
+        <entry><literal>array_positions(ARRAY['A','A','B','A'], 'A')</literal></entry>
         <entry><literal>{1,2,4}</literal></entry>
        </row>
        <row>
@@ -11741,18 +11741,18 @@ NULL baz</literallayout>(3 rows)</entry>
     </table>
 
    <para>
-    In <function>array_offset</function> and <function>array_offsets</>,
+    In <function>array_position</function> and <function>array_positions</>,
     each array element is compared to the searched value using
     <literal>IS NOT DISTINCT FROM</literal> semantics.
    </para>
 
    <para>
-    In <function>array_offset</function>, <literal>NULL</literal> is returned
+    In <function>array_position</function>, <literal>NULL</literal> is returned
     if the value is not found.
    </para>
 
    <para>
-    In <function>array_offsets</function>, <literal>NULL</literal> is returned
+    In <function>array_positions</function>, <literal>NULL</literal> is returned
     only if the array is <literal>NULL</literal>; if the value is not found in
     the array, an empty array is returned instead.
    </para>
-- 
cgit v1.2.3