Documentation

Iterator
in package
implements Iterator

AbstractYes

An extension of the Standard PHP Library's Iterator class, with additional methods to make working with Iterators more expressive.

Table of Contents

Interfaces

Iterator

Methods

advance_by()  : bool
Advances the iterator by a number of elements.
cmp_by()  : int
Performs a lexicographical comparison between this object and another, using a user-specified function for element comparison.
count()  : int
Consumes the iterator, counting the number of elements it contains.
filter()  : FilterIterator
Creates a new iterator that only yields values that pass supplied predicate function.
find()  : mixed
Traverses the iterator, returning the first element for which a user-supplied function evaluates to true when passed the element.
ge()  : bool
Determines if the elements of this object are lexicographically greater than or equal to the elements of another object.
gt()  : bool
Determines if the elements of this object are lexicographically greater than the elements of another object.
le()  : bool
Determines if the elements of this object are lexicographically less-than or equal to the elements of another object.
lt()  : bool
Determines if the elements of this object are lexicographically less-than the elements of another object.
map()  : MapIterator
Creates an iterator that yields values from the underlying iterator after having been passed through a user-supplied function.
nth()  : mixed
Returns the nth element of the iterator, using 0-based indexing.
partial_cmp_by()  : int|null
Perform a "partial" lexicgraphical comparison using a user-supplied comparison function.
reduce()  : mixed
Repeatedly applies a user-supplied reduction function to all of the elements of the iterator.
take()  : TakeIterator
Creates an iterator that yields the first `$num`, or fewer if the underlying iterator ends sooner.
to_array()  : array<string|int, mixed>
Place all of the element in the iterator into an array
transform()  : MapIterator
Alias for the map function.

Methods

advance_by()

Advances the iterator by a number of elements.

public advance_by(int $count) : bool

Examples:

$a = [1, 2, 3, 4];
$iter = iter($a);

assert($iter->advance_by(2) == true);
assert($iter->current() == 3);
$iter->next();
assert($iter->advance_by(0) == true);
assert($iter->current() == 4);
assert($iter->advance_by(100) == false);
Parameters
$count : int

The number of elements to advance by

Return values
bool —

true if the iterator was successfully advanced (i.e., it had enough element), false otherwise.

cmp_by()

Performs a lexicographical comparison between this object and another, using a user-specified function for element comparison.

public cmp_by(Iterator $other, callable $f) : int

Examples:

$xs = [1, 2, 3, 4];
$ys = [1, 4, 9, 16];
$cmp = function($x, $y) {
     if ($x > $y)
         return 1;
     if ($x < $y)
         return -1;
     return 0;
}

assert(iter($xs)->cmp_by(
   iter($ys),
   fn(&x, &y) => $cmp($x, $y)) < 0);
assert(iter($xs)->cmp_by(
   iter($ys),
   fn(&x, &y) => $cmp($x * $x, $y)) == 0);
assert(iter($xs)->cmp_by(
   iter($ys),
   fn(&x, &y) => $cmp(2 * $x, $y)) > 0);
Parameters
$other : Iterator

The iterator to compare to (i.e., the right-hand side of the comparison).

$f : callable

A user-supplied function accepting two input parameters. It should return a value less than 0 (typically -1) when the first parameter is less-than the second, a value greater than 0 (typically 1) when the first parameter is greater-than the second, and 0 when they are equal.

Tags
see
Iterator::lt()

For a defintion of lexicographical comparison

Return values
int —

0 if $this is considered lexicographically equal to $other, -1 if $this is lexicographically less than $other, and 1 if $this is lexicographically greater than $other.

count()

Consumes the iterator, counting the number of elements it contains.

public count() : int
Return values
int —

The number elements in the Iterator.

filter()

Creates a new iterator that only yields values that pass supplied predicate function.

public filter(callable $filter) : FilterIterator
Parameters
$filter : callable

The predicate to apply to elements of the Iterator

Return values
FilterIterator —

The filtered Iterator

find()

Traverses the iterator, returning the first element for which a user-supplied function evaluates to true when passed the element.

public find(callable $f) : mixed

Examples:

$a = [1, 2, 3];

assert(iter($a)->find(fn($x) => $x == 2) == 2);
assert(iter($a)->find(fn($x) => $x == 5) == null);

