An iterator that allows peeking at the next value(s) and stepping back to the previous value(s) without advancing the iteration.
Description
This iterator extends IteratorIterator and provides methods peek() and prev()
to inspect the next and previous values without modifying the current iteration state.
Usage Example:
Description
Using LookaheadIterator
use FastForward\Iterator\LookaheadIterator;
use ArrayIterator;
$data = new ArrayIterator(['A', 'B', 'C', 'D']);
$lookaheadIterator = new LookaheadIterator($data);
foreach ($lookaheadIterator as $value) {
echo "Current: " . var_export($value, true) . " | Next: " . var_export($lookaheadIterator->peek(), true) . " | Prev: " . var_export($lookaheadIterator->prev(), true) . "\n";
}
// Outputs:
// Current: 'A' | Next: 'B' | Prev: null
// Current: 'B' | Next: 'C' | Prev: 'A'
// Current: 'C' | Next: 'D' | Prev: 'B'
// Current: 'D' | Next: null | Prev: 'C'
Properties
Methods
Initializes the LookaheadIterator.
Counts the number of elements exposed by the inner iterator.
Retrieves the next value(s) without advancing the iterator.
Retrieves the previous value(s) without moving the iterator backward.
Advances the iterator and updates the internal position counter.
Resets the iterator to the first available element.
private
LimitIterator
$peekableInnerIterator
Description
A separate instance of the iterator used for peeking.
This iterator ensures that calling lookAhead() and lookBehind() does not affect the main iterator's position.
private
int
$position
=
0
Description
the current iterator position
Initializes the LookaheadIterator.
public
__construct(
iterable<string|int, mixed>
$iterator) : mixed
Parameters
$iterator
:
iterable<string|int, mixed>
Description
the iterator to wrap
Counts the number of elements exposed by the inner iterator.
public
count() : int
Description
If the inner iterator implements Countable, this method SHALL return the value provided by that implementation. Otherwise, it MUST count elements by iterating over the iterator. If the inner iterator is not cloneable, this method SHALL wrap the current object in an IteratorIterator instance and count through that wrapper to avoid performing an invalid clone operation. If the inner iterator is cloneable, this method SHOULD count over a clone so that the original iterator state is preserved as much as possible.
Return values
Description
the total number of elements available from the inner iterator
Retrieves the next value(s) without advancing the iterator.
public
lookAhead([
int
$count = 1]) : mixed
Description
If $count is specified, an array of the next $count values will be returned.
Parameters
$count
:
int
=
1
Description
the number of upcoming values to peek at (default: 1)
Description
if $count is less than 1
Return values
Description
the next value, an array of upcoming values, or null if no further elements exist
Retrieves the previous value(s) without moving the iterator backward.
public
lookBehind([
int
$count = 1]) : mixed
Description
If $count is specified, an array of the previous $count values will be returned.
Parameters
$count
:
int
=
1
Description
the number of previous values to retrieve (default: 1)
Description
if $count is less than 1
Return values
Description
the previous value, an array of previous values, or null if no previous elements exist
Advances the iterator and updates the internal position counter.
public
next() : void
Description
This method increments the internal position tracker and moves the iterator forward.
Resets the iterator to the first available element.
public
rewind() : void
Description
This method rewinds both the main iterator and the peeking iterator, ensuring that both are in sync when restarting the iteration.