rfc:array_column

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:array_column [2013/01/12 16:45]
ramsey Change "0-indexed number" to "integer key"
rfc:array_column [2017/09/22 13:28] (current)
Line 1: Line 1:
 ====== Request for Comments: array_column ====== ====== Request for Comments: array_column ======
  
-  * Version: 2.2+  * Version: 2.4
   * Date: 2013-01-11   * Date: 2013-01-11
   * Author: Ben Ramsey <​ramsey@php.net>​   * Author: Ben Ramsey <​ramsey@php.net>​
-  * Status: ​Voting+  * Status: ​Implemented in PHP 5.5
   * First Published at: http://​wiki.php.net/​rfc/​array_column   * First Published at: http://​wiki.php.net/​rfc/​array_column
  
Line 18: Line 18:
  
   array array_column(array $input, mixed $columnKey[,​ mixed $indexKey])   array array_column(array $input, mixed $columnKey[,​ mixed $indexKey])
-  array array_pluck(array $input, mixed $columnKey[,​ mixed $indexKey]) 
  
 ''​array_column()''​ returns the values from a single column of the //​**input**//​ array, identified by the //​**columnKey**//​. Optionally, you may provide an //​**indexKey**//​ to index the values in the returned array by the values from the //​**indexKey**//​ column in the //​**input**//​ array. ''​array_column()''​ returns the values from a single column of the //​**input**//​ array, identified by the //​**columnKey**//​. Optionally, you may provide an //​**indexKey**//​ to index the values in the returned array by the values from the //​**indexKey**//​ column in the //​**input**//​ array.
- 
-''​array_pluck()''​ is an alias of ''​array_column()''​. 
  
 ==== Parameters ==== ==== Parameters ====
Line 64: Line 61:
         '​first_name'​ => '​Jane',​         '​first_name'​ => '​Jane',​
         '​last_name'​ => '​Jones'​         '​last_name'​ => '​Jones'​
 +    ),
 +    array(
 +        '​id'​ => 5623,
 +        '​first_name'​ => '​Peter',​
 +        '​last_name'​ => '​Doe'​
     )     )
 ); );
Line 79: Line 81:
     [1] => Sally     [1] => Sally
     [2] => Jane     [2] => Jane
 +    [3] => Peter
 ) )
 </​code>​ </​code>​
Line 111: Line 114:
 <code php> <code php>
 <?php <?php
-// Array representing a possible record set returned from a database +// Using the $records array from Example #1
-$records ​array+
-    array( +
-        '​id'​ => 2135, +
-        '​first_name'​ => '​John',​ +
-        '​last_name'​ => '​Doe'​ +
-    ), +
-    array( +
-        '​id'​ => 3245, +
-        '​first_name'​ => '​Sally',​ +
-        '​last_name'​ => '​Smith'​ +
-    ), +
-    array( +
-        '​id'​ => 5342, +
-        '​first_name'​ => '​Jane',​ +
-        '​last_name'​ => '​Jones'​ +
-    ) +
-); +
 $lastNames = array_column($records,​ '​last_name',​ '​id'​);​ $lastNames = array_column($records,​ '​last_name',​ '​id'​);​
 print_r($lastNames);​ print_r($lastNames);​
Line 142: Line 127:
     [3245] => Smith     [3245] => Smith
     [5342] => Jones     [5342] => Jones
 +    [5623] => Doe
 +)
 +</​code>​
 +
 +=== Example #4: Mismatched columns ===
 +
 +With ''​array_column()''​ the relationship in finding the values of //​**columnKey**//​ to //​**indexKey**//​ is much like that of a SQL left join. All values of the //​**columnKey**//​ are returned. When a corresponding //​**indexKey**//​ cannot be found, the value will be keyed with an integer, starting from zero.
 +
 +The following examples will all use the same **$mismatchedColumns** array defined here:
 +
 +<code php>
 +<?php
 +$mismatchedColumns = array(
 +    array(
 +        '​a'​ => '​foo',​
 +        '​b'​ => '​bar',​
 +        '​e'​ => '​baz'​
 +    ),
 +    array(
 +        '​a'​ => '​qux',​
 +        '​c'​ => '​quux',​
 +        '​d'​ => '​corge'​
 +    ),
 +    array(
 +        '​a'​ => '​grault',​
 +        '​b'​ => '​garply',​
 +        '​e'​ => '​waldo'​
 +    ),
 +);
 +</​code>​
 +
 +In this example, all rows contain an "​a"​ key, but only two contain a "​b"​ key. If we want to retrieve all "​a"​ values and key them by "​b"​ values, then ''​array_column()''​ behaves like this:
 +
 +<code php>
 +<?php
 +$foo = array_column($mismatchedColumns,​ '​a',​ '​b'​);​
 +$bar = array('​bar'​ => '​foo',​ '​qux',​ '​garply'​ => '​grault'​);​
 +
 +/*
 +Both $foo and $bar contain values that look like this:
 +
 +Array
 +(
 +    [bar] => foo
 +    [0] => qux
 +    [garply] => grault
 +)
 +*/
 +</​code>​
 +
 +However, if we want to retrieve all "​b"​ values and key them by "​a"​ values, we will only have two elements in the resulting array, since only two rows contain "​b"​ values.
 +
 +<code php>
 +// There is a corresponding "​a"​ value for each "​b"​ value
 +print_r(array_column($mismatchedColumns,​ '​b',​ '​a'​));​
 +
 +/*
 +Array
 +(
 +    [foo] => bar
 +    [grault] => garply
 +)
 +*/
 +
 +// There are no corresponding "​c"​ values for either "​b"​ value
 +print_r(array_column($mismatchedColumns,​ '​b',​ '​c'​));​
 +
 +/*
 +Array
 +(
 +    [0] => bar
 +    [1] => garply
 +)
 +*/
 +</​code>​
 +
 +=== Example #5: indexKey Collisions ===
 +
 +In the event that more than one row contains the same value for //​**indexKey**//,​ then the last //​**columnKey**//​ value for that //​**indexKey**//​ will overwrite the previous value.
 +
 +<code php>
 +// Using the $records array from Example #1
 +$firstNames = array_column($records,​ '​first_name',​ '​last_name'​);​
 +print_r($firstNames);​
 +
 +/*
 +Array
 +(
 +    [Doe] => Peter
 +    [Smith] => Sally
 +    [Jones] => Jane
 ) )
 +*/
 </​code>​ </​code>​
  
Line 157: Line 234:
 Voting ends not before Friday, January 18, 2013. The PHP language is not changed, so a 50% + 1 majority is required. Voting ends not before Friday, January 18, 2013. The PHP language is not changed, so a 50% + 1 majority is required.
  
-<doodle title="​Accept array_column() for inclusion in PHP?" auth="​user"​ voteType="​single"​ closed="​false">+<doodle title="​Accept array_column() for inclusion in PHP?" auth="​user"​ voteType="​single"​ closed="​true">
    * Yes    * Yes
    * No    * No
Line 168: Line 245:
   * 2.1 (2013-01-11):​ Adding link to new pull request: https://​github.com/​php/​php-src/​pull/​257   * 2.1 (2013-01-11):​ Adding link to new pull request: https://​github.com/​php/​php-src/​pull/​257
   * 2.2 (2013-01-11):​ Opened voting   * 2.2 (2013-01-11):​ Opened voting
 +  * 2.3 (2013-01-12):​ Updates to the RFC (new examples, etc.), based on mailing list feedback
 +  * 2.4 (2013-01-14):​ Removed array_pluck() alias
rfc/array_column.1358009112.txt.gz · Last modified: 2017/09/22 13:28 (external edit)