Stopping at the first true:

$a = [1, 2, 3];
$iter = iter($a);

assert($iter->find(fn($x) => $x == 2) == 2);

// we can still use `$iter`, as there are more elements.
assert($iter->current() == 3);
Parameters
$f : callable

The predicate function to pass elements to. It should accept one parameter and return true if the parameter meets the desired condition.

Return values
mixed —

The desired element, or null if no element meets the condition.

ge()

Determines if the elements of this object are lexicographically greater than or equal to the elements of another object.

public ge(Iterator $other) : bool

Examples:

assert(iter([1])->ge(iter([1])));
assert(!(iter([1])->ge(iter([1, 2]))));
assert(iter([1, 2])->ge(iter([1])));
assert(iter([1, 2])->ge(iter([1, 2])));
Parameters
$other : Iterator

The iterator to compare to (i.e., the right-hand side of the comparison).

Tags
see
Iterator::lt()

For a defintion of lexicographical comparison

Return values
bool —

True if $this is considered lexicographically greater than or equal to other.

gt()

Determines if the elements of this object are lexicographically greater than the elements of another object.

public gt(Iterator $other) : bool

Examples:

assert(!(iter([1])->gt(iter([1]))));
assert(!(iter([1])->gt(iter([1, 2]))));
assert(iter([1, 2])->gt(iter([1])));
assert(!(iter([1, 2])->gt(iter([1, 2]))));
Parameters
$other : Iterator

The iterator to compare to (i.e., the right-hand side of the comparison).

Tags
see
Iterator::lt()

For a defintion of lexicographical comparison

Return values
bool —

True if $this is considered lexicographically greater than other.

le()

Determines if the elements of this object are lexicographically less-than or equal to the elements of another object.

public le(Iterator $other) : bool

Examples:

assert(iter([1])->le(iter([1])));
assert(iter([1])->le(iter([1, 2])));
assert(!(iter([1, 2])->le(iter([1]))));
assert(iter([1, 2])->le(iter([1, 2])));
Parameters
$other : Iterator

The iterator to compare to (i.e., the right-hand side of the comparison).

Tags
see
Iterator::lt()

For a defintion of lexicographical comparison

Return values
bool —

True if $this is considered lexicographically less-than or equal to other.

lt()

Determines if the elements of this object are lexicographically less-than the elements of another object.

public lt(Iterator $other) : bool

"Lexicographical" ordering differs from an element-by-element comparison. Instead, this is more similar to a "dictionary" ordering, where only the first n elements, where n is smaller of the length of both sequences. More specifically:

  • If two sequences $a and $b have the same number of elements, then $a < $b if and only if $a[$i] < $b[$i] for some $i. If all elements are equal, then $a == $b.
  • Otherwise, the shorter sequence is padded with a special element that always compares less than every other element, and the result is then compared using the rules above. In other words, if after comparing the first n common elements, if $a has no more elements, then $a < $b. Otherwise (i.e., $b is shorter), so $b < $a.

Examples:

assert(!(iter([1])->lt(iter([1]))));
assert(iter([1])->lt(iter([1, 2])));
assert(!(iter([1, 2])->lt(iter([1]))));
assert(!(iter([1, 2])->lt(iter([1, 2]))));
Parameters
$other : Iterator

The iterator to compare to (i.e., the right-hand side of the comparison).

Return values
bool —

True if $this is considered lexicographically less-than other.

map()

Creates an iterator that yields values from the underlying iterator after having been passed through a user-supplied function.

public map(Closure $f) : MapIterator

Examples:

$a = [1, 2, 3];

$iter = iter($a)->map(fn($x) => 2 * $x);

assert(iter->current() == 2);
iter->next();
assert(iter->current() == 4);
iter->next();
assert(iter->current() == 6);
iter->next();
assert(iter->current() == null);
Parameters
$f : Closure

The user supplied function taking one parameter and returning its transformed value.

Return values
MapIterator —

A new iterator that yields transformed values.

nth()

Returns the nth element of the iterator, using 0-based indexing.

public nth(int $n) : mixed

Examples:

$a = [1, 2, 3];
assert(iter($a)->nth(1) == 2);

Calling nth() multiple times doesn’t rewind the iterator:

