iterable_to_array() and iterable_count() View as Markdown

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.

Vote: Add iterable_to_array()? — Yes: 8 · No: 24 (closed)

.

Vote: Add iterable_count()? — Yes: 2 · No: 35 (closed)

Patches and Tests

GitHub PR: https://github.com/php/php-src/pull/3293