rfc:array_key_first_last_index

Differences

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

Link to this comparison view

Next revision		Previous revision
Next revisionBoth sides next revision
rfc:array_key_first_last_index [2015/12/07 17:07] – created jbaffordrfc:array_key_first_last_index [2016/01/01 20:19] – jbafford
Line 15: Line 15:
  
 ===== Proposal ===== ===== Proposal =====
 +Arrays in php are ordered maps, but there is no convenient way to 
 +
 array_key_first() returns the first key in an array. array_key_first() returns the first key in an array.
  
 array_key_last() returns the last 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; positive starts from the beginning of the array; negative from the end).+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).
  
-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). Each function also takes an optional $value parameter that returns the value at the specified index. (This is strictly for convenience, and is not an essential part of this RFC.)+<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.
  
  
Line 35: Line 57:
     * Retrieving the last key can be done by either of these more complicated/confusing constructs:     * Retrieving the last key can be done by either of these more complicated/confusing constructs:
       * foreach(array_reverse($arr) as $key => $value) { break; }       * foreach(array_reverse($arr) as $key => $value) { break; }
-      * foreach($arr as $key => $value); //Iterate over the entire array; as a possibly unexpected side-effect, $key still contains the last array key beyond the end of the loop.//+      * 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);   * reset($arr); $key = current($arr);
Line 43: Line 65:
  
 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. 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.
 +
 +In the proposed PR implementing this functionality (see below), array_key_first() and array_key_last() are implemented in terms of array_key_index(); array_key_index() exists a a consequence and extension of generalizing the common code between array_key_first() and array_key_last().
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 71: Line 95:
   - a link to the git commit(s)   - a link to the git commit(s)
   - a link to the PHP manual entry for the feature   - a link to the PHP manual entry for the feature
- 
rfc/array_key_first_last_index.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools