- Version: 2.0
- Date: 2016-11-21
- Author: @WesNetmo on Twitter - with Room 11's help
- Status: Under Discussion
- First Published at: https://wiki.php.net/rfc/arrayiterator-improvements
This RFC proposes the addition of a couple of functions that would expose to userland important features of PHP's (linked) hash-tables.
ArrayIterator::seekKey($key):void (throws OutOfBoundsException)
This method would move the Iterator's cursor to the Entry identified by the key
The existing method
ArrayIterator::seek($position) searches for the Entry in a linear manner, and this is not ideal for many uses, as what it does is simply iterating over the array (or part of it) to reach the specified position (or key, assuming the array is a list). Instead, the proposed method
ArrayIterator::seekKey($key) would be a
O(1) operation as the cursor can immediately jump to the Entry identified by the given
Specifically, if the given key is present in the array the method would successfully execute such that subsequent calls to
ArrayIterator::current() would get the value associated with the specified
ArrayIterator::key() would get
$key and so on, like it would normally behave when iterating over the Entry. Instead, if the provided key is not present in the array, and exactly like
ArrayIterator::seek($position), the method would throw a
OutOfBoundsException and keep the current
ArrayIterator's cursor state.
This method would simply move the Iterator's cursor to the previous Entry in the hash table's linked list. Exactly like
ArrayIterator::next(), it would never throw and it would always return
null. However, if there is no previous Entry, immediate calls to the
valid() method would return
Backward Incompatible Changes
None, for both of the proposed methods.
Proposed PHP Version(s)
Proposed Voting Choices
Accept ArrayIterator::seekKey($key) for PHP 7.2?
* vote 1 *
Accept ArrayIterator::prev() for PHP 7.2?
* vote 2 *
Patches and Tests