Skip to content

Commit 97690ea

Browse files
alvherrealvherre
committed
Change array_offset to return subscripts, not offsets
... 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.
1 parent 0853630 commit 97690ea

File tree

8 files changed

+137
-118
lines changed

8 files changed

+137
-118
lines changed

‎doc/src/sgml/array.sgml

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -601,20 +601,20 @@ SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000];
601601
</para>
602602

603603
<para>
604-
You can also search for specific values in an array using the <function>array_offset</>
605-
and <function>array_offsets</> functions. The former returns the position of
604+
You can also search for specific values in an array using the <function>array_position</>
605+
and <function>array_positions</> functions. The former returns the subscript of
606606
the first occurrence of a value in an array; the latter returns an array with the
607-
positions of all occurrences of the value in the array. For example:
607+
subscripts of all occurrences of the value in the array. For example:
608608

609609
<programlisting>
610-
SELECT array_offset(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon');
611-
array_offset
612-
--------------
610+
SELECT array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon');
611+
array_positions
612+
-----------------
613613
2
614614

615-
SELECT array_offsets(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1);
616-
array_offsets
617-
---------------
615+
SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1);
616+
array_positions
617+
-----------------
618618
{1,4,8}
619619
</programlisting>
620620
</para>

‎doc/src/sgml/func.sgml

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11481,10 +11481,10 @@ SELECT NULLIF(value, '(none)') ...
1148111481
<primary>array_lower</primary>
1148211482
</indexterm>
1148311483
<indexterm>
11484-
<primary>array_offset</primary>
11484+
<primary>array_position</primary>
1148511485
</indexterm>
1148611486
<indexterm>
11487-
<primary>array_offsets</primary>
11487+
<primary>array_positions</primary>
1148811488
</indexterm>
1148911489
<indexterm>
1149011490
<primary>array_prepend</primary>
@@ -11606,27 +11606,27 @@ SELECT NULLIF(value, '(none)') ...
1160611606
<row>
1160711607
<entry>
1160811608
<literal>
11609-
<function>array_offset</function>(<type>anyarray</type>, <type>anyelement</type> <optional>, <type>int</type></optional>)
11609+
<function>array_position</function>(<type>anyarray</type>, <type>anyelement</type> <optional>, <type>int</type></optional>)
1161011610
</literal>
1161111611
</entry>
1161211612
<entry><type>int</type></entry>
11613-
<entry>returns the offset of the first occurrence of the second
11613+
<entry>returns the subscript of the first occurrence of the second
1161411614
argument in the array, starting at the element indicated by the third
1161511615
argument or at the first element (array must be one-dimensional)</entry>
11616-
<entry><literal>array_offset(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon')</literal></entry>
11616+
<entry><literal>array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon')</literal></entry>
1161711617
<entry><literal>2</literal></entry>
1161811618
</row>
1161911619
<row>
1162011620
<entry>
1162111621
<literal>
11622-
<function>array_offsets</function>(<type>anyarray</type>, <type>anyelement</type>)
11622+
<function>array_positions</function>(<type>anyarray</type>, <type>anyelement</type>)
1162311623
</literal>
1162411624
</entry>
1162511625
<entry><type>int[]</type></entry>
11626-
<entry>returns an array of offsets of all occurrences of the second
11626+
<entry>returns an array of subscripts of all occurrences of the second
1162711627
argument in the array given as first argument (array must be
1162811628
one-dimensional)</entry>
11629-
<entry><literal>array_offsets(ARRAY['A','A','B','A'], 'A')</literal></entry>
11629+
<entry><literal>array_positions(ARRAY['A','A','B','A'], 'A')</literal></entry>
1163011630
<entry><literal>{1,2,4}</literal></entry>
1163111631
</row>
1163211632
<row>
@@ -11741,18 +11741,18 @@ NULL baz</literallayout>(3 rows)</entry>
1174111741
</table>
1174211742

1174311743
<para>
11744-
In <function>array_offset</function> and <function>array_offsets</>,
11744+
In <function>array_position</function> and <function>array_positions</>,
1174511745
each array element is compared to the searched value using
1174611746
<literal>IS NOT DISTINCT FROM</literal> semantics.
1174711747
</para>
1174811748

1174911749
<para>
11750-
In <function>array_offset</function>, <literal>NULL</literal> is returned
11750+
In <function>array_position</function>, <literal>NULL</literal> is returned
1175111751
if the value is not found.
1175211752
</para>
1175311753

1175411754
<para>
11755-
In <function>array_offsets</function>, <literal>NULL</literal> is returned
11755+
In <function>array_positions</function>, <literal>NULL</literal> is returned
1175611756
only if the array is <literal>NULL</literal>; if the value is not found in
1175711757
the array, an empty array is returned instead.
1175811758
</para>

‎src/backend/utils/adt/array_userfuncs.c

Lines changed: 29 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
#include "utils/typcache.h"
2020

2121

22-
static Datum array_offset_common(FunctionCallInfo fcinfo);
22+
static Datum array_position_common(FunctionCallInfo fcinfo);
2323

2424

2525
/*
@@ -659,43 +659,43 @@ array_agg_array_finalfn(PG_FUNCTION_ARGS)
659659
}
660660

661661
/*-----------------------------------------------------------------------------
662-
* array_offset, array_offset_start :
662+
* array_position, array_position_start :
663663
* return the offset of a value in an array.
664664
*
665665
* IS NOT DISTINCT FROM semantics are used for comparisons. Return NULL when
666666
* the value is not found.
667667
*-----------------------------------------------------------------------------
668668
*/
669669
Datum
670-
array_offset(PG_FUNCTION_ARGS)
670+
array_position(PG_FUNCTION_ARGS)
671671
{
672-
return array_offset_common(fcinfo);
672+
return array_position_common(fcinfo);
673673
}
674674

675675
Datum
676-
array_offset_start(PG_FUNCTION_ARGS)
676+
array_position_start(PG_FUNCTION_ARGS)
677677
{
678-
return array_offset_common(fcinfo);
678+
return array_position_common(fcinfo);
679679
}
680680

681681
/*
682-
* array_offset_common
683-
* Common code for array_offset and array_offset_start
682+
* array_position_common
683+
* Common code for array_position and array_position_start
684684
*
685685
* These are separate wrappers for the sake of opr_sanity regression test.
686686
* They are not strict so we have to test for null inputs explicitly.
687687
*/
688688
static Datum
689-
array_offset_common(FunctionCallInfo fcinfo)
689+
array_position_common(FunctionCallInfo fcinfo)
690690
{
691691
ArrayType *array;
692692
Oid collation = PG_GET_COLLATION();
693693
Oid element_type;
694694
Datum searched_element,
695695
value;
696696
bool isnull;
697-
int offset = 0,
698-
offset_min;
697+
int position,
698+
position_min;
699699
bool found = false;
700700
TypeCacheEntry *typentry;
701701
ArrayMetaState *my_extra;
@@ -731,18 +731,20 @@ array_offset_common(FunctionCallInfo fcinfo)
731731
null_search = false;
732732
}
733733

734+
position = (ARR_LBOUND(array))[0] - 1;
735+
734736
/* figure out where to start */
735737
if (PG_NARGS() == 3)
736738
{
737739
if (PG_ARGISNULL(2))
738740
ereport(ERROR,
739741
(errcode(ERRCODE_NULL_VALUE_NOT_ALLOWED),
740-
errmsg("initial offset should not be NULL")));
742+
errmsg("initial position should not be NULL")));
741743

