Doc #80295 [Opn->Ver]: + operator on arrays is documented as Union but it's not
Edit report at https://bugs.php.net/bug.php?id=80295&edit=1
ID: 80295
Updated by: cmb@php.net
Reported by: rimas at kudelis dot lt
Summary: + operator on arrays is documented as Union but it's
not
-Status: Open
+Status: Verified
Type: Documentation Problem
Package: Arrays related
PHP Version: Irrelevant
Block user comment: N
Private report: N
New Comment:
> Personally, I would avoid the term "union" entirely. It's too
> misleading.
I agree, except for when arrays are used as sets, where the index
specifies the element, and its value is always the same (e.g.
bool(true)), in which case this operation actually is set union.
Previous Comments:
------------------------------------------------------------------------
[2020-10-29 23:32:21] requinix@php.net
Personally, I would avoid the term "union" entirely. It's too misleading.
I think of + for arrays as a "fill in the blanks" operator. Or a "with defaults"
operator. The LHS is the base array, and the RHS will provide additional values for the keys that do
not exist in the base array.
Essentially, $a + $b is equivalent to array_replace($b, $a).
https://3v4l.org/dXl11
Note that's array_replace and not array_merge, and that the arguments are backwards from how
they're used in the operator.
The primary use case for me has been about dealing with missing/optional data from an associative
array: take the provided values and "fill in" what wasn't given from a set of
defaults.
https://3v4l.org/SuAln
------------------------------------------------------------------------
[2020-10-29 13:53:17] rimas at kudelis dot lt
Description:
------------
The documentation for array operators currently says this:
> $a + $b Union Union of $a and $b.
At least to me, this signals that if I apply this operator on two arrays (e.g. [1, 2] and [3, 4, 5,
6]), I would get an array which holds all elements appearing in each array: [1, 2, 3, 4, 5, 6]. But
that's not what I get. Instead, I get [1, 2, 5, 6], as documented in a note below the initial
table:
> The + operator returns the right-hand array appended to the left-hand array; for
> keys that exist in both arrays, the elements from the left-hand array will be
> used, and the matching elements from the right-hand array will be ignored.
as well as in a set of examples below.
I believe it's wrong to refer to this operation as simply union, thus I suggest to change the
documentation to make it more obvious upfront.
I don't have a good idea how to reword it exactly ATM, but perhaps just changing
"Union" to "Union by keys" in the table would be enough?
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=80295&edit=1
Thread (3 messages)