README.md

IterTools - PHP Iteration Tools to Power Up Your Loops

Inspired by Python—designed for PHP.

Features

IterTools makes you an iteration superstar by providing two types of tools:

• Loop iteration tools
• Stream iteration tools

Loop Iteration Tools Example

foreach (Multi::zip(['a', 'b'], [1, 2]) as [$letter, $number]) {
    print($letter . $number);  // a1, b2
}

Stream Iteration Tools Example

$result = Stream::of([1, 1, 2, 2, 3, 4, 5])
    ->distinct()                 // [1, 2, 3, 4, 5]
    ->map(fn ($x) => $x**2)      // [1, 4, 9, 16, 25]
    ->filter(fn ($x) => $x < 10) // [1, 4, 9]
    ->toSum();                   // 14

All functions work on iterable collections:

• array (type)
• Generator (type)
• Iterator (interface)
• Traversable (interface)

README docs translated in other languages:

• Русский

Setup

Add the library to your composer.json file in your project:

{
  "require": {
      "markrogoyski/itertools-php": "2.*"
  }
}

Use composer to install the library:

$ composer install

Composer will install IterTools inside your vendor folder. Then you can add the following to your .php files to use the library with Autoloading.

require_once __DIR__ . '/vendor/autoload.php';

Alternatively, use composer on the command line to require and install IterTools:

$ composer require markrogoyski/itertools-php:2.*

Minimum Requirements

• PHP 8.2+
  • (For PHP 7.4–8.1, use v1.9)

Quick Reference

Loop Iteration Tools

Multi Iteration

Iterator	Description	Code Snippet
chain	Chain multiple iterables together	Multi::chain($list1, $list2)
roundRobin	Yield one value at a time from multiple iterables, rotating across sources	Multi::roundRobin($list1, $list2)
zip	Iterate multiple collections simultaneously until the shortest iterator completes	Multi::zip($list1, $list2)
zipEqual	Iterate multiple collections of equal length simultaneously, error if lengths not equal	Multi::zipEqual($list1, $list2)
zipFilled	Iterate multiple collections, using a filler value if lengths not equal	Multi::zipFilled($default, $list1, $list2)
zipLongest	Iterate multiple collections simultaneously until the longest iterator completes	Multi::zipLongest($list1, $list2)
unzip	Transpose a sequence of rows into columns (inverse of zip)	Multi::unzip($rows)

Single Iteration

Iterator	Description	Code Snippet
accumulate	Running result of a binary operator	Single::accumulate($data, $op, [$initial])
chunkwise	Iterate by chunks	Single::chunkwise($data, $chunkSize)
chunkwiseOverlap	Iterate by overlapped chunks	Single::chunkwiseOverlap($data, $chunkSize, $overlapSize)
compress	Filter out elements not selected	Single::compress($data, $selectors)
compressAssociative	Filter out elements by keys not selected	Single::compressAssociative($data, $selectorKeys)
dropWhile	Drop elements while predicate is true	Single::dropWhile($data, $predicate)
enumerate	Iterate [index, value] pairs	Single::enumerate($data, [$start])
filter	Filter for elements where predicate is true	Single::filterTrue($data, $predicate)
filterTrue	Filter for truthy elements	Single::filterTrue($data)
filterFalse	Filter for falsy elements	Single::filterFalse($data)
filterKeys	Filter for keys where predicate is true	Single::filterKeys($data, $predicate)
flatMap	Map function onto items and flatten result	Single::flaMap($data, $mapper)
flatten	Flatten multidimensional iterable	Single::flatten($data, [$dimensions])
groupAdjacentBy	Group adjacent elements sharing an extracted key	Single::groupAdjacentBy($data, $keyFn)
groupBy	Group data by a common element	Single::groupBy($data, $groupKeyFunction, [$itemKeyFunc])
intersperse	Insert a separator between elements	Single::intersperse($data, $separator)
limit	Iterate up to a limit	Single::limit($data, $limit)
map	Map function onto each item	Single::map($data, $function)
mapSpread	Map function onto each item, splatting items as positional args	Single::mapSpread($data, $function)
padLeft	Pad iterable on the left to a minimum length	Single::padLeft($data, $length, $fill)
padRight	Pad iterable on the right to a minimum length	Single::padRight($data, $length, $fill)
pairwise	Iterate successive overlapping pairs	Single::pairwise($data)
reindex	Reindex keys of key-value iterable	Single::reindex($data, $reindexer)
repeat	Repeat an item a number of times	Single::repeat($item, $repetitions)
reverse	Iterate elements in reverse order	Single::reverse($data)
skip	Iterate after skipping elements	Single::skip($data, $count, [$offset])
slice	Extract a slice of the iterable	Single::slice($data, [$start], [$count], [$step])
splitWhen	Split iterable into groups when predicate matches	Single::splitWhen($data, $predicate)
string	Iterate the characters of a string	Single::string($string)
takeWhile	Iterate elements while predicate is true	Single::takeWhile($data, $predicate)

Infinite Iteration

Iterator	Description	Code Snippet
count	Count sequentially forever	Infinite::count($start, $step)
cycle	Cycle through a collection	Infinite::cycle($collection)
generate	Yield values from a supplier forever	Infinite::generate($supplier)
iterate	Iterate by repeatedly applying a function	Infinite::iterate($initial, $function)
repeat	Repeat an item forever	Infinite::repeat($item)

Random Iteration

Iterator	Description	Code Snippet
choice	Random selections from list	Random::choice($list, $repetitions)
coinFlip	Random coin flips (0 or 1)	Random::coinFlip($repetitions)
number	Random numbers	Random::number($min, $max, $repetitions)
percentage	Random percentage between 0 and 1	Random::percentage($repetitions)
rockPaperScissors	Random rock-paper-scissors hands	Random::rockPaperScissors($repetitions)
sample	Random sample without replacement	Random::sample($data, $size, [$engine])

Math Iteration

Iterator	Description	Code Snippet
frequencies	Frequency distribution of data	Math::frequencies($data, [$strict])
relativeFrequencies	Relative frequency distribution of data	Math::relativeFrequencies($data, [$strict])
runningAverage	Running average accumulation	Math::runningAverage($numbers, $initialValue)
runningDifference	Running difference accumulation	Math::runningDifference($numbers, $initialValue)
runningMax	Running maximum accumulation	Math::runningMax($numbers, $initialValue)
runningMin	Running minimum accumulation	Math::runningMin($numbers, $initialValue)
runningProduct	Running product accumulation	Math::runningProduct($numbers, $initialValue)
runningTotal	Running total accumulation	Math::runningTotal($numbers, $initialValue)

Set and multiset Iteration

Iterator	Description	Code Snippet
distinct	Iterate only distinct items	Set::distinct($data)
distinctAdjacent	Remove only consecutive duplicates	Set::distinctAdjacent($data)
distinctAdjacentBy	Remove only consecutive duplicates using custom key	Set::distinctAdjacentBy($data, $keyFn)
distinctBy	Iterate only distinct items using custom comparator	Set::distinct($data, $compareBy)
duplicates	Iterate values that appear more than once	Set::duplicates($data, [$strict])
duplicatesBy	Iterate duplicates using a custom key function	Set::duplicatesBy($data, $keyFn)
intersection	Intersection of iterables	Set::intersection(...$iterables)
intersectionCoercive	Intersection with type coercion	Set::intersectionCoercive(...$iterables)
partialIntersection	Partial intersection of iterables	Set::partialIntersection($minCount, ...$iterables)
partialIntersectionCoercive	Partial intersection with type coercion	Set::partialIntersectionCoercive($minCount, ...$iterables)
difference	Difference of iterables	Set::difference($a, ...$iterables)
differenceCoercive	Difference with type coercion	Set::differenceCoercive($a, ...$iterables)
symmetricDifference	Symmetric difference of iterables	Set::symmetricDifference(...$iterables)
symmetricDifferenceCoercive	Symmetric difference with type coercion	Set::symmetricDifferenceCoercive(...$iterables)
union	Union of iterables	Set::union(...$iterables)
unionCoercive	Union with type coercion	Set::unionCoercive(...$iterables)

Combinatorics

Iterator	Description	Code Snippet
product	Cartesian product of iterables	Combinatorics::product(...$iterables)
permutations	Permutations of an iterable	Combinatorics::permutations($data, [$r])
combinations	Combinations of an iterable	Combinatorics::combinations($data, $r)
combinationsWithReplacement	Combinations with replacement	Combinatorics::combinationsWithReplacement($data, $r)
powerset	Every subset of an iterable	Combinatorics::powerset($data)

Sort Iteration

Iterator	Description	Code Snippet
asort	Iterate a sorted collection maintaining keys	Sort::asort($data, [$comparator])
asortBy	Iterate sorted by extracted key, keys kept	Sort::asortBy($data, $keyFn)
largest	Iterate the n largest elements (descending)	Sort::largest($data, $n, [$keyFn])
shuffle	Iterate the iterable in random order	Sort::shuffle($data, [$engine])
smallest	Iterate the n smallest elements (ascending)	Sort::smallest($data, $n, [$keyFn])
sort	Iterate a sorted collection	Sort::sort($data, [$comparator])
sortBy	Iterate sorted by extracted key	Sort::sortBy($data, $keyFn)

File Iteration

Iterator	Description	Code Snippet
readCsv	Intersection a CSV file line by line	File::readCsv($fileHandle)
readLines	Iterate a file line by line	File::readLines($fileHandle)

Transform Iteration

Iterator	Description	Code Snippet
partition	Partition iterable into truthy and falsy lists	Transform::partition($data, $predicate)
tee	Iterate duplicate iterators	Transform::tee($data, $count)
toArray	Transform iterable to an array	Transform::toArray($data)
toAssociativeArray	Transform iterable to an associative array	Transform::toAssociativeArray($data, [$keyFunc], [$valueFunc])
toIterator	Transform iterable to an iterator	Transform::toIterator($data)

Summary

Summary	Description	Code Snippet
allMatch	True if all items are true according to predicate	Summary::allMatch($data, $predicate)
allUnique	True if all items are unique	Summary::allUnique($data, [$strict])
anyMatch	True if any item is true according to predicate	Summary::anyMatch($data, $predicate)
arePermutations	True if iterables are permutations of each other	Summary::arePermutations(...$iterables)
arePermutationsCoercive	True if iterables are permutations of each other with type coercion	Summary::arePermutationsCoercive(...$iterables)
atLeastN	True if at least n items are true according to predicate	Summary::atLeastN($data, $n, [$predicate])
atMostN	True if at most n items are true according to predicate	Summary::atMostN($data, $n, [$predicate])
contains	True if iterable contains the needle	Summary::contains($data, $needle)
containsCoercive	True if iterable contains the needle with type coercion	Summary::containsCoercive($data, $needle)
endsWith	True if iterable ends with the given suffix	Summary::endsWith($data, $suffix)
endsWithCoercive	True if iterable ends with the given suffix with type coercion	Summary::endsWithCoercive($data, $suffix)
exactlyN	True if exactly n items are true according to predicate	Summary::exactlyN($data, $n, $predicate)
isEmpty	True if iterable has no items	Summary::isEmpty($data)
isPartitioned	True if partitioned with items true according to predicate before others	Summary::isPartitioned($data, $predicate)
isSorted	True if iterable sorted	Summary::isSorted($data)
isReversed	True if iterable reverse sorted	Summary::isReversed($data)
noneMatch	True if none of items true according to predicate	Summary::noneMatch($data, $predicate)
same	True if iterables are the same	Summary::same(...$iterables)
sameCount	True if iterables have the same lengths	Summary::sameCount(...$iterables)
startsWith	True if iterable starts with the given prefix	Summary::startsWith($data, $prefix)
startsWithCoercive	True if iterable starts with the given prefix with type coercion	Summary::startsWithCoercive($data, $prefix)