742-
offset_min = PG_GETARG_INT32(2);
744+
position_min = PG_GETARG_INT32(2);
743745
}
744746
else
745-
offset_min = 1;
747+
position_min = (ARR_LBOUND(array))[0];
746748

747749
/*
748750
* We arrange to look up type info for array_create_iterator only once per
@@ -780,10 +782,10 @@ array_offset_common(FunctionCallInfo fcinfo)
780782
array_iterator = array_create_iterator(array, 0, my_extra);
781783
while (array_iterate(array_iterator, &value, &isnull))
782784
{
783-
offset += 1;
785+
position++;
784786

785787
/* skip initial elements if caller requested so */
786-
if (offset < offset_min)
788+
if (position < position_min)
787789
continue;
788790

789791
/*
@@ -818,12 +820,12 @@ array_offset_common(FunctionCallInfo fcinfo)
818820
if (!found)
819821
PG_RETURN_NULL();
820822

821-
PG_RETURN_INT32(offset);
823+
PG_RETURN_INT32(position);
822824
}
823825

824826
/*-----------------------------------------------------------------------------
825-
* array_offsets :
826-
* return an array of offsets of a value in an array.
827+
* array_positions :
828+
* return an array of positions of a value in an array.
827829
*
828830
* IS NOT DISTINCT FROM semantics are used for comparisons. Returns NULL when
829831
* the input array is NULL. When the value is not found in the array, returns
@@ -833,15 +835,15 @@ array_offset_common(FunctionCallInfo fcinfo)
833835
*-----------------------------------------------------------------------------
834836
*/
835837
Datum
836-
array_offsets(PG_FUNCTION_ARGS)
838+
array_positions(PG_FUNCTION_ARGS)
837839
{
838840
ArrayType *array;
839841
Oid collation = PG_GET_COLLATION();
840842
Oid element_type;
841843
Datum searched_element,
842844
value;
843845
bool isnull;
844-
int offset = 0;
846+
int position;
845847
TypeCacheEntry *typentry;
846848
ArrayMetaState *my_extra;
847849
bool null_search;
@@ -854,6 +856,8 @@ array_offsets(PG_FUNCTION_ARGS)
854856
array = PG_GETARG_ARRAYTYPE_P(0);
855857
element_type = ARR_ELEMTYPE(array);
856858

859+
position = (ARR_LBOUND(array))[0] - 1;
860+
857861
/*
858862
* We refuse to search for elements in multi-dimensional arrays, since we
859863
* have no good way to report the element's location in the array.
@@ -912,12 +916,12 @@ array_offsets(PG_FUNCTION_ARGS)
912916
}
913917

914918
/*
915-
* Accumulate each array offset iff the element matches the given element.
919+
* Accumulate each array position iff the element matches the given element.
916920
*/
917921
array_iterator = array_create_iterator(array, 0, my_extra);
918922
while (array_iterate(array_iterator, &value, &isnull))
919923
{
920-
offset += 1;
924+
position += 1;
921925

922926
/*
923927
* Can't look at the array element's value if it's null; but if we
@@ -927,7 +931,7 @@ array_offsets(PG_FUNCTION_ARGS)
927931
{
928932
if (isnull && null_search)
929933
astate =
930-
accumArrayResult(astate, Int32GetDatum(offset), false,
934+
accumArrayResult(astate, Int32GetDatum(position), false,
931935
INT4OID, CurrentMemoryContext);
932936

933937
continue;
@@ -937,7 +941,7 @@ array_offsets(PG_FUNCTION_ARGS)
937941
if (DatumGetBool(FunctionCall2Coll(&my_extra->proc, collation,
938942
searched_element, value)))
939943
astate =
940-
accumArrayResult(astate, Int32GetDatum(offset), false,
944+
accumArrayResult(astate, Int32GetDatum(position), false,
941945
INT4OID, CurrentMemoryContext);
942946
}
943947

‎src/include/catalog/catversion.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,6 @@
5353
*/
5454

5555
/* yyyymmddN */
56-
#define CATALOG_VERSION_NO 201503301
56+
#define CATALOG_VERSION_NO 201503302
5757

5858
#endif

‎src/include/catalog/pg_proc.h

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -895,11 +895,11 @@ DATA(insert OID = 515 ( array_larger PGNSP PGUID 12 1 0 0 0 f f f f t f i 2
895895
DESCR("larger of two");
896896
DATA(insert OID = 516 ( array_smaller PGNSP PGUID 12 1 0 0 0 f f f f t f i 2 0 2277 "2277 2277" _null_ _null_ _null_ _null_ array_smaller _null_ _null_ _null_ ));
897897
DESCR("smaller of two");
898-
DATA(insert OID = 3277 ( array_offset PGNSP PGUID 12 1 0 0 0 f f f f f f i 2 0 23 "2277 2283" _null_ _null_ _null_ _null_ array_offset _null_ _null_ _null_ ));
898+
DATA(insert OID = 3277 ( array_position PGNSP PGUID 12 1 0 0 0 f f f f f f i 2 0 23 "2277 2283" _null_ _null_ _null_ _null_ array_position _null_ _null_ _null_ ));
899899
DESCR("returns a offset of value in array");
900-
DATA(insert OID = 3278 ( array_offset PGNSP PGUID 12 1 0 0 0 f f f f f f i 3 0 23 "2277 2283 23" _null_ _null_ _null_ _null_ array_offset_start _null_ _null_ _null_ ));
900+
DATA(insert OID = 3278 ( array_position PGNSP PGUID 12 1 0 0 0 f f f f f f i 3 0 23 "2277 2283 23" _null_ _null_ _null_ _null_ array_position_start _null_ _null_ _null_ ));
901901
DESCR("returns a offset of value in array with start index");
902-
DATA(insert OID = 3279 ( array_offsets PGNSP PGUID 12 1 0 0 0 f f f f f f i 2 0 1007 "2277 2283" _null_ _null_ _null_ _null_ array_offsets _null_ _null_ _null_ ));
902+
DATA(insert OID = 3279 ( array_positions PGNSP PGUID 12 1 0 0 0 f f f f f f i 2 0 1007 "2277 2283" _null_ _null_ _null_ _null_ array_positions _null_ _null_ _null_ ));
903903
DESCR("returns a array of offsets of some value in array");
904904
DATA(insert OID = 1191 ( generate_subscripts PGNSP PGUID 12 1 1000 0 0 f f f f t t i 3 0 23 "2277 23 16" _null_ _null_ _null_ _null_ generate_subscripts _null_ _null_ _null_ ));
905905
DESCR("array subscripts generator");

‎src/include/utils/array.h

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -358,9 +358,9 @@ extern Datum array_agg_finalfn(PG_FUNCTION_ARGS);
358358
extern Datum array_agg_array_transfn(PG_FUNCTION_ARGS);
359359
extern Datum array_agg_array_finalfn(PG_FUNCTION_ARGS);
360360

361-
extern Datum array_offset(PG_FUNCTION_ARGS);
362-
extern Datum array_offset_start(PG_FUNCTION_ARGS);
363-
extern Datum array_offsets(PG_FUNCTION_ARGS);
361+
extern Datum array_position(PG_FUNCTION_ARGS);
362+
extern Datum array_position_start(PG_FUNCTION_ARGS);
363+
extern Datum array_positions(PG_FUNCTION_ARGS);
364364

365365
/*
366366
* prototypes for functions defined in array_typanalyze.c

0 commit comments

Comments
 (0)