rfc:array_find
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
rfc:array_find [2024/04/07 13:37] – josh | rfc:array_find [2024/06/01 11:23] (current) – Status: Implemented josh | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== PHP RFC: array_find ====== | ====== PHP RFC: array_find ====== | ||
- | * Version: | + | * Version: |
- | * Date: 2024-03-31 | + | * Date: 2024-04-07 |
* Author: Joshua Rüsweg, josh@php.net | * Author: Joshua Rüsweg, josh@php.net | ||
- | * Status: | + | * Status: |
* First Published at: https:// | * First Published at: https:// | ||
+ | * Discussion: https:// | ||
+ | * Implementation: | ||
===== Introduction ===== | ===== Introduction ===== | ||
- | This RFC proposes the addition of a new function | + | This RFC proposes the addition of new array functions: |
- | There are currently | + | There are currently |
===== Proposal ===== | ===== Proposal ===== | ||
- | Add a new function < | + | This RFC proposes to add four new function, < |
+ | |||
+ | ==== array_find ==== | ||
+ | |||
+ | < | ||
<PHP> | <PHP> | ||
- | function array_find(array $array, callable $callback, bool $return_array_key = false): mixed {} | + | function array_find(array $array, callable $callback): mixed { |
+ | foreach ($array as $key => $value) { | ||
+ | if ($callback($value, | ||
+ | return $value; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | return null; | ||
+ | } | ||
</ | </ | ||
- | ==== Parameters | + | === Parameters === |
< | < | ||
Line 28: | Line 42: | ||
< | < | ||
- | The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns true, the value (or key) is returned from < | + | The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns |
- | < | + | === Return Value === |
- | If this parameter is < | + | The function returns the value of the first element for which the < |
- | ==== Return Value ==== | + | === Examples === |
- | + | ||
- | The function returns the first entry for which the < | + | |
- | + | ||
- | ==== Examples | + | |
<PHP> | <PHP> | ||
Line 55: | Line 65: | ||
})); // string(5) " | })); // string(5) " | ||
- | // Find the first animal whose name begins with f. | + | // Find the first animal whose name begins with f. |
var_dump(array_find($array, | var_dump(array_find($array, | ||
- | return str_starts_with($value, | + | return str_starts_with($value, |
})); // NULL | })); // NULL | ||
- | // Find the key corresponding to the first animal | + | // Find the first animal where the array key is the first symbol of the animal. |
- | var_dump(array_find($array, | + | |
- | return strlen($value) > 4; | + | |
- | }, true)); // string(1) " | + | |
- | + | ||
- | // Find the first animal whose where the array key is the first symbol of the animal. | + | |
var_dump(array_find($array, | var_dump(array_find($array, | ||
| | ||
})); // string(3) " | })); // string(3) " | ||
+ | |||
+ | // Find the first animal where the array key matching a RegEx. | ||
+ | var_dump(array_find($array, | ||
+ | | ||
+ | })); // string(3) " | ||
+ | </ | ||
+ | |||
+ | ==== array_find_key ==== | ||
+ | < | ||
+ | |||
+ | <PHP> | ||
+ | function array_find_key(array $array, callable $callback): mixed { | ||
+ | foreach ($array as $key => $value) { | ||
+ | if ($callback($value, | ||
+ | return $key; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | return null; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === Parameters === | ||
+ | |||
+ | < | ||
+ | |||
+ | The array that should be searched. | ||
+ | |||
+ | < | ||
+ | |||
+ | The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns < | ||
+ | |||
+ | === Return Value === | ||
+ | The function returns the key of the first element for which the < | ||
+ | |||
+ | === Examples === | ||
+ | |||
+ | <PHP> | ||
+ | $array = [ | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ]; | ||
+ | |||
+ | // Find the first animal with a name longer than 4 characters. | ||
+ | var_dump(array_find_key($array, | ||
+ | return strlen($value) > 4; | ||
+ | })); // string(1) " | ||
+ | |||
+ | // Find the first animal whose name begins with f. | ||
+ | var_dump(array_find_key($array, | ||
+ | return str_starts_with($value, | ||
+ | })); // NULL | ||
+ | |||
+ | // Find the first animal where the array key is the first symbol of the animal. | ||
+ | var_dump(array_find_key($array, | ||
+ | | ||
+ | })); // string(1) " | ||
+ | |||
+ | // Find the first animal where the array key matching a RegEx. | ||
+ | var_dump(array_find_key($array, | ||
+ | | ||
+ | })); // string(1) " | ||
+ | </ | ||
+ | |||
+ | ==== array_any ==== | ||
+ | |||
+ | < | ||
+ | |||
+ | <PHP> | ||
+ | function array_any(array $array, callable $callback): bool { | ||
+ | foreach ($array as $key => $value) { | ||
+ | if ($callback($value, | ||
+ | return true; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | return false; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === Parameters === | ||
+ | |||
+ | < | ||
+ | |||
+ | The array that should be searched. | ||
+ | |||
+ | < | ||
+ | |||
+ | The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns < | ||
+ | |||
+ | === Return Value === | ||
+ | |||
+ | The function returns < | ||
+ | |||
+ | === Examples === | ||
+ | |||
+ | <PHP> | ||
+ | $array = [ | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ]; | ||
+ | |||
+ | // Check, if any animal name is longer than 5 letters. | ||
+ | var_dump(array_any($array, | ||
+ | return strlen($value) > 5; | ||
+ | })); // bool(true) | ||
+ | |||
+ | // Check, if any animal name is shorter than 3 letters. | ||
+ | var_dump(array_any($array, | ||
+ | return strlen($value) < 3; | ||
+ | })); // bool(false) | ||
+ | |||
+ | // Check, if any array key is not a string. | ||
+ | var_dump(array_any($array, | ||
+ | | ||
+ | })); // bool(false) | ||
+ | </ | ||
+ | |||
+ | ==== array_all ==== | ||
+ | |||
+ | < | ||
+ | |||
+ | <PHP> | ||
+ | function array_all(array $array, callable $callback): bool { | ||
+ | foreach ($array as $key => $value) { | ||
+ | if (!$callback($value, | ||
+ | return false; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | return true; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === Parameters === | ||
+ | |||
+ | < | ||
+ | |||
+ | The array that should be searched. | ||
+ | |||
+ | < | ||
+ | |||
+ | The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns < | ||
+ | |||
+ | === Return Value === | ||
+ | |||
+ | The function returns < | ||
+ | |||
+ | === Examples === | ||
+ | |||
+ | <PHP> | ||
+ | $array = [ | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ]; | ||
+ | |||
+ | // Check, if all animal names are shorter than 12 letters. | ||
+ | var_dump(array_all($array, | ||
+ | return strlen($value) < 12; | ||
+ | })); // bool(true) | ||
+ | |||
+ | // Check, if all animal names are longer than 5 letters. | ||
+ | var_dump(array_all($array, | ||
+ | return strlen($value) > 5; | ||
+ | })); // bool(false) | ||
+ | |||
+ | // Check, if all array keys are strings. | ||
+ | var_dump(array_all($array, | ||
+ | | ||
+ | })); // bool(true) | ||
</ | </ | ||
===== Backward Incompatible Changes ===== | ===== Backward Incompatible Changes ===== | ||
- | Functions created by the user and named < | + | Functions created by the user and named < |
+ | |||
+ | Looking at the search results I estimate about 30% of these results are functions that are not located in a namespace, are not part of a class and are not false-positvies (e.g. the symbol is < | ||
===== Proposed PHP Version(s) ===== | ===== Proposed PHP Version(s) ===== | ||
Line 102: | Line 291: | ||
===== Open Issues ===== | ===== Open Issues ===== | ||
- | None. | + | This function behaves differently to < |
===== Unaffected PHP Functionality ===== | ===== Unaffected PHP Functionality ===== | ||
- | This RFC only adds a new function | + | This RFC only adds two new functions |
+ | |||
+ | ===== Proposed Voting Choices ===== | ||
+ | |||
+ | Each vote requires a 2/3 majority. | ||
+ | |||
+ | Voting started on 2024-05-15 and will end on 2024-05-29 15:00 UTC. | ||
+ | |||
+ | ==== array_find()/ | ||
+ | |||
+ | <doodle title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
+ | |||
+ | |||
+ | ==== array_any()/ | ||
+ | |||
+ | <doodle title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
===== Implementation ===== | ===== Implementation ===== | ||
- | https:// | + | https:// |
===== References ===== | ===== References ===== | ||
- | [1] GitHub currently has [[https:// | + | * GitHub currently has [[https:// |
+ | * https:// | ||
+ | * https:// | ||
+ | * https:// | ||
+ | * https:// | ||
+ | * https:// | ||
+ | * https:// | ||
+ | * https:// | ||
+ | * https:// |
rfc/array_find.1712497045.txt.gz · Last modified: 2024/04/07 13:37 by josh