Reduce

Reducer	Description	Code Snippet
toAverage	Mean average of elements	Reduce::toAverage($numbers)
toCount	Reduce to length of iterable	Reduce::toCount($data)
toFirst	Reduce to its first value	Reduce::toFirst($data)
toFirstAndLast	Reduce to its first and last values	Reduce::toFirstAndLast($data)
toFirstMatch	Reduce to first value matching predicate	Reduce::toFirstMatch($data, $predicate, [$default])
toFirstMatchIndex	Reduce to position of first matching element	Reduce::toFirstMatchIndex($data, $predicate, [$default])
toFirstMatchKey	Reduce to key of first matching element	Reduce::toFirstMatchKey($data, $predicate, [$default])
toLast	Reduce to its last value	Reduce::toLast()
toLastMatch	Reduce to last value matching predicate	Reduce::toLastMatch($data, $predicate, [$default])
toLastMatchIndex	Reduce to position of last matching element	Reduce::toLastMatchIndex($data, $predicate, [$default])
toLastMatchKey	Reduce to key of last matching element	Reduce::toLastMatchKey($data, $predicate, [$default])
toOnly	Reduce to its sole element	Reduce::toOnly($data)
consume	Drain iterable, discarding values	Reduce::consume($data)
toMax	Reduce to its largest element	Reduce::toMax($numbers, [$compareBy])
toMin	Reduce to its smallest element	Reduce::toMin($numbers, [$compareBy])
toMinMax	Reduce to array of upper and lower bounds	Reduce::toMinMax($numbers, [$compareBy])
toNth	Reduce to value at nth position	Reduce::toNth($data, $position)
toProduct	Reduce to the product of its elements	Reduce::toProduct($numbers)
toRandomValue	Reduce to random value from iterable	Reduce::toRandomValue($data)
toRange	Reduce to difference of max and min values	Reduce::toRange($numbers)
toString	Reduce to joined string	Reduce::toString($data, [$separator], [$prefix], [$suffix])
toSum	Reduce to the sum of its elements	Reduce::toSum($numbers)
toValue	Reduce to value using callable reducer	Reduce::toValue($data, $reducer, $initialValue)

Stream Iteration Tools

Stream Sources

Source	Description	Code Snippet
of	Create a stream from an iterable	Stream::of($iterable)
ofCoinFlips	Create a stream of random coin flips	Stream::ofCoinFlips($repetitions)
ofCsvFile	Create a stream from a CSV file	Stream::ofCsvFile($fileHandle)
ofEmpty	Create an empty stream	Stream::ofEmpty()
ofFileLines	Create a stream from lines of a file	Stream::ofFileLines($fileHandle)
ofRandomChoice	Create a stream of random selections	Stream::ofRandomChoice($items, $repetitions)
ofRandomNumbers	Create a stream of random numbers (integers)	Stream::ofRandomNumbers($min, $max, $repetitions)
ofRandomPercentage	Create a stream of random percentages between 0 and 1	Stream::ofRandomPercentage($repetitions)
ofRange	Create a stream of a range of numbers	Stream::ofRange($start, $end, $step)
ofRockPaperScissors	Create a stream of rock-paper-scissors hands	Stream::ofRockPaperScissors($repetitions)

Stream Operations

