php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #80295 + operator on arrays is documented as Union but it's not
Submitted: 2020-10-29 13:53 UTC Modified: 2021-11-15 16:33 UTC
Votes:1
Avg. Score:3.0 ± 0.0
Reproduced:0 of 0 (0.0%)
From: rimas at kudelis dot lt Assigned:
Status: Verified Package: Arrays related
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If you forgot your password, you can retrieve your password here.
Password:
Status:
Package:
Bug Type:
Summary:
From: rimas at kudelis dot lt
New email:
PHP Version: OS:

 

 [2020-10-29 13:53 UTC] 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?

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2020-10-29 23:32 UTC] requinix@php.net
-Package: Documentation problem +Package: Arrays related
 [2020-10-29 23:32 UTC] 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
 [2021-11-15 16:33 UTC] cmb@php.net
-Status: Open +Status: Verified
 [2021-11-15 16:33 UTC] cmb@php.net 
> 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.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved. 		Last updated: Sat Dec 21 17:01:58 2024 UTC