README.md
July 26, 2026 · View on GitHub
IterTools PHP — инструментарий для работы с итерируемыми сущностями
Спроектирован для PHP аналогично itertools в Python.
Функционал
IterTools поддерживает два вида конструкций для итерирования:
- Итерирование в цикле
- Итерирование в потоке цепочечных вызовов
Пример итерирования в цикле
foreach (Multi::zip(['a', 'b'], [1, 2]) as [$letter, $number]) {
print($letter . $number); // a1, b2
}
Пример итерирования в потоке цепочечных вызовов
$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
Методы библиотеки гарантировано работают с любыми iterable сущностями:
arrayIteratorGeneratorTraversable
Установка
Добавьте библиотеку в зависимости в файле composer.json вашего проекта:
{
"require": {
"markrogoyski/itertools-php": "2.*"
}
}
Используйте composer, чтобы установить библиотеку:
$ composer install
Composer установит IterTools в папку vendor вашего проекта. После этого вы можете использовать функционал библиотеки в файлах своего проекта, используя Composer Autoloader.
require_once __DIR__ . '/vendor/autoload.php';
Альтернативный вариант установки. Выполните данную команду в терминале, находясь в корневой директории вашего проекта:
$ composer require markrogoyski/itertools-php:2.*
Минимальные требования
- PHP 8.2+
- (Для PHP 7.4–8.1 используйте v1.9)
Краткий справочник
Инструменты для итерирования в циклах
Итерирование нескольких коллекций
| Метод | Описание | Пример кода |
|---|---|---|
chain | Последовательно итерирует коллекции | Multi::chain($list1, $list2) |
roundRobin | Поочерёдно отдаёт по одному элементу из каждой коллекции, чередуя источники | Multi::roundRobin($list1, $list2) |
zip | Параллельно итерирует коллекции, пока не закончится самый короткий итератор | Multi::zip($list1, $list2) |
zipEqual | Параллельно итерирует коллекции одного размера, в случае разных размеров бросает исключение | Multi::zipEqual($list1, $list2) |
zipFilled | Параллельно итерирует коллекции с подстановкой филлера для закончившихся итераторов | Multi::zipFilled($default, $list1, $list2) |
zipLongest | Параллельно итерирует коллекции, пока не закончится самый длинный итератор | Multi::zipLongest($list1, $list2) |
unzip | Транспонирует последовательность строк в столбцы (обратная операция к zip) | Multi::unzip($rows) |
Итерирование одной коллекции
| Метод | Описание | Пример кода |
|---|---|---|
accumulate | Накапливает результат применения бинарного оператора | Single::accumulate($data, $op, [$initial]) |
chunkwise | Итерирует коллекцию, разбитую на чанки | Single::chunkwise($data, $chunkSize) |
chunkwiseOverlap | Итерирует коллекцию, разбитую на взаимонакладывающиеся чанки | Single::chunkwiseOverlap($data, $chunkSize, $overlapSize) |
compress | Возвращает элементы из коллекции, выбранные селектором | Single::compress($data, $selectors) |
compressAssociative | Возвращает элементы из коллекции по заданным ключам | Single::compressAssociative($data, $selectorKeys) |
dropLast | Перебирает все элементы, кроме последних N | Single::dropLast($data, $count) |
dropWhile | Пропускает элементы, пока предикат возвращает истину | Single::dropWhile($data, $predicate) |
enumerate | Итерирует пары [индекс, значение] | Single::enumerate($data, [$start]) |
filter | Возвращает только те элементы, для которых предикат возвращает истину | Single::filter($data, $predicate) |
filterTrue | Возвращает только истинные элементы из коллекции | Single::filterTrue($data) |
filterFalse | Возвращает только ложные элементы из коллекции | Single::filterFalse($data, $predicate) |
filterKeys | Возвращает только те элементы, для ключей которых предикат возвращает истину | Single::filterKeys($data, $predicate) |
filterWithKeys | Фильтрация предикатом, учитывающим значение и ключ | Single::filterWithKeys($data, $predicate) |
flatMap | Отображение коллекции с уплощением результата на 1 уровень вложенности | Single::flatMap($data, $mapper) |
flatMapWithKeys | Отображение, учитывающее ключи, с уплощением результата | Single::flatMapWithKeys($data, $func) |
flatten | Многоуровневое уплощение коллекции | Single::flatten($data, [$dimensions]) |
groupAdjacentBy | Группирует подряд идущие элементы по извлечённому ключу | Single::groupAdjacentBy($data, $keyFn) |
groupBy | Группирует элементы коллекции | Single::groupBy($data, $groupKeyFunction, [$itemKeyFunc]) |
intersperse | Вставляет разделитель между элементами коллекции | Single::intersperse($data, $separator) |
limit | Ограничивает итерирование коллекции заданным максимальным числом итераций | Single::limit($data, $limit) |
map | Отображение коллекции с использованием callback-функции | Single::map($data, $function) |
mapWithKeys | Отображение функцией, учитывающей значение и ключ | Single::mapWithKeys($data, $func) |
mapSpread | Отображение, при котором элементы распаковываются как позиционные аргументы | Single::mapSpread($data, $function) |
padLeft | Дополняет коллекцию слева до указанной минимальной длины | Single::padLeft($data, $length, $fill) |
padRight | Дополняет коллекцию справа до указанной минимальной длины | Single::padRight($data, $length, $fill) |
pairwise | Итерирует коллекцию попарно (с наложением) | Single::pairwise($data) |
range | Лениво генерирует конечную арифметическую прогрессию чисел | Single::range($start, $end, [$step]) |
reindex | Переиндексирует key-value коллекцию | Single::reindex($data, $reindexer) |
repeat | Повторяет данное значение заданное число раз | Single::repeat($item, $repetitions) |
reverse | Итерирует коллекцию в обратном порядке | Single::reverse($data) |
skip | Итерирует коллекцию, пропуская некоторое количество элементов подряд | Single::skip($data, $count, [$offset]) |
slice | Возвращает подвыборку коллекции | Single::slice($data, [$start], [$count], [$step]) |
splitWhen | Разбивает коллекцию на группы при срабатывании предиката | Single::splitWhen($data, $predicate) |
string | Итерирует строку посимвольно | Single::string($string) |
takeLast | Перебирает последние N элементов | Single::takeLast($data, $count) |
takeWhile | Отдает элементы, пока предикат возвращает истину | Single::takeWhile($data, $predicate) |
windowed | Итерирует скользящие окна элементов | Single::windowed($data, $size, [$step], [$partial]) |
withFirst | Сопоставляет каждому элементу флаг «первый» | Single::withFirst($data) |
withFirstAndLast | Сопоставляет каждому элементу флаги «первый»/«последний» | Single::withFirstAndLast($data) |
withLast | Сопоставляет каждому элементу флаг «последний» | Single::withLast($data) |
Бесконечное итерирование
| Метод | Описание | Пример кода |
|---|---|---|
count | Бесконечно перебирает последовательность целых чисел | Infinite::count($start, $step) |
cycle | Бесконечно зацикливает перебор коллекции | Infinite::cycle($collection) |
generate | Бесконечно отдаёт значения, возвращаемые поставщиком | Infinite::generate($supplier) |
iterate | Бесконечно применяет функцию к её предыдущему результату | Infinite::iterate($initial, $function) |
repeat | Бесконечно повторяет данное значение | Infinite::repeat($item) |
Итерирование случайных значений
| Метод | Описание | Пример кода |
|---|---|---|
choice | Случайные выборы вариантов из списка | Random::choice($list, $repetitions) |
coinFlip | Случайные броски монеты (0 или 1) | Random::coinFlip($repetitions) |
number | Случайные целые числа | Random::number($min, $max, $repetitions) |
percentage | Случайные вещественные числа между 0 и 1 | Random::percentage($repetitions) |
reservoirSample | Однопроходная равномерная случайная выборка | Random::reservoirSample($data, $size, [$engine]) |
rockPaperScissors | Случайный выбор "камень-ножницы-бумага" | Random::rockPaperScissors($repetitions) |
sample | Случайная выборка без повторений | Random::sample($data, $size, [$engine]) |
Математическое итерирование
| Метод | Описание | Пример кода |
|---|---|---|
frequencies | Абсолютное распределение частот | Math::frequencies($data, [$strict]) |
frequenciesBy | Распределение частот по функции-ключу | Math::frequenciesBy($data, $keyFunc, [$strict]) |
relativeFrequencies | Относительное распределение частот | Math::relativeFrequencies($data, [$strict]) |
relativeFrequenciesBy | Относительное распределение частот по функции-ключу | Math::relativeFrequenciesBy($data, $keyFunc, [$strict]) |
runningAverage | Накопление среднего арифметического | Math::runningAverage($numbers, $initialValue) |
runningDifference | Накопление разности | Math::runningDifference($numbers, $initialValue) |
runningMax | Поиск максимального значения | Math::runningMax($numbers, $initialValue) |
runningMin | Поиск минимального значения | Math::runningMin($numbers, $initialValue) |
runningProduct | Накопление произведения | Math::runningProduct($numbers, $initialValue) |
runningTotal | Накопление суммы | Math::runningTotal($numbers, $initialValue) |
Итерирование множеств и мультимножеств
| Метод | Описание | Пример кода |
|---|---|---|
distinct | Фильтрует коллекцию, сохраняя только уникальные значения | Set::distinct($data) |
distinctAdjacent | Удаляет только подряд идущие дубликаты | Set::distinctAdjacent($data) |
distinctAdjacentBy | Удаляет только подряд идущие дубликаты по заданному ключу | Set::distinctAdjacentBy($data, $keyFn) |
distinctBy | Фильтрует коллекцию, сохраняя только уникальные значения по компаратору | Set::distinctBy($data, $compareBy) |
duplicates | Возвращает значения, встречающиеся более одного раза | Set::duplicates($data, [$strict]) |
duplicatesBy | Возвращает дубликаты по извлечённому ключу | Set::duplicatesBy($data, $keyFn) |
intersection | Пересечение нескольких коллекций | Set::intersection(...$iterables) |
intersectionCoercive | Пересечение нескольких коллекций в режиме приведения типов | Set::intersectionCoercive(...$iterables) |
partialIntersection | Частичное пересечение нескольких коллекций | Set::partialIntersection($minCount, ...$iterables) |
partialIntersectionCoercive | Частичное пересечение нескольких коллекций в режиме приведения типов | Set::partialIntersectionCoercive($minCount, ...$iterables) |
difference | Разность коллекций | Set::difference($a, ...$iterables) |
differenceCoercive | Разность коллекций в режиме приведения типов | Set::differenceCoercive($a, ...$iterables) |
symmetricDifference | Симметрическая разница нескольких коллекций | Set::symmetricDifference(...$iterables) |
symmetricDifferenceCoercive | Симметрическая разница нескольких коллекций в режиме приведения типов | Set::symmetricDifferenceCoercive(...$iterables) |
union | Объединение нескольких коллекций | Set::union(...$iterables) |
unionCoercive | Объединение нескольких коллекций в режиме приведения типов | Set::unionCoercive(...$iterables) |
Комбинаторное итерирование
| Метод | Описание | Пример кода |
|---|---|---|
product | Декартово произведение коллекций | Combinatorics::product(...$iterables) |
permutations | Перестановки элементов коллекции | Combinatorics::permutations($data, [$r]) |
combinations | Сочетания элементов коллекции | Combinatorics::combinations($data, $r) |
combinationsWithReplacement | Сочетания с повторениями | Combinatorics::combinationsWithReplacement($data, $r) |
powerset | Все подмножества коллекции (булеан) | Combinatorics::powerset($data) |
Итерирование с сортировкой
| Итератор | Описание | Пример кода |
|---|---|---|
asort | Сортирует коллекцию с сохранением ключей | Sort::asort($data, [$comparator]) |
asortBy | Сортирует коллекцию по извлечённому ключу с сохранением ключей | Sort::asortBy($data, $keyFn) |
largest | n наибольших элементов (по убыванию) | Sort::largest($data, $n, [$keyFn]) |
shuffle | Итерирует коллекцию в случайном порядке | Sort::shuffle($data, [$engine]) |
smallest | n наименьших элементов (по возрастанию) | Sort::smallest($data, $n, [$keyFn]) |
sort | Сортирует коллекцию | Sort::sort($data, [$comparator]) |
sortBy | Сортирует коллекцию по извлечённому ключу | Sort::sortBy($data, $keyFn) |
Итерирование файлов
| Итератор | Описание | Пример кода |
|---|---|---|
readCsv | Итерирует коллекции ячеек CSV-файла построчно | File::readCsv($fileHandle) |
readCsvAssoc | Итерирует CSV-файл как массивы с ключами из заголовков | File::readCsvAssoc($fileHandle) |
readLines | Итерирует содержимое файла построчно | File::readLines($fileHandle) |
writeCsv | Записывает коллекцию строк в файл в формате CSV | File::writeCsv($fileHandle, $rows, $header) |
writeLines | Записывает коллекцию строк в файл | File::writeLines($fileHandle, $lines) |
Преобразование итерируемых сущностей
| Итератор | Описание | Пример кода |
|---|---|---|
partition | Разделяет коллекцию на два списка: истинные и ложные | Transform::partition($data, $predicate) |
tee | Создает несколько одинаковых независимых итераторов из данной коллекции | Transform::tee($data, $count) |
toArray | Преобразует итерируемую коллекцию в массив | Transform::toArray($data) |
toAssociativeArray | Преобразует итерируемую коллекцию в ассоциативный массив | Transform::toAssociativeArray($data, [$keyFunc], [$valueFunc]) |
toIterator | Преобразует итерируемую коллекцию в итератор | Transform::toIterator($data) |
Саммари о коллекции
| Метод | Описание | Пример кода |
|---|---|---|
allMatch | Истинно, если предикат возвращает истину для всех элементов коллекции | Summary::allMatch($data, $predicate) |
allUnique | Истинно, если все элементы коллекции уникальны | Summary::allUnique($data, [$strict]) |
anyMatch | Истинно, если предикат возвращает истину хотя бы для одного элемента коллекции | Summary::anyMatch($data, $predicate) |
arePermutations | Истинно, если коллекции являются перестановками друг друга | Summary::arePermutations(...$iterables) |
arePermutationsCoercive | Истинно, если коллекции являются перестановками друг друга (в режиме приведения типов) | Summary::arePermutationsCoercive(...$iterables) |
atLeastN | Истинно, если предикат возвращает истину как минимум для N элементов | Summary::atLeastN($data, $n, [$predicate]) |
atMostN | Истинно, если предикат возвращает истину не более чем для N элементов | Summary::atMostN($data, $n, [$predicate]) |
contains | Истинно, если коллекция содержит искомое значение | Summary::contains($data, $needle) |
containsCoercive | Истинно, если коллекция содержит искомое значение (в режиме приведения типов) | Summary::containsCoercive($data, $needle) |
endsWith | Истинно, если коллекция заканчивается заданным суффиксом | Summary::endsWith($data, $suffix) |
endsWithCoercive | Истинно, если коллекция заканчивается заданным суффиксом (в режиме приведения типов) | Summary::endsWithCoercive($data, $suffix) |
exactlyN | Истинно, если предикат возвращает истину в точности для N элементов | Summary::exactlyN($data, $n, $predicate) |
isPartitioned | Истинно, если истинные элементы находятся в коллекции перед ложными (истинность определяет предикат) | Summary::isPartitioned($data, $predicate) |
isEmpty | Истинно, если коллекция пуста | Summary::isEmpty($data) |
isSorted | Истинно, если коллекция отсортирована в прямом порядке | Summary::isSorted($data) |
isReversed | Истинно, если коллекция отсортирована в обратном порядке | Summary::isReversed($data) |
isSortedBy | Истинно, если коллекция отсортирована по функции-ключу в прямом порядке | Summary::isSortedBy($data, $keyFunc) |
isReversedBy | Истинно, если коллекция отсортирована по функции-ключу в обратном порядке | Summary::isReversedBy($data, $keyFunc) |
noneMatch | Истинно, если предикат возвращает ложь для всех элементов коллекции | Summary::noneMatch($data, $predicate) |
same | Истинно, если данные коллекции одинаковы | Summary::same(...$iterables) |
sameCount | Истинно, если данные коллекции имеют одинаковую длину | Summary::sameCount(...$iterables) |
startsWith | Истинно, если коллекция начинается с заданного префикса | Summary::startsWith($data, $prefix) |
startsWithCoercive | Истинно, если коллекция начинается с заданного префикса (в режиме приведения типов) | Summary::startsWithCoercive($data, $prefix) |
Редуцирование
| Метод | Описание | Пример кода |
|---|---|---|
toAverage | Среднее арифметическое элементов коллекции | Reduce::toAverage($numbers) |
toCount | Длина коллекции | Reduce::toCount($data) |
toCountBy | Количества, сгруппированные по функции-ключу | Reduce::toCountBy($data, $keyFunc) |
toFirst | Первый элемент коллекции | Reduce::toFirst() |
toFirstAndLast | Первый и последний элементы коллекции | Reduce::toFirstAndLast() |
toFirstMatch | Первый элемент, удовлетворяющий предикату | Reduce::toFirstMatch($data, $predicate, [$default]) |
toFirstMatchIndex | Индекс первого элемента, удовлетворяющего предикату | Reduce::toFirstMatchIndex($data, $predicate, [$default]) |
toFirstMatchKey | Ключ первого элемента, удовлетворяющего предикату | Reduce::toFirstMatchKey($data, $predicate, [$default]) |
toLast | Последний элемент коллекции | Reduce::toLast() |
toLastMatch | Последний элемент, удовлетворяющий предикату | Reduce::toLastMatch($data, $predicate, [$default]) |
toLastMatchIndex | Индекс последнего элемента, удовлетворяющего предикату | Reduce::toLastMatchIndex($data, $predicate, [$default]) |
toLastMatchKey | Ключ последнего элемента, удовлетворяющего предикату | Reduce::toLastMatchKey($data, $predicate, [$default]) |
toOnly | Единственный элемент коллекции | Reduce::toOnly($data) |
consume | Полный обход коллекции с отбрасыванием значений | Reduce::consume($data) |
toMax | Максимальный элемент коллекции | Reduce::toMax($numbers, [$compareBy]) |
toMin | Минимальный элемент коллекции | Reduce::toMin($numbers, [$compareBy]) |
toMinMax | Минимальный и максимальный элемент коллекции | Reduce::toMinMax($numbers, [$compareBy]) |
toMedian | Медиана коллекции | Reduce::toMedian($numbers) |
toMode | Список мод коллекции (наиболее частых значений) | Reduce::toMode($data) |
toVariance | Дисперсия (генеральная/выборочная) | Reduce::toVariance($numbers, [$sample]) |
toStandardDeviation | Стандартное отклонение (генеральное/выборочное) | Reduce::toStandardDeviation($numbers, [$sample]) |
toPercentile | Значение коллекции для заданного процентиля [0, 100] | Reduce::toPercentile($numbers, $percentile) |
toQuantile | Значение коллекции для заданного квантиля [0, 1] | Reduce::toQuantile($numbers, $quantile) |
toNth | N-й элемент коллекции | Reduce::toNth($data, $position) |
toProduct | Произведение элементов коллекции | Reduce::toProduct($numbers) |
toRandomValue | Случайный элемент из коллекции | Reduce::toRandomValue($data) |
toRange | Разница между максимальным и минимальным элементами коллекции | Reduce::toRange($numbers) |
toString | Преобразование коллекции в строку | Reduce::toString($data, [$separator], [$prefix], [$suffix]) |
toSum | Сумма элементов коллекции | Reduce::toSum($numbers) |
toValue | Редуцирование коллекции до значения, вычисляемого с использованием callback-функции | Reduce::toValue($data, $reducer, $initialValue) |
Цепочечный вызов итераторов
Фабричные методы
| Источник | Описание | Пример кода |
|---|---|---|
of | Создает поток для цепочечных вызовов из данной коллекции | Stream::of($iterable) |
ofCoinFlips | Создает поток для цепочечных вызовов из бесконечных случайных бросков монеты | Stream::ofCoinFlips($repetitions) |
ofCsvFile | Создает поток для цепочечных вызовов из строк CSV-файла | Stream::ofCsvFile($fileHandle) |
ofCsvFileAssoc | Создает поток из строк CSV-файла с ключами из заголовков | Stream::ofCsvFileAssoc($fileHandle) |
ofFileLines | Создает поток для цепочечных вызовов из строк файла | Stream::ofFileLines($fileHandle) |
ofEmpty | Создает поток для цепочечных вызовов из пустой коллекции | Stream::ofEmpty() |
ofRandomChoice | Создает поток для цепочечных вызовов из бесконечных случайных выборов элемента из списка | Stream::ofRandomChoice($items, $repetitions) |
ofRandomNumbers | Создает поток для цепочечных вызовов из бесконечного набора случайных целых чисел | Stream::ofRandomNumbers($min, $max, $repetitions) |
ofRandomPercentage | Создает поток для цепочечных вызовов из бесконечного набора случайных вещественных чисел между 0 и 1 | Stream::ofRandomPercentage($repetitions) |
ofRange | Создает ленивый поток конечной арифметической прогрессии чисел | Stream::ofRange($start, $end, $step) |
ofRockPaperScissors | Создает поток для цепочечных вызовов из бесконечных случайных выборов "камень-ножницы-бумага" | Stream::ofRockPaperScissors($repetitions) |
Цепочечные операции
| Операция | Описание | Пример кода |
|---|---|---|
accumulate | Накапливает результат применения бинарного оператора | $stream->accumulate($op, [$initial]) |
append | Добавляет значения в конец потока | $stream->append(...$values) |
asort | Сортирует коллекцию с сохранением ключей | $stream->asort([$comparator]) |
asortBy | Сортирует коллекцию по извлечённому ключу с сохранением ключей | $stream->asortBy($keyFn) |
chainWith | Добавляет в конец итератора другие коллекции для последовательного итерирования | $stream->chainWith(...$iterables) |
compress | Отфильтровывает из коллекции элементы, которые не выбраны | $stream->compress($selectors) |
compressAssociative | Оставляет элементы с выбранными ключами | $stream->compressAssociative($selectorKeys) |
chunkwise | Итерирует коллекцию с разбиением по чанкам | $stream->chunkwise($chunkSize) |
chunkwiseOverlap | Итерирует коллекцию с разбиением по взаимонакладывающимся чанкам | $stream->chunkwiseOverlap($chunkSize, $overlap) |
distinct | Фильтрует коллекцию, сохраняя только уникальные значения | $stream->distinct($strict) |
distinctAdjacent | Удаляет только подряд идущие дубликаты | $stream->distinctAdjacent() |
distinctAdjacentBy | Удаляет только подряд идущие дубликаты по заданному ключу | $stream->distinctAdjacentBy($keyFn) |
distinctBy | Фильтрует коллекцию, сохраняя только уникальные значения по компаратору | $stream->distinctBy($compareBy) |
dropLast | Перебирает все элементы потока, кроме последних N | $stream->dropLast($count) |
dropWhile | Пропускает элементы из коллекции, пока предикат возвращает истину | $stream->dropWhile($predicate) |
duplicates | Возвращает значения, встречающиеся более одного раза | $stream->duplicates([$strict]) |
duplicatesBy | Возвращает дубликаты по извлечённому ключу | $stream->duplicatesBy($keyFn) |
enumerate | Итерирует пары [индекс, значение] | $stream->enumerate([$start]) |
filter | Возвращает из коллекции только те элементы, для которых предикат возвращает истину | $stream->filter($predicate) |
filterTrue | Возвращает только истинные элементы из коллекции | $stream->filterTrue($predicate) |
filterFalse | Возвращает только ложные элементы из коллекции | $stream->filterFalse($predicate) |
filterKeys | Возвращает только те элементы, для ключей которых предикат возвращает истину | $stream->filterKeys($predicate) |
filterWithKeys | Фильтрация предикатом, учитывающим значение и ключ | $stream->filterWithKeys($predicate) |
flatMap | Отображение коллекции с уплощением результата на 1 уровень вложенности | $stream->flatMap($function) |
flatMapWithKeys | Отображение, учитывающее ключи, с уплощением результата | $stream->flatMapWithKeys($func) |
flatten | Многоуровневое уплощение коллекции | $stream->flatten($dimensions) |
frequencies | Абсолютная частота вхождений | $stream->frequencies([$strict]) |
frequenciesBy | Частота вхождений по функции-ключу | $stream->frequenciesBy($keyFunc, [$strict]) |
groupAdjacentBy | Группирует подряд идущие элементы по извлечённому ключу | $stream->groupAdjacentBy($keyFn) |
groupBy | Группирует элементы из коллекции по заданному правилу | $stream->groupBy($groupKeyFunction) |
infiniteCycle | Бесконечно зацикливает перебор коллекции | $stream->infiniteCycle() |
intersectionWith | Возвращает пересечение хранимой коллекции с другими коллекциями | $stream->intersectionWith(...$iterables) |
intersectionCoerciveWith | Возвращает пересечение хранимой коллекции с другими коллекциями (в режиме приведения типов) | $stream->intersectionCoerciveWith(...$iterables) |
intersperse | Вставляет разделитель между элементами коллекции | $stream->intersperse($separator) |
largest | Сводит поток к n наибольшим элементам (по убыванию) | $stream->largest($n, [$keyFn]) |
limit | Ограничивает итерирование коллекции заданным максимальным числом итераций | $stream->limit($limit) |
map | Отображение коллекции с использованием callback-функции | $stream->map($function) |
mapWithKeys | Отображение функцией, учитывающей значение и ключ | $stream->mapWithKeys($func) |
mapSpread | Отображение, при котором элементы распаковываются как позиционные аргументы | $stream->mapSpread($function) |
padLeft | Дополняет поток слева до указанной минимальной длины | $stream->padLeft($length, $fill) |
padRight | Дополняет поток справа до указанной минимальной длины | $stream->padRight($length, $fill) |
pairwise | Итерирует коллекцию попарно (с наложением) | $stream->pairwise() |
partialIntersectionWith | Возвращает частичное пересечение хранимой коллекции с другими коллекциями | $stream->partialIntersectionWith( $minIntersectionCount, ...$iterables) |
partialIntersectionCoerciveWith | Возвращает частичное пересечение хранимой коллекции с другими коллекциями (в режиме приведения типов) | $stream->partialIntersectionCoerciveWith( $minIntersectionCount, ...$iterables) |
productWith | Декартово произведение коллекции с другими коллекциями | $stream->productWith(...$iterables) |
permutations | Перестановки элементов коллекции | $stream->permutations([$r]) |
combinations | Сочетания элементов коллекции | $stream->combinations($r) |
combinationsWithReplacement | Сочетания с повторениями элементов потока | $stream->combinationsWithReplacement($r) |
powerset | Все подмножества элементов потока (булеан) | $stream->powerset() |
prepend | Добавляет значения в начало потока | $stream->prepend(...$values) |
reindex | Переиндексирует key-value коллекцию | $stream->reindex($reindexer) |
relativeFrequencies | Относительная частота вхождений | $stream->relativeFrequencies([$strict]) |
relativeFrequenciesBy | Относительная частота вхождений по функции-ключу | $stream->relativeFrequenciesBy($keyFunc, [$strict]) |
reservoirSample | Однопроходная равномерная случайная выборка (энергичная) | $stream->reservoirSample($size, [$engine]) |
reverse | Итерирует коллекцию в обратном порядке | $stream->reverse() |
roundRobinWith | Поочерёдно отдаёт элементы из потока и заданных коллекций, чередуя источники | $stream->roundRobinWith(...$iterables) |
runningAverage | Накопление среднего арифметического элементов коллекции | $stream->runningAverage($initialValue) |
runningDifference | Накопление разности элементов коллекции | $stream->runningDifference($initialValue) |
runningMax | Поиск максимального значения из коллекции | $stream->runningMax($initialValue) |
runningMin | Поиск минимального значения из коллекции | $stream->runningMin($initialValue) |
runningProduct | Накопление произведения элементов коллекции | $stream->runningProduct($initialValue) |
runningTotal | Накопление суммы элементов коллекции | $stream->runningTotal($initialValue) |
sample | Случайная выборка из $size элементов потока без повторений | $stream->sample($size, [$engine]) |
shuffle | Рандомизирует порядок элементов потока | $stream->shuffle([$engine]) |
skip | Пропускает n элементов коллекции | $stream->skip($count, [$offset]) |
slice | Возвращает подвыборку коллекции | $stream->slice([start], [$count], [step]) |
smallest | Сводит поток к n наименьшим элементам (по возрастанию) | $stream->smallest($n, [$keyFn]) |
sort | Сортирует хранимую коллекцию | $stream->sort([$comparator]) |
sortBy | Сортирует хранимую коллекцию по извлечённому ключу | $stream->sortBy($keyFn) |
splitWhen | Разбивает поток на группы при срабатывании предиката | $stream->splitWhen($predicate) |
differenceWith | Возвращает разность хранимой коллекции с другими коллекциями | $stream->differenceWith(...$iterables) |
differenceCoerciveWith | Возвращает разность хранимой коллекции с другими коллекциями (в режиме приведения типов) | $stream->differenceCoerciveWith(...$iterables) |
symmetricDifferenceWith | Возвращает симметрическую разность хранимой коллекции с другими коллекциями | $this->symmetricDifferenceWith(...$iterables) |
symmetricDifferenceCoerciveWith | Возвращает симметрическую разность хранимой коллекции с другими коллекциями (в режиме приведения типов) | $this->symmetricDifferenceCoerciveWith( ...$iterables) |
takeLast | Перебирает последние N элементов потока | $stream->takeLast($count) |
takeWhile | Отдает элементы из коллекции, пока предикат возвращает истину | $stream->takeWhile($predicate) |
unionWith | Возвращает объединение хранимой коллекции с другими коллекциями | $stream->unionWith(...$iterables) |
unionCoerciveWith | Возвращает объединение хранимой коллекции с другими коллекциями (в режиме приведения типов) | $stream->unionCoerciveWith(...$iterables) |
unzip | Транспонирует строки потока в столбцы (обратная операция к zip) | $stream->unzip() |
windowed | Итерирует скользящие окна элементов | $stream->windowed($size, [$step], [$partial]) |
withFirst | Сопоставляет каждому элементу флаг «первый» | $stream->withFirst() |
withFirstAndLast | Сопоставляет каждому элементу флаги «первый»/«последний» | $stream->withFirstAndLast() |
withLast | Сопоставляет каждому элементу флаг «последний» | $stream->withLast() |
zip | Транспонирует поток строк по столбцам, останавливаясь по самой короткой строке | $stream->zip() |
zipLongest | Транспонирует поток строк по столбцам до самой длинной строки (отсутствующие → null) | $stream->zipLongest() |
zipFilled | Транспонирует поток строк по столбцам до самой длинной, подставляя филлер | $stream->zipFilled($filler) |
zipEqual | Транспонирует поток строк по столбцам, бросает исключение при разных длинах | $stream->zipEqual() |
zipWith | Параллельно итерирует коллекцию вместе с другими, пока не закончится самый короткий итератор | $stream->zipWith(...$iterables) |
zipEqualWith | Параллельно итерирует коллекцию вместе с другими одного размера, в случае разных размеров бросает исключение | $stream->zipEqualWith(...$iterables) |
zipFilledWith | Параллельно итерирует коллекцию вместе с другими, подставляя для закончившихся заданный филлер | $stream->zipFilledWith($default, ...$iterables) |
zipLongestWith | Параллельно итерирует коллекцию вместе с другими, пока не закончится самый длинный итератор | $stream->zipLongestWith(...$iterables) |
Завершающие операции
Саммари о коллекции
| Операция | Описание | Пример кода |
|---|---|---|
allMatch | Истинно, если предикат возвращает истину для всех элементов коллекции | $stream->allMatch($predicate) |
allUnique | Истинно, если все элементы коллекции уникальны | $stream->allUnique([$strict]]) |
anyMatch | Истинно, если предикат возвращает истину хотя бы для одного элемента коллекции | $stream->anyMatch($predicate) |
arePermutationsWith | Истинно, если коллекции являются перестановками друг друга | $stream->arePermutationsWith(...$iterables) |
arePermutationsCoerciveWith | Истинно, если коллекции являются перестановками друг друга (в режиме приведения типов) | $stream->arePermutationsCoerciveWith(...$iterables) |
atLeastN | Истинно, если предикат возвращает истину как минимум для N элементов | $stream->atLeastN($n, [$predicate]) |
atMostN | Истинно, если предикат возвращает истину не более чем для N элементов | $stream->atMostN($n, [$predicate]) |
contains | Истинно, если поток содержит искомое значение | $stream->contains($needle) |
containsCoercive | Истинно, если поток содержит искомое значение (в режиме приведения типов) | $stream->containsCoercive($needle) |
endsWith | Истинно, если поток заканчивается заданным суффиксом | $stream->endsWith($suffix) |
endsWithCoercive | Истинно, если поток заканчивается заданным суффиксом (в режиме приведения типов) | $stream->endsWithCoercive($suffix) |
exactlyN | Истинно, если предикат возвращает истину в точности для N элементов | $stream->exactlyN($n, $predicate) |
isEmpty | Истинно, если коллекция пуста | $stream::isEmpty() |
isPartitioned | Истинно, если истинные элементы находятся в коллекции перед ложными (истинность определяет предикат) | $stream::isPartitioned($predicate) |
isSorted | Истинно, если коллекция отсортирована в прямом порядке | $stream->isSorted() |
isReversed | Истинно, если коллекция отсортирована в обратном порядке | $stream->isReversed() |
isSortedBy | Истинно, если коллекция отсортирована по функции-ключу в прямом порядке | $stream->isSortedBy($keyFunc) |
isReversedBy | Истинно, если коллекция отсортирована по функции-ключу в обратном порядке | $stream->isReversedBy($keyFunc) |
noneMatch | Истинно, если предикат возвращает ложь для всех элементов коллекции | $stream->noneMatch($predicate) |
sameWith | Истинно, если данные коллекции одинаковы | $stream->sameWith(...$iterables) |
sameCountWith | Истинно, если данные коллекции имеют одинаковую длину | $stream->sameCountWith(...$iterables) |
startsWith | Истинно, если поток начинается с заданного префикса | $stream->startsWith($prefix) |
startsWithCoercive | Истинно, если поток начинается с заданного префикса (в режиме приведения типов) | $stream->startsWithCoercive($prefix) |
Редуцирование
| Завершающая операция | Описание | Пример кода |
|---|---|---|
toAverage | Среднее арифметическое элементов коллекции | $stream->toAverage() |
toCount | Длина коллекции | $stream->toCount() |
toCountBy | Количества, сгруппированные по функции-ключу | $stream->toCountBy($keyFunc) |
toFirst | Первый элемент коллекции | $stream->toFirst() |
toFirstAndLast | Первый и последний элементы коллекции | $stream->toFirstAndLast() |
toFirstMatch | Первый элемент, удовлетворяющий предикату | $stream->toFirstMatch($predicate, [$default]) |
toFirstMatchIndex | Индекс первого элемента, удовлетворяющего предикату | $stream->toFirstMatchIndex($predicate, [$default]) |
toFirstMatchKey | Ключ первого элемента, удовлетворяющего предикату | $stream->toFirstMatchKey($predicate, [$default]) |
toLast | Последний элемент коллекции | $stream->toLast() |
toLastMatch | Последний элемент, удовлетворяющий предикату | $stream->toLastMatch($predicate, [$default]) |
toLastMatchIndex | Индекс последнего элемента, удовлетворяющего предикату | $stream->toLastMatchIndex($predicate, [$default]) |
toLastMatchKey | Ключ последнего элемента, удовлетворяющего предикату | $stream->toLastMatchKey($predicate, [$default]) |
toOnly | Единственный элемент коллекции | $stream->toOnly() |
toMax | Максимальное значение из элементов коллекции | $stream->toMax([$compareBy]) |
toMin | Минимальное значение из элементов коллекции | $stream->toMin([$compareBy]) |
toMinMax | Минимальное и максимальное значения из элементов коллекции | $stream->toMinMax([$compareBy]) |
toMedian | Медиана коллекции из потока | $stream->toMedian() |
toMode | Список мод коллекции из потока | $stream->toMode() |
toVariance | Дисперсия значений коллекции из потока | $stream->toVariance([$sample]) |
toStandardDeviation | Стандартное отклонение значений коллекции из потока | $stream->toStandardDeviation([$sample]) |
toPercentile | Значение коллекции из потока для заданного процентиля | $stream->toPercentile($percentile) |
toQuantile | Значение коллекции из потока для заданного квантиля | $stream->toQuantile($quantile) |
toNth | N-й элемент коллекции | $stream->toNth($position) |
toProduct | Произведение элементов коллекции | $stream->toProduct() |
toString | Преобразование коллекции в строку | $stream->toString([$separator], [$prefix], [$suffix]) |
toSum | Сумма элементов коллекции | $stream->toSum() |
toRandomValue | Случайный элемент из коллекции | $stream->toRandomValue() |
toRange | Разница между максимальным и минимальным элементами коллекции | $stream->toRange() |
toValue | Редуцирование коллекции до значения, вычисляемого callback-функцией | $stream->toValue($reducer, $initialValue) |
Операции трансформации
| Завершающая операция | Описание | Пример кода |
|---|---|---|
toArray | Возвращает массив из элементов потока | $stream->toArray() |
toAssociativeArray | Возвращает ассоциативный массив из элементов потока | $stream->toAssociativeArray($keyFunc, $valueFunc) |
toPartition | Разделяет поток на два списка: истинные и ложные | $stream->toPartition($predicate) |
tee | Создает несколько одинаковых независимых потоков из данной коллекции | $stream->tee($count) |
Операции с побочными эффектами
| Завершающая операция | Описание | Пример кода |
|---|---|---|
callForEach | Вызывает callback-функцию для каждого элемента потока | $stream->callForEach($function) |
consume | Полный обход потока с отбрасыванием значений | $stream->consume() |
print | print каждого элемента потока | $stream->print([$separator], [$prefix], [$suffix]) |
printLn | print каждого элемента потока с новой строки | $stream->printLn() |
toCsvFile | Записывает содержимое потока в CSV файл | $stream->toCsvFile($fileHandle, [$headers]) |
toFile | Записывает содержимое потока в файл | $stream->toFile($fileHandle) |
Операции для дебаггинга
| Отладочная операция | Описание | Пример кода |
|---|---|---|
peek | Просмотр каждого элемента коллекции между потоковыми операциями | $stream->peek($peekFunc) |
peekStream | Просмотр всей коллекции потока между операциями | $stream->peekStream($peekFunc) |
peekPrint | Печать в поток вывода каждого элемента коллекции между операциями | $stream->peekPrint() |
peekPrintR | Вызов print_r для каждого элемента коллекции между операциями | $stream->peekPrintR() |
printR | print_r каждого элемента потока | $stream->printR() |
varDump | var_dump каждого элемента потока | $stream->varDump() |
Использование
Все функции работают с iterable сущностями:
array(тип)Generator(тип)Iterator(интерфейс)Traversable(интерфейс)
Композиция вызовов
IterTools позволяет комбинировать вызовы методов, чтобы получать новые коллекции.
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
Режимы типизации
Для методов, которые используют сравнение элементов коллекций для получения результата, по умолчанию сравнения выполняются строго без приведения типов:
- scalars: сравнивает строго по типу;
- objects: всегда считает разные экземпляры неравными;
- arrays: сравнивает сериализованными.
В случае, если метод опционально поддерживает режим приведения типов (имеет аргумент $strict) при $strict установленном в false
либо если метод имеет в названии слово Coercive, он будет работать в нестрогом режиме сравнения:
- scalars: сравнивает нестрого по значению;
- objects: сравнивает сериализованными;
- arrays: сравнивает сериализованными.
Стандарты
IterTools PHP соответствует следующим стандартам:
- 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/)
Лицензия
IterTools PHP распространяется по лицензии MIT License.