Operation	Description	Code Snippet
accumulate	Running result of a binary operator	$stream->accumulate($op, [$initial])
append	Append values to the end of the stream	$stream->append(...$values)
asort	Sorts the iterable source maintaining keys	$stream->asort([$comparator])
asortBy	Sorts the stream by extracted key, maintaining keys	$stream->asortBy($keyFn)
chainWith	Chain iterable source withs given iterables together into a single iteration	$stream->chainWith(...$iterables)
compress	Compress source by filtering out data not selected	$stream->compress($selectors)
compressAssociative	Compress source by filtering out keys not selected	$stream->compressAssociative($selectorKeys)
chunkwise	Iterate by chunks	$stream->chunkwise($chunkSize)
chunkwiseOverlap	Iterate by overlapped chunks	$stream->chunkwiseOverlap($chunkSize, $overlap)
distinct	Filter out elements: iterate only unique items	$stream->distinct([$strict])
distinctAdjacent	Remove only consecutive duplicates	$stream->distinctAdjacent()
distinctAdjacentBy	Remove only consecutive duplicates using custom key	$stream->distinctAdjacentBy($keyFn)
distinctBy	Filter out elements: iterate only unique items using custom comparator	$stream->distinct($compareBy)
dropWhile	Drop elements from the iterable source while the predicate function is true	$stream->dropWhile($predicate)
duplicates	Iterate values that appear more than once	$stream->duplicates([$strict])
duplicatesBy	Iterate duplicates using a custom key function	$stream->duplicatesBy($keyFn)
enumerate	Iterate [index, value] pairs	$stream->enumerate([$start])
filter	Filter for only elements where the predicate function is true	$stream->filterTrue($predicate)
filterTrue	Filter for only truthy elements	$stream->filterTrue()
filterFalse	Filter for only falsy elements	$stream->filterFalse()
filterKeys	Filter for keys where predicate function is true	$stream->filterKeys($predicate)
flatMap	Map function onto elements and flatten result	$stream->flatMap($function)
flatten	Flatten multidimensional stream	$stream->flatten($dimensions)
frequencies	Frequency distribution	$stream->frequencies([$strict])
groupAdjacentBy	Group adjacent elements sharing an extracted key	$stream->groupAdjacentBy($keyFn)
groupBy	Group iterable source by a common data element	$stream->groupBy($groupKeyFunction, [$itemKeyFunc])
infiniteCycle	Cycle through the elements of iterable source sequentially forever	$stream->infiniteCycle()
intersectionWith	Intersect iterable source and given iterables	$stream->intersectionWith(...$iterables)
intersectionCoerciveWith	Intersect iterable source and given iterables with type coercion	$stream->intersectionCoerciveWith(...$iterables)
intersperse	Insert a separator between elements of the stream	$stream->intersperse($separator)
largest	Reduce the stream to the n largest elements (descending)	$stream->largest($n, [$keyFn])
limit	Limit the stream's iteration	$stream->limit($limit)
map	Map function onto elements	$stream->map($function)
mapSpread	Map function onto elements, splatting items as positional args	$stream->mapSpread($function)
padLeft	Pad the stream on the left to a minimum length	$stream->padLeft($length, $fill)
padRight	Pad the stream on the right to a minimum length	$stream->padRight($length, $fill)
pairwise	Return pairs of elements from iterable source	$stream->pairwise()
partialIntersectionWith	Partially intersect iterable source and given iterables	$stream->partialIntersectionWith( $minIntersectionCount, ...$iterables)
partialIntersectionCoerciveWith	Partially intersect iterable source and given iterables with type coercion	$stream->partialIntersectionCoerciveWith( $minIntersectionCount, ...$iterables)
productWith	Cartesian product of stream with given iterables	$stream->productWith(...$iterables)
permutations	Permutations of the stream's elements	$stream->permutations([$r])
combinations	Combinations of the stream's elements	$stream->combinations($r)
combinationsWithReplacement	Combinations with replacement of the stream's elements	$stream->combinationsWithReplacement($r)
powerset	Every subset of the stream's elements	$stream->powerset()
prepend	Prepend values to the front of the stream	$stream->prepend(...$values)
reindex	Reindex keys of key-value stream	$stream->reindex($reindexer)
relativeFrequencies	Relative frequency distribution	$stream->relativeFrequencies([$strict])
reverse	Reverse elements of the stream	$stream->reverse()
roundRobinWith	Yield values from the stream and given iterables in round-robin order	$stream->roundRobinWith(...$iterables)
runningAverage	Accumulate the running average (mean) over iterable source	$stream->runningAverage($initialValue)
runningDifference	Accumulate the running difference over iterable source	$stream->runningDifference($initialValue)
runningMax	Accumulate the running max over iterable source	$stream->runningMax($initialValue)
runningMin	Accumulate the running min over iterable source	$stream->runningMin($initialValue)
runningProduct	Accumulate the running product over iterable source	$stream->runningProduct($initialValue)
runningTotal	Accumulate the running total over iterable source	$stream->runningTotal($initialValue)
sample	Sample $size elements from the stream without replacement	$stream->sample($size, [$engine])
shuffle	Randomize the order of the stream	$stream->shuffle([$engine])
skip	Skip some elements of the stream	$stream->skip($count, [$offset])
slice	Extract a slice of the stream	$stream->slice([$start], [$count], [$step])
smallest	Reduce the stream to the n smallest elements (ascending)	$stream->smallest($n, [$keyFn])
sort	Sorts the stream	$stream->sort([$comparator])
sortBy	Sorts the stream by extracted key	$stream->sortBy($keyFn)
splitWhen	Split the stream into groups when predicate matches	$stream->splitWhen($predicate)
differenceWith	Difference of iterable source and given iterables	$stream->differenceWith(...$iterables)
differenceCoerciveWith	Difference of iterable source and given iterables with type coercion	$stream->differenceCoerciveWith(...$iterables)
symmetricDifferenceWith	Symmetric difference of iterable source and given iterables	$stream->symmetricDifferenceWith(...$iterables)
symmetricDifferenceCoerciveWith	Symmetric difference of iterable source and given iterables with type coercion	$stream->symmetricDifferenceCoerciveWith(...$iterables)
takeWhile	Return elements from the iterable source as long as the predicate is true	$stream->takeWhile($predicate)
unionWith	Union of stream with iterables	$stream->unionWith(...$iterables)
unionCoerciveWith	Union of stream with iterables with type coercion	$stream->unionCoerciveWith(...$iterables)
unzip	Transpose rows of the stream into columns (inverse of zip)	$stream->unzip()
zip	Zip rows of the stream column-wise (transpose), stopping at shortest	$stream->zip()
zipLongest	Zip rows of the stream column-wise, continuing until longest (missing → null)	$stream->zipLongest()
zipFilled	Zip rows of the stream column-wise, continuing until longest with filler	$stream->zipFilled($filler)
zipEqual	Zip rows of the stream column-wise, throwing if lengths differ	$stream->zipEqual()
zipWith	Iterate iterable source with another iterable collection simultaneously	$stream->zipWith(...$iterables)
zipEqualWith	Iterate iterable source with another iterable collection of equal lengths simultaneously	$stream->zipEqualWith(...$iterables)
zipFilledWith	Iterate iterable source with another iterable collection using default filler	$stream->zipFilledWith($default, ...$iterables)
zipLongestWith	Iterate iterable source with another iterable collection simultaneously	$stream->zipLongestWith(...$iterables)