$a = [1, 2, 3];
$iter = iter($a);

assert($iter->nth(1) == 2);
assert($iter->nth(1) == null);
Parameters
$n : int

The (0-based) index of the desired element

Return values
mixed —

The value at the $nth position, or null if the iterator contains fewer than $n remaining values.

partial_cmp_by()

Perform a "partial" lexicgraphical comparison using a user-supplied comparison function.

public partial_cmp_by(Iterator $other, callable $f) : int|null

The difference between this and cmp_by is that it may return null in the even that the comparison function $f returns null. This may happen when two elements are not comparable (i.e., NaN).

Examples:

$xs = [1.0, 2.0, 3.0, 4.0];
$ys = [1.0, 4.0, 9.0, 16.0];
$cmp = function($x, $y) {
     if ($x > $y)
         return 1;
     if ($x < $y)
         return -1;
     return 0;
}

assert(iter($xs)->cmp_by(
     iter($ys),
     fn(&x, &y) => $cmp($x, $y)) < 0);
assert(iter($xs)->cmp_by(
     iter($ys),
     fn(&x, &y) => $cmp($x * $x, $y)) == 0);
assert(iter($xs)->cmp_by(
     iter($ys),
     fn(&x, &y) => $cmp(2 * $x, $y)) > 0);

$xs[2] = NAN;

assert(iter($xs)->cmp_by(
     iter($ys),
     fn(&x, &y) => $cmp($x, $y)) == null);
assert(iter($xs)->cmp_by(
     iter($ys),
     fn(&x, &y) => $cmp($x * $x, $y)) == null);
assert(iter($xs)->cmp_by(
     iter($ys),
     fn(&x, &y) => $cmp(2 * $x, $y)) == null);
Parameters
$other : Iterator

The iterator to compare to (i.e., the right-hand side of the comparison).

$f : callable

A user-supplied function accepting two input parameters. It should return a value less than 0 (typically -1) when the first parameter is less-than the second, a value greater than 0 (typically 1) when the first parameter is greater-than the second, and 0 when they are equal.

Tags
see
Iterator::lt()

For a defintion of lexicographical comparison

Return values
int|null —

null if the comparison function ever return null, 0 if $this is considered lexicographically equal to $other, -1 if $this is lexicographically less than $other, and 1 if $this is lexicographically greater than $other.

reduce()

Repeatedly applies a user-supplied reduction function to all of the elements of the iterator.

public reduce(mixed $init, callable $accumulator) : mixed

If $accumlator returns null at any point, this function immediately returns null and the iterator is not advanced further.

If the iterator is empty, the value of $init is returned.

Examples:

$reduced = iter(range(1, 9))->reduce(
     fn($acc, $e) => $acc + $e);
assert($reduced == 45);
Parameters
$init : mixed

The initial "accumulated" value to pass to the accumulator function

$accumulator : callable

The accumulator function. It should take two parameters, the current accumlated value and the new value, and return the result of combining them.

Return values
mixed —

The final calculated value of $accumlator, null if $accumulator returns null, or $init if the iterator is empty.

take()

Creates an iterator that yields the first `$num`, or fewer if the underlying iterator ends sooner.

public take(int $num) : TakeIterator

Examples:

$a = [1, 2, 3];
$iter = iter($a).take(2);

assert($iter->current() == 1);
$iter->next();
assert($iter->current() == 2);
$iter->next();
assert($iter->valid() == false);

If less than $num elements are available, take() will limit itself to the size of the underlying iterator:

$v = [1, 2];
$iter = iter($v)->take(5);

assert($iter->current() == 1);
$iter->next();
assert($iter->current() == 2);
$iter->next();
assert($iter->valid() == false);
Parameters
$num : int

The maximum number of elements that the resulting iterator will contain.

Return values
TakeIterator —

A new iterator that contains at most $n elements.

to_array()

Place all of the element in the iterator into an array

public to_array() : array<string|int, mixed>
Return values
array<string|int, mixed> —

An array containing the values that are in the iterator

transform()

Alias for the map function.

public transform(Closure $f) : MapIterator
Parameters
$f : Closure

The user supplied function taking one parameter and returning its transformed value.

Tags
see
Iterator::map()
Return values
MapIterator —

A new iterator that yields transformed values.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results