rfc:arrayiterator-improvements

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
rfc:arrayiterator-improvements [2016/11/21 17:16] wesnetmorfc:arrayiterator-improvements [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
-====== ArrayIterator improvements for PHP's (linked) hash tables ======+====== ArrayIterator improvements ======
  
-  * Version: 1.0+  * Version: 2.0
   * Date: 2016-11-21   * Date: 2016-11-21
   * Author: @WesNetmo on Twitter - with Room 11's help   * Author: @WesNetmo on Twitter - with Room 11's help
-  * Status: Draft+  * Status: Under Discussion
   * First Published at: https://wiki.php.net/rfc/arrayiterator-improvements   * First Published at: https://wiki.php.net/rfc/arrayiterator-improvements
  
Line 11: Line 11:
 This RFC proposes the addition of a couple of functions that would expose to userland important features of PHP's (linked) hash-tables. 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):bool =====+===== ArrayIterator::seekKey($key):void (throws OutOfBoundsException) =====
  
 This method would move the Iterator's cursor to the Entry identified by the key ''$key''. This method would move the Iterator's cursor to the Entry identified by the key ''$key''.
  
-After calling this method''ArrayIterator::current()'' would return the value associated with the specified ''$key'', ''ArrayIterator::key()'' will return ''$key'' and so on. If the ''$key'' doesn't exist the method would return ''false'' and Iterator would keep its current state, otherwise the method would return ''true''.+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 ''$key''.
  
-The existing ''ArrayIterator::seek($position)'' searches for the Entry in a linear manner, and this is not ideal for many usesas what it does is simply iterating over the array to reach the specified position (or key, assuming the array is a list). Insteadthe proposed method ''ArrayIterator::seekKey($key)'' is a ''O(1)'' operation as the cursor can immediately jump to the Entry identified by the given ''$key''.+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 ''$key''''ArrayIterator::key()'' would get ''$key'' and so onlike 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.
  
 ===== ArrayIterator::prev():void ===== ===== ArrayIterator::prev():void =====
  
-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'', but if there is no previous Entry, after calling it, an immediate call to the ''valid()'' method would return ''false''.+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 ''false''. 
 + 
 + 
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 33: Line 36:
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
  
-Accept ''ArrayIterator::seekKey($key):bool''? +Accept ArrayIterator::seekKey($key) for PHP 7.2?
-Requires a 50% + 1 majority.+
  
-*votes*+vote 1 *
  
-Accept ''ArrayIterator::prev():void''? +Accept ArrayIterator::prev() for PHP 7.2?
-Requires a 50% + 1 majority.+
  
-*votes*+vote 2 *
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
 None yet. None yet.
 +
 +===== References =====
 +[[http://externals.io/thread/510|Discussion thread]]
rfc/arrayiterator-improvements.1479748610.txt.gz · Last modified: 2017/09/22 13:28 (external edit)