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 15:22]
ramsey
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 32: Line 29:
 **columnKey** **columnKey**
  
-> The column of values to return. This value may be the 0-indexed number ​of the column you wish to retrieve, or it may be the string key name for an associative array.+> The column of values to return. This value may be the integer key of the column you wish to retrieve, or it may be the string key name for an associative array.
  
 **indexKey** **indexKey**
  
-> (Optional.) The column to use as the index/keys for the returned array. This value may be the 0-indexed number ​of the column, or it may be the string key name.+> (Optional.) The column to use as the index/keys for the returned array. This value may be the integer key of the column, or it may be the string key name.
  
 ==== Return Values ==== ==== Return Values ====
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.1358004134.txt.gz · Last modified: 2017/09/22 13:28 (external edit)