Stream Terminal Operations

Summary Terminal Operations

Terminal Operation	Description	Code Snippet
allMatch	Returns true if all items in stream match predicate	$stream->allMatch($predicate)
allUnique	Returns true if all items in stream are unique	$stream->allUnique([$strict]])
anyMatch	Returns true if any item in stream matches predicate	$stream->anyMatch($predicate)
arePermutationsWith	Returns true if all iterables permutations of stream	$stream->arePermutationsWith(...$iterables)
arePermutationsCoerciveWith	Returns true if all iterables permutations of stream with type coercion	$stream->arePermutationsCoerciveWith(...$iterables)
atLeastN	Returns true if at least n items are true according to predicate	$stream->atLeastN($n, [$predicate])
atMostN	Returns true if at most n items are true according to predicate	$stream->atMostN($n, [$predicate])
contains	Returns true if stream contains the needle	$stream->contains($needle)
containsCoercive	Returns true if stream contains the needle with type coercion	$stream->containsCoercive($needle)
endsWith	Returns true if stream ends with the given suffix	$stream->endsWith($suffix)
endsWithCoercive	Returns true if stream ends with the given suffix with type coercion	$stream->endsWithCoercive($suffix)
exactlyN	Returns true if exactly n items are true according to predicate	$stream->exactlyN($n, $predicate)
isEmpty	Returns true if stream has no items	$stream::isEmpty()
isPartitioned	Returns true if partitioned with items true according to predicate before others	$stream::isPartitioned($predicate)
isSorted	Returns true if stream is sorted in ascending order	$stream->isSorted()
isReversed	Returns true if stream is sorted in reverse descending order	$stream->isReversed()
noneMatch	Returns true if none of the items in stream match predicate	$stream->noneMatch($predicate)
sameWith	Returns true if stream and all given collections are the same	$stream->sameWith(...$iterables)
sameCountWith	Returns true if stream and all given collections have the same lengths	$stream->sameCountWith(...$iterables)
startsWith	Returns true if stream starts with the given prefix	$stream->startsWith($prefix)
startsWithCoercive	Returns true if stream starts with the given prefix with type coercion	$stream->startsWithCoercive($prefix)

Reduction Terminal Operations

Terminal Operation	Description	Code Snippet
toAverage	Reduces stream to the mean average of its items	$stream->toAverage()
toCount	Reduces stream to its length	$stream->toCount()
toFirst	Reduces stream to its first value	$stream->toFirst()
toFirstAndLast	Reduces stream to its first and last values	$stream->toFirstAndLast()
toFirstMatch	Reduces stream to first value matching predicate	$stream->toFirstMatch($predicate, [$default])
toFirstMatchIndex	Reduces stream to position of first matching element	$stream->toFirstMatchIndex($predicate, [$default])
toFirstMatchKey	Reduces stream to key of first matching element	$stream->toFirstMatchKey($predicate, [$default])
toLast	Reduces stream to its last value	$stream->toLast()
toLastMatch	Reduces stream to last value matching predicate	$stream->toLastMatch($predicate, [$default])
toLastMatchIndex	Reduces stream to position of last matching element	$stream->toLastMatchIndex($predicate, [$default])
toLastMatchKey	Reduces stream to key of last matching element	$stream->toLastMatchKey($predicate, [$default])
toOnly	Reduces stream to its sole element	$stream->toOnly()
toMax	Reduces stream to its max value	$stream->toMax([$compareBy])
toMin	Reduces stream to its min value	$stream->toMin([$compareBy])
toMinMax	Reduces stream to array of upper and lower bounds	$stream->toMinMax([$compareBy])
toNth	Reduces stream to value at nth position	$stream->toNth($position)
toProduct	Reduces stream to the product of its items	$stream->toProduct()
toString	Reduces stream to joined string	$stream->toString([$separator], [$prefix], [$suffix])
toSum	Reduces stream to the sum of its items	$stream->toSum()
toRandomValue	Reduces stream to random value within it	$stream->toRandomValue()
toRange	Reduces stream to difference of max and min values	$stream->toRange()
toValue	Reduces stream like array_reduce() function	$stream->toValue($reducer, $initialValue)

Transformation Terminal Operations

Terminal Operation	Description	Code Snippet
toArray	Returns array of stream elements	$stream->toArray()
toAssociativeArray	Returns key-value map of stream elements	$stream->toAssociativeArray($keyFunc, $valueFunc)
toPartition	Partition stream into truthy and falsy lists	$stream->toPartition($predicate)
tee	Returns array of multiple identical Streams	$stream->tee($count)

Side Effect Terminal Operations

