markrogoyski / itertools-php Goto Github PK

Hi Mark!

I want to popularize IterTools among PHP developers as much as possible, because this library allows to write compact and beautiful code. Many developers live in Russian-speaking countries and I am a native Russian speaker, so I translated the documentation into Russian: https://github.com/Smoren/itertools-php/blob/docs_ru/README.md

What do you think is the best solution: to make a separate repository in my profile with the translation of the documentation, or place it into docs folder of your IterTools repository?

I understand that this is an unpopular topic today, but I sincerely believe that the world of opensource should exist outside of politics.

This thread is for discussion new functionality to implement in IterTools. Please reply with suggestions for new functionality.

Here are some of the functions I am considering implementing. Some are more useful than others.

Single Iteration

Skip

Skip the first n elements in the iterable.

public static function skip(iterable $data, int $n): \Generator

Shuffle

Shuffle the elements in the iterable.

public static function shuffle(iterable $data): \Generator

Note: More useful in a Stream than standalone function.

Filter RegEx

Filter for elements where the regular expression matches.

public static function filterRegEx(iterable $data, string $regex): \Generator

Permutations

All permutations of size $length.

public static function permutations(iterable $data, int $length) \Generator

Combinations

All combinations of size $length.

public static function combinations(iterable $data, int $length) \Generator

Combinations With Replacement

All combinations, with repeated elements, of size $length.

public static function combinationsWithReplacement(iterable $data, int $length) \Generator

Multi

Unzip

Reverse of zip.
Ex: ['a', 1], ['b', 2], ['c', 3] => ['a', 'b', 'c'], [1, 2, 3]

public static function unzip(...iterable $iterables): array

Reduce

To Random Value

Reduce the iterable to any random value in the iterable.

public static function toRandomValue(iterable $data): mixed

Note: More useful in a Stream than standalone function.

To Nth

Reduce the iterable to the value at the nth position.

public static function toNth(iterable $data): mixed

Note: More useful in a Stream than standalone function.

To Frequencies

Reduce the iterable to a frequency distribution showing how often each different value in the data occurs.

public static function toFrequencies(iterable $data): array

Note: MathPHP has this functionality. Maybe outside the scope for IterTools.

To Summary Stats

Reduce the iterable (of numbers) to a five-number summary.

public static function toSummaryStats(iterable $data): array

Note: MathPHP has this functionality. Maybe outside the scope for IterTools.

Summary

Not All Match

True if not all the elements are true according to the predicate.

public static function notAllMatch(iterable $data, callable $predicate): bool

Is Empty

True if the iterable is empty.

public static function isEmpty(iterable $data): bool

Note: More useful in a Stream than standalone function.

All Unique

True if all elements of the iterable are unique values.

public static function allUnique(iterable $data): bool

All Equal

True if all elements of the iterable are equal.

public static funcion allEqual(iterable $data): bool

Note: Consider maybe adding a strict parameter, or alternate method allSame.

Set

Union

Difference

CartesianProduct

Transform

Distribute

Distribute the elements of the iterable evenly into n smaller iterables.
Ex: [1, 2, 3, 4], 2 => [1, 3], [2, 4]

public static function distribute(iterable $data, int $n): array

Divide

Divide the elements of the iterable evenly into n smaller iterables, maintaining order.
Ex: [1, 2, 3, 4], 2 => [1, 2], [3, 4]

public static function divide(iterable $data, int $n): array

Stream

Peek

Peek at each element in between other Stream operations to do some action without modifying the stream. Useful for debugging purposes.

public function peek(callable $action): Stream

It might be useful to also add pre-built peaks:

• peakPrint
• peekPrintR

Example usage:

Stream::of($someData)
    ->map($someFunction)
    ->filter($anotherFunction)
    ->peakPrint()  // Added for debugging during development to see what is going on
    ->toAverage()

FYI: @Smoren.

Hi @markrogoyski,

What do you think about implementing pipe functionality in itertools? Something like this:

class Pipe
{
    /**
     * @var array<callable>
     */
    protected array $funcs = [];

    /**
     * @param array<callable> $funcs
     */
    public function __construct(array $funcs)
    {
        $this->funcs = $funcs;
    }

    /**
     * @param mixed $x
     * @return mixed
     */
    public function __invoke($x)
    {
        return array_reduce($this->funcs, fn ($carry, $func) => $func($carry), $x);
    }
}

$pipe = new Pipe(
    fn ($x) => $x**2,
    fn ($x) => $x+1,
);

$result = $pipe(3);
// 10 (3^2 + 1)

Do we realy need this clarification?

Look at all the points:

1. If input iterables produce duplicate items, then multiset intersection rules apply.
2. If $minIntersectionCount is 1, then multiset union rules apply.

• So if we have multisets on input then we have the case (1).
• When we have $minIntersectionCount = 1 and multisets on input, then we still have case (1).
• And when we have $minIntersectionCount = 1 and common sets on input, then no multisets rules needed.

So i think the case (2) is redundant.

Hi Mark!

What do you think about the functionality for iterating resources in IterTools? For example, reading files. Something like this:

class Resource {
    public static function readCsv(
        resource $stream,
        ?int $length = null,
        string $separator = ",",
        string $enclosure = "\"",
        string $escape = "\\"
    ): \Generator {
        while (($row = fgetcsv($handle, $length, $separator, $enclosure, $escape)) !== false) {
            yield $row;
        }
    }
}

$stream = fopen('path/to/file.csv');

foreach (Resource::readCsv($stream) as $row) {
    // ...
}

fclose($stream);

BTW, this may confuse the Stream namespace. What do you think, maybe rename Stream to Fluent or something else?

I supposed zipping of collections like in python is supposed to work for collections that are of the same size. If they are different, I think it would be a good idea to throw an exception in that case.

BTW, cool library, nice ReadMe.md and good tests!