Lazy\Sequence

Lazy\Sequence is a collection of utilities implemented in a lazy way using generators in PHP 5.5.

All the methods operate on iterators - functions are provided to convert to and from regular arrays.

Installation

Lazy\Sequence can be installed via composer:

#!json

{
    "require" : {
        "mkjpryor/lazy-sequence" : "0.1.1"
    }
}

Creational functions

Some of these functions create infinite sequences. Infinite sequences can be turned into finite sequences using some of the functions below (e.g. take, takeWhile).

The following functions create new sequences:

create($item, ...)

Create a new sequence from the given arguments.

<?php

use Lazy\Sequence as S;

$seq = S::create(1, 2, 3, 4, 5);

S::each($seq, 'print_r'); // prints 1, 2, 3, 4, 5

range($from, $to = null, $step = 1)

Create a new sequence consisting of the values from $from to $to (if given) incrementing by $step each time.

NOTE: If $to is not given, this produces an infinite sequence.

<?php

use Lazy\Sequence as S;

S::each(S::range(1, 10, 2), 'print_r'); // prints 1, 3, 5, 7, 9

S::each(S::range(100), 'print_r'); // prints 100, 101, 102, 103, 104, ...

repeat($x)

Create a new sequence consisting of $x repeated forever.

NOTE: This function creates an infinite sequence.

<?php

use Lazy\Sequence as S;

S::each(S::repeat(5), 'print_r'); // prints 5, 5, 5, 5, 5, ...

replicate($n, $x)

Create a new sequence consisting of $x repeated $n times.

<?php

use Lazy\Sequence as S;

S::each(S::replicate(5, 3), 'print_r'); // prints 3, 3, 3, 3, 3

iterate(callable $block, $initial)

Create a new sequence whose values are the result of successively applying $block, with initial value $initial.

NOTE: This function creates an infinite sequence.

<?php

use Lazy\Sequence as S;

S::each(S::iterate(function($x) { return $x + 1; }, 1), 'print_r'); // prints 1, 2, 3, 4, 5, ...

Manipulation functions

The following functions manipulate already existing sequences:

head(array|\Traversable $seq)

Returns the first element of a sequence, or null for an empty sequence.

<?php

use Lazy\Sequence as S;

print_r(S::head([1, 2, 3, 4, 5]));  // prints 1

tail(array|\Traversable $seq)

Returns a new sequence consisting of all but the first element of $seq.

<?php

use Lazy\Sequence as S;

S::each(S::tail([1, 2, 3, 4, 5]), 'print_r');  // prints 2, 3, 4, 5

last(array|\Traversable $seq)

Returns the last element of the sequence, or null for an empty sequence.

NOTE that if the sequence is infinite, this causes an infinite loop.

<?php

use Lazy\Sequence as S;

print_r(S::last([1, 2, 3, 4, 5]));  // prints 5

each(array|\Traversable, callable $block)

Applies the given callable object for each element in $seq.

NOTE that if the sequence is infinite, this causes an infinite loop.

<?php

use Lazy\Sequence as S;

S::each([1, 2, 3, 4, 5], 'print_r');  // Prints 1, 2, 3, 4, 5

isEmpty(array|\Traversable $seq)

Checks if a sequence is empty.

<?php

use Lazy\Sequence as S;

print_r(S::isEmpty([1, 2, 3, 4, 5]));  // Prints false

print_r(S::isEmpty([]));  // Prints true

cons(array|\Traversable $seq, $item)

Returns a new sequence consisting of $item prepended to $seq.

<?php

use Lazy\Sequence as S;

S::each(S::cons([1, 2, 3, 4, 5], 0), 'print_r');  // Prints 0, 1, 2, 3, 4, 5

append(array|\Traversable $seq, array|\Traversable $other)

Returns a new sequence consisting of all the elements of $seq followed by all the elements of $other.

<?php

use Lazy\Sequence as S;

S::each(S::append([1, 2, 3, 4, 5], [6, 7, 8]), 'print_r');  // Prints 1, 2, 3, 4, 5, 6, 7, 8

map(array|\Traversable $seq, callable $mapper)

Returns a new sequence consisting of $mapper applied to each element of $seq.

<?php

use Lazy\Sequence as S;

S::each(S::map([1, 2, 3, 4, 5], function($x) { return $x * 2; }), 'print_r');  // Prints 2, 4, 6, 8, 10

filter(array|\Traversable $seq, callable $predicate)

Returns a new sequence consisting of the elements of $seq for which $predicate returns true.

<?php

use Lazy\Sequence as S;

S::each(S::filter([1, 2, 3, 4, 5], function($x) { return $x % 2 == 0; }), 'print_r');  // Prints 2, 4

take(array|\Traversable $seq, integer $n)

Returns a new sequence consisting of the first $n items of $seq.

<?php

use Lazy\Sequence as S;

S::each(S::take([1, 2, 3, 4, 5], 3), 'print_r');  // Prints 1, 2, 3

takeWhile(array|\Traversable $seq, callable $predicate)

Returns a new sequence consisting of the elements of $seq until the first time that $predicate returns false.

<?php

use Lazy\Sequence as S;

S::each(S::takeWhile([1, 2, 3, 4, 5], function($x) { return $x <= 3; }), 'print_r');  // Prints 1, 2, 3

skip(array|\Traversable $seq, $n)

Returns a new sequence consisting of all but the first $n elements of $seq.

<?php

use Lazy\Sequence as S;

S::each(S::skip([1, 2, 3, 4, 5], 2), 'print_r');  // Prints 3, 4, 5

skipWhile(array|\Traversable $seq, callable $predicate)

Returns a new sequence consisting of all the elements of $seq after the first time that $predicate returns false.

<?php

use Lazy\Sequence as S;

S::each(S::skipWhile([1, 2, 3, 4, 5], function($x) { return $x < 3; }), 'print_r');  // Prints 3, 4, 5

reduce(array|\Traversable $seq, callable $reducer, $initial)

Combines successive elements of $seq using $reducer, with initial value given by $initial.

NOTE that if the sequence is infinite, this causes an infinite loop.

<?php

use Lazy\Sequence as S;

print_r(S::reduce([1, 2, 3, 4, 5], function($a, $x) { return $a + $x; }, 0));  // Prints 15

reverse(array|\Traversable $seq)

Returns a new sequence that is the reverse of the given sequence.

NOTE that if the sequence is infinite, this causes an infinite loop.

<?php

use Lazy\Sequence as S;

S::each(S::reverse([1, 2, 3, 4, 5]), 'print_r');  // Prints 5, 4, 3, 2, 1

zip(array|\Traversable $seq, array|\Traversable $other, callable $op)

Returns a new sequence whose values are the associated values from $seq and $other combined using $op.

<?php

use Lazy\Sequence as S;

S::each(S::zip([1, 2, 3, 4], [6, 7, 8], function($x, $y) { return $x + $y; }), 'print_r');  // Prints 7, 9, 11

toArray(array|\Traversable $seq)

Converts a sequence to a regular array.

NOTE that if the sequence is infinite, this causes an infinite loop.

<?php

use Lazy\Sequence as S;

$seq = S::create(1, 2, 3, 4, 5);

print_r(S::toArray($seq)); // prints [1, 2, 3, 4, 5]

count(array|\Traversable $seq)

Returns the number of elements in $seq.

NOTE that if the sequence is infinite, this causes an infinite loop.

<?php

use Lazy\Sequence as S;

print_r(S::count([1, 2, 3, 4, 5])); // prints 5