Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commite4f29ce

Browse files
committed
Improve documentation about array concat operator vs. underlying functions.
The documentation implied that there was seldom any reason to use thearray_append, array_prepend, and array_cat functions directly. But that'snot 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 threecases. Add some discussion and examples illustrating the potentiallyconfusing behavior that can ensue if the parser misinterprets what wasmeant.Per a complaint from Michael Herold. Back-patch to 9.2, which is where ||started to behave this way.
1 parent45811be commite4f29ce

File tree

1 file changed

+41
-6
lines changed

1 file changed

+41
-6
lines changed

‎doc/src/sgml/array.sgml

Lines changed: 41 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -346,7 +346,7 @@ SELECT array_length(schedule, 1) FROM sal_emp WHERE name = 'Carol';
346346
<programlisting>
347347
SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol';
348348

349-
cardinality
349+
cardinality
350350
-------------
351351
4
352352
(1 row)
@@ -494,11 +494,7 @@ SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
494494
<function>array_prepend</function>, <function>array_append</function>,
495495
or <function>array_cat</function>. The first two only support one-dimensional
496496
arrays, but <function>array_cat</function> supports multidimensional arrays.
497-
498-
Note that the concatenation operator discussed above is preferred over
499-
direct use of these functions. In fact, these functions primarily exist for use
500-
in implementing the concatenation operator. However, they might be directly
501-
useful in the creation of user-defined aggregates. Some examples:
497+
Some examples:
502498

503499
<programlisting>
504500
SELECT array_prepend(1, ARRAY[2,3]);
@@ -531,6 +527,45 @@ SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
531527
{{5,6},{1,2},{3,4}}
532528
</programlisting>
533529
</para>
530+
531+
<para>
532+
In simple cases, the concatenation operator discussed above is preferred
533+
over direct use of these functions. However, because the concatenation
534+
operator is overloaded to serve all three cases, there are situations where
535+
use of one of the functions is helpful to avoid ambiguity. For example
536+
consider:
537+
538+
<programlisting>
539+
SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array
540+
?column?
541+
-----------
542+
{1,2,3,4}
543+
544+
SELECT ARRAY[1, 2] || '7'; -- so is this one
545+
ERROR: malformed array literal: "7"
546+
547+
SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL
548+
?column?
549+
----------
550+
{1,2}
551+
(1 row)
552+
553+
SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant
554+
array_append
555+
--------------
556+
{1,2,NULL}
557+
</programlisting>
558+
559+
In the examples above, the parser sees an integer array on one side of the
560+
concatenation operator, and a constant of undetermined type on the other.
561+
The heuristic it uses to resolve the constant's type is to assume it's of
562+
the same type as the operator's other input &mdash; in this case,
563+
integer array. So the concatenation operator is presumed to
564+
represent <function>array_cat</>, not <function>array_append</>. When
565+
that's the wrong choice, it could be fixed by casting the constant to the
566+
array's element type; but explicit use of <function>array_append</> might
567+
be a preferable solution.
568+
</para>
534569
</sect2>
535570

536571
<sect2 id="arrays-searching">

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp