rfc:array_key_first_last_index

Differences

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

Link to this comparison view

rfc:array_key_first_last_index [2016/01/01 20:11]
jbafford
rfc:array_key_first_last_index [2017/09/22 13:28]
Line 1: Line 1:
-====== PHP RFC: array_key_(first|last|index) ====== 
-  * Version: 1.0 
-  * Date: 2015-12-05 
-  * Author: John Bafford 
-  * Status: Draft 
-  * First Published at: http://wiki.php.net/rfc/array_key_first_last_index 
- 
- 
-===== Introduction ===== 
-This RFC and its accompanying patch add the following functions: 
- 
-  * $key = array_key_first($array [, &$value]) 
-  * $key = array_key_last($array [, &$value]) 
-  * $key = array_key_index($array, $index [, &$value]) 
- 
-===== Proposal ===== 
-array_key_first() returns the first key in an array. 
- 
-array_key_last() returns the last key in an array. 
- 
-array_key_index() returns the key at a specified index (using a substr-like offset; greater-than or equal to zero starts from the beginning of the array; negative from the end). 
- 
-<code php> 
-$arr ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4]; 
- 
-$key = array_key_first($arr); //$key === 'a' 
- 
-$key = array_key_last($arr, $val); //$key === 'd', $val === 4 
- 
-$key = array_key_index($arr, 1); //$key === 'b' 
-$key = array_key_index($arr, -2); //$key === 'c' 
-$key = array_key_index($arr, 5, $val); //$key === NULL, $val is unchanged 
- 
- 
-// Also works for numeric arrays 
-$numeric = [1 => 1, 5 => 2, 2 => 3]; 
-$key = array_key_index($numeric, 0); //$key === 1 
-$key = array_key_index($numeric, 1); //$key === 5 
-$key = array_key_index($numeric, 2); //$key === 2 
-</code> 
- 
- 
-All three functions return the requested array key, or null if the requested array key is not found (an empty array, or an out-of-bounds index in the case of array_key_index). For convenience, each function also takes an optional $value parameter that, if provided and the specified index is found, will be set to contain the value at the specified index. 
- 
- 
-There are certain use-cases that require getting the first key of an array (and to a much lesser extent, the last key, or an arbitrary key by index order). There are three ways this could be done with existing php functionality, all of which have significant drawbacks, in either performance, legibility, or mutability: 
- 
-  * array_keys($arr)[0] 
-    * array_keys() is non-performant for this task. It requires the relatively expensive operation of iterating over an entire array and building a new array whose values are the keys of the original, when only one single key is needed. Additionally, bounds-checking must be done in php code. 
-    * Retrieving the last key requires either of the more complicated constructs, array_keys(array_reverse($arr))[0]; or array_keys($arr)[count($arr) - 1] 
- 
-  * foreach($arr as $key => $value) { break; } 
-    * This is a confusing construct to read. An iteration over the array must be started, stopped after one element, and as a side-effect, $key contains the first key in the array after the loop is stopped. Also, an emptiness check on the array must occur, or, $key initialized prior to the loop to handle the empty array case. 
-    * In PHP < 7, this also modifies the array by changing the array pointer. 
-    * Retrieving the last key can be done by either of these more complicated/confusing constructs: 
-      * foreach(array_reverse($arr) as $key => $value) { break; } 
-      * foreach($arr as $key => $value); //Iterate over the entire array, doing nothing, just for the side-effect of $key still contains the last array key beyond the end of the loop.// 
- 
-  * reset($arr); $key = current($arr); 
-    * This modifies the array (resets the array pointer). 
-    * There is no simple way to get either the last key or an indexed key via this method. 
- 
- 
-With the reference implementation provided below, array_key_first() and array_key_last() directly retrieve the array key from the underlying hash (by setting a local hash pointer to the start/end of the array and retrieving the key for that index). By necessity, array_key_index() iterates through the keys, but does so in C code, rather than in PHP code. 
- 
-===== Backward Incompatible Changes ===== 
-None. 
- 
-===== Proposed PHP Version(s) ===== 
-Next PHP 7.x. 
- 
-===== RFC Impact ===== 
-As this RFC only adds new functions, it should not cause any impact to SAPIs, other extensions, or opcache. 
- 
-===== Open Issues ===== 
-None noted at this time. 
- 
-===== Proposed Voting Choices ===== 
-  * Whether to accept the RFC for PHP 7.1. 
- 
-This RFC does not add new syntax, so a 50%+1 majority is required to pass. 
- 
-===== Patches and Tests ===== 
-The GitHub Pull request for this change is here: https://github.com/php/php-src/pull/347 
- 
-This is a full and working implementation, and if accepted, could be merged as-is. 
- 
-===== Implementation ===== 
-After the project is implemented, this section should contain  
-  - the version(s) it was merged to 
-  - a link to the git commit(s) 
-  - a link to the PHP manual entry for the feature 
  
rfc/array_key_first_last_index.txt · Last modified: 2017/09/22 13:28 (external edit)