Code Monkey home page Code Monkey logo

iterators's Introduction

Latest Stable Version GitHub stars Total Downloads GitHub Workflow Status Type Coverage License Donate!

PHP Iterators

Description

The missing PHP iterators.

Features

  • CachingIteratorAggregate
  • ChunkIterableAggregate
  • ClosureIterator: ClosureIterator(callable $callable, array $arguments = [])
  • ClosureIteratorAggregate: ClosureIteratorAggregate(callable $callable, array $arguments = [])
  • ConcatIterableAggregate
  • FilterIterableAggregate
  • InterruptableIterableIteratorAggregate: InterruptableIterableIteratorAggregate(iterable $iterable)
  • IterableIterator: IterableIterator(iterable $iterable)
  • IterableIteratorAggregate: IterableIteratorAggregate(iterable $iterable)
  • MapIterableAggregate
  • MersenneTwisterRNGIteratorAggregate
  • MultipleIterableAggregate
  • PackIterableAggregate
  • PausableIteratorAggregate
  • RandomIterableAggregate
  • ReductionIterableAggregate
  • ResourceIteratorAggregate
  • SimpleCachingIteratorAggregate
  • SortIterableAggregate
  • StringIteratorAggregate
  • TypedIterableAggregate
  • UniqueIterableAggregate
  • UnpackIterableAggregate

Installation

composer require loophp/iterators

Usage

CachingIteratorAggregate

Let you cache any iterator. You then get \Generators rewindable for free.

This implementation does not use internal state to keep track of the current position of the iterator. The underlying mechanism is based on SPL \CachingIterator.

The pros of using that iterator is performance. It's blazing fast, it cannot compare to any other stateful custom implementations.

This iterator will cache keys and values, of any type.

<?php

// Generator
$generator = static function (): \Generator {
    yield true => 'foo';
    yield false => 'bar';
    yield ['foo', 'bar'] => 'foobar';
};

$iterator = new CachingIteratorAggregate($generator());

foreach ($iterator as $key => $value); // This will work.
foreach ($iterator as $key => $value); // This will also work.

ChunkIterableAggregate

<?php

$iterator = (new ChunkIterableAggregate(
    range('a', 'j'),
    2
));

foreach ($iterator as $chunk) {} // ['a', 'b'], ['c', 'd'], ...

FilterIterableAggregate

<?php

$iterator = (new FilterIterableAggregate(
    range(0, 5),
    static fn (int $v, int $key, iterable $iterable): bool =>
        0 === (($v + 2 * $key + count($iterable)) % 2)
));

foreach ($iterator as $filteredValue) {} // 0, 2, 4

InterruptableIterableIteratorAggregate

Let you break the iterator at anytime.

Useful when working with infinite collection of items.

<?php

// Generator
$naturals = static function () {
    $i = 0;

    while (true) {
        yield $i++;
    }
};

$iterator = new InterruptableIterableIteratorAggregate($generator());

foreach ($iterator as $generator => [$key, $value]) {
    var_dump($value);

    if (10 === $value) {
        $generator->send(InterruptableIterableIteratorAggregate::BREAK);
    }
}

MapIterableAggregate

<?php

$iterator = (new MapIterableAggregate(
    range('a', 'c'),
    static fn (string $letter, int $key, iterable $iterable): string =>
        sprintf(
            '%s::%s::%s',
            $key,
            $letter,
            gettype($iterable)
        )
));

foreach ($iterator as $tranformedValue) {}

MersenneTwisterRNGIteratorAggregate

<?php

$rngGenerator = (new MersenneTwisterRNGIteratorAggregate())
    ->withMin(1)
    ->withMax(10)
    ->withSeed($seed);

foreach ($rngGenerator as $randomValue) {} // Random integers in [1, 10]

PackIterableAggregate

<?php

// Generator
$generator = static function (): \Generator {
    yield true => 'foo';
    yield false => 'bar';
    yield ['foo', 'bar'] => 'foobar';
};

$iterator = new PackIterableAggregate($generator());

foreach ($iterator as $value);
/*
$value will yield the following values:

- [true, 'foo']
- [false, 'bar']
- [['foo', 'bar'], 'foobar']
*/

UniqueIterableAggregate

<?php

$generator = static function(): Generator {
    while (true) {
        yield mt_rand(0, 9);
    }
};

$iterator = new UniqueIterableAggregate($generator(), 1000);

foreach ($iterator as $value) {} // 9 random values only.

UnpackIterableAggregate

<?php

// Generator
$generator = static function (): \Generator {
    yield [true, 'foo'];
    yield [false, 'bar'];
    yield [['foo', 'bar'], 'foobar'];
};

$iterator = new UnpackIterableAggregate($generator());

foreach ($iterator as $key => $value);
/*
$key and $value will yield the following values:

- true => 'foo'
- false => 'bar'
- ['foo', 'bar'] => 'foobar'
*/

ClosureIterator

<?php

$callable = static fn (int $from, int $to) => yield from range($from, $to);

$iterator = new ClosureIterator($callable(10, 20));

IterableIterator

<?php

$iterator = new IterableIterator(range(1, 10));

PausableIteratorAggregate

<?php

$inputIterator = new ArrayIterator(range('a', 'e'));
$iteratorAggregate = new PausableIteratorAggregate($inputIterator);

$i = 0;
foreach ($iteratorAggregate as $v) {
    var_dump($v) // Print: 'a', 'b', 'c'
    if (++$i === 2) {
        break;
    }
}

