PHP RFC: iterable_to_array() and iterable_count()
- Version: 1.0
- Date: 2018-06-19
- Author: Michael Moravec (php.net@majkl578.cz)
- Status: Declined
- First Published at: https://wiki.php.net/rfc/iterable_to_array-and-iterable_count
Introduction
PHP 7.1 added an iterable pseudo-type which is a union of array and Traversable. Although iterable is very useful, sometimes it's necessary to convert it to an array (i.e. for array_*() functions or for compatibility with older code).
Proposal
PHP currently has iterator_to_array(), iterator_count() and iterator_apply(). Unfortunately these functions are incompatible with iterable as they only work with iterators, not arrays.
In order to transform an iterable to an array, one has to write code as such:
is_array($iterable) ? $iterable : iterator_to_array($iterable) is_array($iterable) ? count($iterable) : iterator_count($iterable)
Besides being error-prone, this code makes iterables much harder to work with.
In order to improve user experience and ease adoption of iterables, two new functions should help mitigate the code above, basically expanding behavior of iterator_to_array() and iterator_count() to work also with arrays.
iterable_to_array()
The following code:
is_array($iterable) ? $iterable : iterator_to_array($iterable)
Is now replaced by simple:
iterable_to_array($iterable)
This function's behavior is similar to iterator_to_array():
- when an array is given:
- when $use_keys = true: array is returned as-is, unchanged
- when $use_keys = false: array is returned as a list, similar to array_values()
- when an iterator is given:
- when $use_keys = true: iterator is converted to an array, preserving the keys (same behavior as iterator_to_array())
- when $use_keys = false: iterator is converted to an array as a list, ignoring the keys (same behavior as iterator_to_array())
In order to stay consistent with iterator_to_array(), the $use_keys behavior is retained.
iterable_count()
The following code:
is_array($iterable) ? count($iterable) : iterator_count($iterable)
Is now replaced by simple:
iterable_count($iterable)
This function's behavior is similar to iterator_count():
- when an array is given: returns the number of elements contained in the array (same as count())
- when an iterator is given: returns the number of elements contained in the iterator (same as iterator_count())
Backward Incompatible Changes
None.
Proposed PHP Version(s)
next 7.x
RFC Impact
Two new SPL functions which could collide with user-land functions. Since iterable type is still quite new, the risk should be relatively low.
To SAPIs
None.
To Existing Extensions
None.
To Opcache
None.
Future Scope
Since these new functions provide a superset of features provided by iterator_to_array() and iterator_count(), these could be deprecated later on.
In case these functions gain a popularity, they could be optimized directly by VM, similar to ZEND_COUNT.
Vote
This is not a language change so simple yes/no vote with 50%+1 majority is required.
Voting starts on 2018-07-03 20:30 UTC and closes on 2018-07-16 23:00 UTC.
.
Patches and Tests
GitHub PR: https://github.com/php/php-src/pull/3293