rfc:array_column

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
rfc:array_column [2013/01/12 16:45] – Change "0-indexed number" to "integer key" ramseyrfc:array_column [2017/09/22 13:28] (current) – external edit 127.0.0.1
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)