rfc:array_key_first_last

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
rfc:array_key_first_last [2018/06/14 22:07]
wol-soft Add open issue: missing corresponding functions to handle values of the outer array elements
rfc:array_key_first_last [2018/06/19 09:22] (current)
wol-soft Extend the scope of this RFC to add also functions for array value handling
Line 1: Line 1:
-====== PHP RFC: array_key_first() ​and array_key_last() ====== +====== PHP RFC: array_key_first()array_key_last() and array_value_first(),​ array_value_last() ====== 
-  * Version: 1.0+  * Version: 1.1
   * Date: 2018-06-11   * Date: 2018-06-11
   * Author: Enno Woortmann<​enno.woortmann@web.de> ​   * Author: Enno Woortmann<​enno.woortmann@web.de> ​
Line 7: Line 7:
  
 ===== Introduction ===== ===== Introduction =====
-As arrays are a powerful data structure it's handy in some cases to get the first or the last key of an array without a workaround. To accomplish this task this RFC adds two functions to the core:+As arrays are a powerful data structure it's handy in some cases to get the first or the last key/​value ​of an array without a workaround. To accomplish this task this RFC adds four functions to the core:
   * $key = array_key_first($array);​   * $key = array_key_first($array);​
   * $key = array_key_last($array);​   * $key = array_key_last($array);​
 +  * $value = array_value_first($array);​
 +  * $value = array_value_last($array);​
  
 ===== Proposal ===== ===== Proposal =====
-The current functions of the PHP core only allow to retrieve the first/last key of an array by changing the internal state of the array when using the functions reset(), end() and key(). Other implementation approaches are either inperformant (eg. usage of array_keys($array)[0],​ which additionally may lead to errors if $array is an empty array) or provide a construct which increases the cognitive complexity of the implementation (eg. usage of loops).+The current functions of the PHP core only allow to retrieve the first/last key/​value ​of an array by changing the internal state of the array when using the functions reset(), end() and key(). Other implementation approaches are either inperformant (eg. usage of array_keys($array)[0] ​to gather the first key, which additionally may lead to errors if $array is an empty array) or provide a construct which increases the cognitive complexity of the implementation (eg. usage of loops).
  
-To avoid changes of the internal array representation in order to gather a single information from the array and to increase the comprehensibility of the userland code this RFC proposes ​two new functions for this task:+To avoid changes of the internal array representation in order to gather a single information from the array and to increase the comprehensibility of the userland code this RFC proposes new functions for this task. Two functions for the handling of array keys and two functions for the handling of array values:
  
-To gather the key of the **first** element of an array the method **array_key_first($array)** will be added.+To gather the **key** of the **first** element of an array the method **array_key_first($array)** will be added.
  
-To gather the key of the **last** element of an array the method **array_key_last($array)** will be added.+To gather the **key** of the **last** element of an array the method **array_key_last($array)** will be added. 
 + 
 +The usage of the methods to handle the keys will look like:
  
 <code php> <code php>
Line 49: Line 53:
 </​code>​ </​code>​
  
-The functions either return the requested key or null if an empty array is provided.+To gather the **value** of the **first** element of an array the method **array_value_first($array)** will be added. 
 + 
 +To gather the **value** of the **last** element of an array the method **array_value_last($array)** will be added. 
 + 
 +The usage of the methods to handle the values will look like: 
 + 
 +<code php> 
 +// usage of an associative array 
 +$array = ['​a'​ => 1, '​b'​ => 2, '​c'​ => 3]; 
 + 
 +$firstValue = array_value_first($array);​ 
 +$lastValue = array_value_last($array);​ 
 + 
 +assert($firstValue === 1); 
 +assert($lastValue === 3); 
 + 
 +// usage of a numeric array 
 +$array = [1 => '​a',​ 2 => '​b',​ 3 => '​c'​];​ 
 + 
 +$firstValue = array_value_first($array);​ 
 +$lastValue = array_value_last($array);​ 
 + 
 +assert($firstValue === '​a'​);​ 
 +assert($lastValue === '​c'​);​ 
 + 
 +// usage of an empty array 
 +$array = []; 
 + 
 +$firstValue = array_value_first($array);​ 
 +$lastValue = array_value_last($array);​ 
 + 
 +assert($firstValue === null); 
 +assert($lastValue === null); 
 +</​code>​ 
 + 
 +All four functions either return the requested key/​value ​or null if an empty array is provided
 +If a non array parameter is given, a warning will be triggered and null will be returned.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 58: Line 98:
  
 ===== RFC Impact ===== ===== RFC Impact =====
-As this RFC adds two new functions there is a possible impact on existing userland extensions where developers created helper functions with an identical name. As the functions proposed provide a meaningful name custom functions should implement an identical functionality and thus be replaceable.+As this RFC adds four new functions there is a possible impact on existing userland extensions where developers created helper functions with an identical name. As the functions proposed provide a meaningful name custom functions should implement an identical functionality and thus be replaceable.
  
 There is no impact to SAPIs or the opcache. There is no impact to SAPIs or the opcache.
- 
-===== Open Issues ===== 
-To provide a complete set of functions to the PHP community the corresponding functions for handling the values of an array (eg. **array_value_first()** and **array_value_last()**) are still missing after implementing the current scope of this RFC. To resolve this issue there are three possibilities to be discussed: 
-  * Expand the scope of this RFC to implement a complete set of functions to handle the outer elements of an array 
-  * Add a future scope to this RFC to add those functions 
-  * Skip the implementation of those functions 
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
Line 80: Line 114:
   - a link to the PHP manual entry for the feature   - a link to the PHP manual entry for the feature
   - a link to the language specification section (if any)   - a link to the language specification section (if any)
 +
 +===== History =====
 +==== Version 1.1 ====
 +  * Extended the scope of this RFC to also cover functions for the handling of values to provide a complete function set for working with outer array elements.
  
rfc/array_key_first_last.1529014041.txt.gz · Last modified: 2018/06/14 22:07 by wol-soft