database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-23 14:01:44 +03:00
Code Activity

Change array_offset to return subscripts, not offsets

Browse Source 
... 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.
This commit is contained in:
Alvaro Herrera
2015-03-30 16:13:21 -03:00
parent 0853630159
commit 97690ea6e8
8 changed files with 136 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/src/sgml/array.sgml
View File

@ -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>

22
doc/src/sgml/func.sgml
View File

@ -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>