====== 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 //iterable//s much harder to work with.

In order to improve user experience and ease adoption of //iterable//s, 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.

<doodle title="Add iterable_to_array()?" auth="majkl" voteType="single" closed="true">
   * Yes
   * No
</doodle>
.
<doodle title="Add iterable_count()?" auth="majkl" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

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