mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-04 23:57:20 +02:00
Improve documentation about array concat operator vs. underlying functions.
The documentation implied that there was seldom any reason to use the array_append, array_prepend, and array_cat functions directly. But that's not really true, because they can help make it clear which case is meant, which the || operator can't do since it's overloaded to represent all three cases. Add some discussion and examples illustrating the potentially confusing behavior that can ensue if the parser misinterprets what was meant. Per a complaint from Michael Herold. Back-patch to 9.2, which is where || started to behave this way.
This commit is contained in:
parent
193e027075
commit
5acc7730c8
@ -494,11 +494,7 @@ SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
|
||||
<function>array_prepend</function>, <function>array_append</function>,
|
||||
or <function>array_cat</function>. The first two only support one-dimensional
|
||||
arrays, but <function>array_cat</function> supports multidimensional arrays.
|
||||
|
||||
Note that the concatenation operator discussed above is preferred over
|
||||
direct use of these functions. In fact, these functions primarily exist for use
|
||||
in implementing the concatenation operator. However, they might be directly
|
||||
useful in the creation of user-defined aggregates. Some examples:
|
||||
Some examples:
|
||||
|
||||
<programlisting>
|
||||
SELECT array_prepend(1, ARRAY[2,3]);
|
||||
@ -531,6 +527,45 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
|
||||
{{5,6},{1,2},{3,4}}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In simple cases, the concatenation operator discussed above is preferred
|
||||
over direct use of these functions. However, because the concatenation
|
||||
operator is overloaded to serve all three cases, there are situations where
|
||||
use of one of the functions is helpful to avoid ambiguity. For example
|
||||
consider:
|
||||
|
||||
<programlisting>
|
||||
SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array
|
||||
?column?
|
||||
-----------
|
||||
{1,2,3,4}
|
||||
|
||||
SELECT ARRAY[1, 2] || '7'; -- so is this one
|
||||
ERROR: malformed array literal: "7"
|
||||
|
||||
SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL
|
||||
?column?
|
||||
----------
|
||||
{1,2}
|
||||
(1 row)
|
||||
|
||||
SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant
|
||||
array_append
|
||||
--------------
|
||||
{1,2,NULL}
|
||||
</programlisting>
|
||||
|
||||
In the examples above, the parser sees an integer array on one side of the
|
||||
concatenation operator, and a constant of undetermined type on the other.
|
||||
The heuristic it uses to resolve the constant's type is to assume it's of
|
||||
the same type as the operator's other input — in this case,
|
||||
integer array. So the concatenation operator is presumed to
|
||||
represent <function>array_cat</>, not <function>array_append</>. When
|
||||
that's the wrong choice, it could be fixed by casting the constant to the
|
||||
array's element type; but explicit use of <function>array_append</> might
|
||||
be a preferable solution.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="arrays-searching">
|
||||
|
Loading…
Reference in New Issue
Block a user