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:

{ "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.