foreach ($iteratorAggregate->rest() as $v) {
    var_dump($v) // Print: 'd', 'e'
}

RandomIterableAggregate

In order to properly use this iterator, the user need to provide an extra parameter seed. By default, this parameter is set to zero and thus, the resulting iterator will be identical to the original one.

Random items are selected by choosing a random integer between zero and the value of seed. If that value is zero, then the iterator will yield else it will skip the value and start again with the next one.

The bigger the seed is, the bigger the entropy will be and the longer it will take to yield random items. It's then up to the user to choose an appropriate value. Usually a good value is twice the approximate amount of items the decorated iterator has.

If you're willing to iterate multiple times on this, use the CachingIteratorAggregate to cache the results.

This iterator works on keys and values, of any type.

<?php

$seed = random_int(0, 1000);
$inputIterator = new ArrayIterator(range('a', 'e'));
$iterator = new RandomIterableAggregate($inputIterator, $seed);

foreach ($iterator as $v) {
    var_dump($v);
}

$iterator = new CachingIteratorAggregate(
    (new RandomIterableAggregate($inputIterator, $seed))->getIterator()
);

foreach ($iterator as $v) {
    var_dump($v);
}
foreach ($iterator as $v) {
    var_dump($v);
}

ReductionIterableAggregate

<?php

$iterator = (new ReductionIterableAggregate(
    range(0, 10),
    static fn (int $carry, int $value, int $key, iterable $iterable): int => $carry + $value,
    0
));

foreach ($iterator as $reduction) {} // [0, 1, 3, 6, 10, 15, 21, 28, 36, 45, 55]

SortIterableAggregate

Implements a stable sort iterable aggregate

This means that if two elements have the same key, the one that appeared earlier in the input will also appear earlier in the sorted output.

$valueObjectFactory = static fn (int $id, int $weight): object => new class($id, $weight)
{
    public function __construct(public readonly int $id, public readonly int $weight) {}
};

$input = [
    $valueObjectFactory(id: 1, weight: 1),
    $valueObjectFactory(id: 2, weight: 1),
    $valueObjectFactory(id: 3, weight: 1),
];

$sort = new SortIterableAggregate(
  $input,
  static fn (object $a, object $b): int => $a->weight <=> $b->weight
);

Code quality, tests, benchmarks

Every time changes are introduced into the library, Github runs the tests.

The library has tests written with PHPUnit. Feel free to check them out in the tests directory.

Before each commit, some inspections are executed with GrumPHP; run composer grumphp to check manually.

Static analyzers are also controlling the code. PHPStan and PSalm are enabled to their maximum level.

Contributing

Feel free to contribute by sending pull requests. We are a usually very responsive team and we will help you going through your pull request from the beginning to the end.

For some reasons, if you can't contribute to the code and willing to help, sponsoring is a good, sound and safe way to show us some gratitude for the hours we invested in this package.

Sponsor me on Github and/or any of the contributors.

Changelog

See CHANGELOG.md for a changelog based on git commits.

For more detailed changelogs, please check the release changelogs.

iterators's People

Contributors

azjezz avatar dependabot[bot] avatar drupol avatar jdreesen avatar renovate[bot] avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

iterators's Issues

SimpleCachingIteratorAggregate doesn't handle nested traversals

Steps required to reproduce the problem

This test shows the expected behavior and it fails on the last assert, since the actual result is 3 instead of 6.

final class SimpleCachingIteratorTest extends TestCase
{
    public function testSimpleCachingIteratorInnerTraversals(): void
    {
        $iter = new SimpleCachingIteratorAggregate(new ArrayIterator([1, 2, 3, 4, 5, 6]));

        $total = 0;

        foreach ($iter as $key => $item) {
            if ($key === 2) {
                $firstTotal = $this->traverseAll($iter);

                self::assertSame(6, $firstTotal);
            }

            ++$total;
        }

        self::assertSame(6, $total);
    }

    private function traverseAll(iterable $iter): int
    {
        $total = 0;

        foreach ($iter as $item) {
            ++$total;
        }

        return $total;
    }
}

Expected Result

It is expected that one may iterate through iterator until the end regardless of whether inner iterations happen or not,

Actual Result

Test fails on final self::assertSame(6, $total);, because outer loop iterated only over 3 items instead of 6.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

Detected dependencies

composer
composer.json
  • php >= 8.1
  • drupol/php-conventions ^5
  • phpbench/phpbench ^1.2
  • phpstan/phpstan-strict-rules ^1.0
  • phpunit/php-code-coverage ^10
  • phpunit/phpunit ^10
github-actions
.github/workflows/benchmarks.yml
  • shivammathur/setup-php v2
  • actions/cache v3
  • actions/checkout v4
  • actions/checkout v4
.github/workflows/code-style.yml
  • actions/checkout v4
  • shivammathur/setup-php v2
  • ramsey/composer-install v2
.github/workflows/prettier.yml
  • actions/checkout v4
.github/workflows/prune.yaml
  • actions/stale v8
.github/workflows/release.yaml
  • actions/checkout v4
  • mindsers/changelog-reader-action v2
  • actions/create-release v1.1.4
.github/workflows/static-analysis.yml
  • actions/checkout v4
  • shivammathur/setup-php v2
  • ramsey/composer-install v2
.github/workflows/tests.yml
  • actions/checkout v4
  • WyriHaximus/github-action-composer-php-versions-in-range v1
  • actions/checkout v4
  • shivammathur/setup-php v2
  • ramsey/composer-install v2

  • Check this box to trigger a request for Renovate to run again on this repository

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.