Terminal Operation	Description	Code Snippet
callForEach	Perform action via function on each item	$stream->callForEach($function)
consume	Drain stream, discarding values	$stream->consume()
print	print each item in the stream	$stream->print([$separator], [$prefix], [$suffix])
printLn	print each item on a new line	$stream->printLn()
toCsvFile	Write the contents of the stream to a CSV file	$stream->toCsvFile($fileHandle, [$headers])
toFile	Write the contents of the stream to a file	$stream->toFile($fileHandle)

Stream Debug Operations

Debug Operation	Description	Code Snippet
peek	Peek at each element between stream operations	$stream->peek($peekFunc)
peekStream	Peek at the entire stream between operations	$stream->peekStream($peekFunc)
peekPrint	Peek at each element by printing between operations	$stream->peekPrint()
peekPrintR	Peek at each element by doing print-r between operations	$stream->peekPrintR()
printR	print_r each item	$stream->printR()
varDump	var_dump each item	$stream->varDump()

Documentation

Full documentation with detailed descriptions, signatures, and code examples for each function.

Loop Iteration

• Multi Iteration — Chain, RoundRobin, Unzip, Zip, ZipEqual, ZipFilled, ZipLongest
• Single Iteration — Chunkwise, Compress, Filter, Map, Flatten, GroupBy, and more
• Infinite Iteration — Count, Cycle, Iterate, Repeat
• Random Iteration — Choice, CoinFlip, Number, Percentage, RockPaperScissors
• Math Iteration — Frequencies, Running Average/Difference/Max/Min/Product/Total
• Set and Multiset Iteration — Distinct, Intersection, Difference, Symmetric Difference, Union
• Combinatorics Iteration — Product, Permutations, Combinations, CombinationsWithReplacement, Powerset
• Sort Iteration — ASort, AsortBy, Largest, Smallest, Sort, SortBy
• File Iteration — ReadCsv, ReadLines
• Transform Iteration — Tee, ToArray, ToAssociativeArray, ToIterator

Summarize and Reduce

• Summary — AllMatch, AnyMatch, IsEmpty, IsSorted, and more
• Reduce — ToAverage, ToSum, ToMin, ToMax, ToString, and more

Stream

• Stream — Sources, operations, terminal operations, and debug tools

Usage

All functions work on iterable collections:

• array (type)
• Generator (type)
• Iterator (interface)
• Traversable (interface)

Composition

IterTools can be combined to create new iterable compositions.

Zip Strings

use IterTools\Multi;
use IterTools\Single;

$letters = 'ABCDEFGHI';
$numbers = '123456789';

foreach (Multi::zip(Single::string($letters), Single::string($numbers)) as [$letter, $number]) {
     $battleshipMove = new BattleshipMove($letter, $number)
}
// A1, B2, C3

Chain Strings

use IterTools\Multi;
use IterTools\Single;

$letters = 'abc';
$numbers = '123';

foreach (Multi::chain(Single::string($letters), Single::string($numbers)) as $character) {
    print($character);
}
// a, b, c, 1, 2, 3

Strict and Coercive Types

When there is an option, the default will do strict type comparisons:

• scalars: compares strictly by type
• objects: always treats different instances as not equal to each other
• arrays: compares serialized

When type coercion (non-strict types) is available and enabled via optional flag:

• scalars: compares by value via type juggling
• objects: compares serialized (throws \InvalidArgumentException if the object cannot be serialized)
• arrays: compares serialized

Standards

IterTools PHP conforms to the following standards:

• PSR-1 - Basic coding standard (http://www.php-fig.org/psr/psr-1/)
• PSR-4 - Autoloader (http://www.php-fig.org/psr/psr-4/)
• PSR-12 - Extended coding style guide (http://www.php-fig.org/psr/psr-12/)

License

IterTools PHP is licensed under the MIT License.

Similar Libraries in Other Languages

IterTools functionality is not limited to PHP and Python. Other languages have similar libraries. Familiar functionality is available when working in other languages.

• IterTools TypeScript/Javascript
• IterTools Python: The original!