gielfeldt/iterators

Various iterators.

Iterators

[][8], _(*1)

, _(*2)

[][7] [][7], _(*3)

Installation

composer require gielfeldt/iterators

Iterators

This library contains a bunch of various iterators that I made primarily for getting more acquainted with iterators in PHP. Some may be useful. Some may be silly., _(*4)

Enjoy!, _(*5)

CachingIterator, _(*6)

ChecksumIterator, _(*7)

ChunkIterator, _(*8)

CloningIterator, _(*9)

CombineIterator, _(*10)

CountableIterator, _(*11)

DiffIterator, _(*12)

FiniteIterator, _(*13)

FlipIterator, _(*14)

GlobIterator, _(*15)

IndexIterator, _(*16)

InfiniteIterator, _(*17)

InterleaveIterator, _(*18)

IntersectIterator, _(*19)

TraversableIterator, _(*20)

KeysIterator, _(*21)

MapIterator, _(*22)

RandomIterator, _(*23)

RepeatIterator, _(*24)

ReplaceableIterator, _(*25)

ReservoirSamplingIterator, _(*26)

ShuffleIterator, _(*27)

SortIterator, _(*28)

StepIterator, _(*29)

UniqueIterator, _(*30)

ValuesIterator, _(*31)

CachingIterator

Cache an iterator for multiple iterations., _(*32)

use Gielfeldt\Iterators\CachingIterator;

$input = new \ArrayIterator(range(1, 4));
$input = new \NoRewindIterator($input);
$cached = new CachingIterator($input);

print_r(iterator_to_array($cached));
print_r(iterator_to_array($cached));

Output:, _(*33)

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)

ChecksumIterator

Generate a checksum for an iterator, either per iteration or the entire dataset., _(*34)

use Gielfeldt\Iterators\ChecksumIterator;

$input = new \ArrayIterator([
    ['key1' => 'value1'],
    ['key2' => 'value2'],
    ['key3' => 'value3'],
]);

$iterator = new ChecksumIterator($input, 'md5');
foreach ($iterator as $key => $value) {
    print "$key => $value\n";
}

var_dump($iterator->getChecksum());

var_dump((string) $iterator);

Output:, _(*35)

0 => e2e517365ffe6fedd279364e3fa74786
1 => f0a0db0fc9abe193b21fd657fe678884
2 => c04f606bb5bba82282dfa93edb59c6ee

string(32) "4fd19adc845da6fdd9c7c394f4626bac"

string(32) "4fd19adc845da6fdd9c7c394f4626bac"

ChunkIterator

Split an iterator into chunks of iterators., _(*36)

use Gielfeldt\Iterators\ChunkIterator;
use Gielfeldt\Iterators\AtomicTempFileObject;

// Split a file into multiple files of a 100 lines each.
$file = new \SplFileObject('inputfile');
foreach (new ChunkIterator($file, 100) as $i => $lines) {
    AtomicTempFileObject::file_put_contents("outputfile.part.$i", implode("", iterator_to_array($lines)));
}

CloningIterator

Clone each value in iteration., _(*37)

use Gielfeldt\Iterators\CloningIterator;

$object1 = (object) ['value' => 'test1'];
$object2 = (object) ['value' => 'test2'];
$object3 = (object) ['value' => 'test3'];

$input = new \ArrayIterator([$object1, $object2, $object3]);

$iterator = new CloningIterator($input);
$cloned = iterator_to_array($iterator);
$object1->value = 'MODIFIED';
var_dump(iterator_to_array($input));
var_dump($cloned);

Output:, _(*38)

array(3) {
  [0] =>
  class stdClass#2 (1) {
    public $value =>
    string(8) "MODIFIED"
  }
  [1] =>
  class stdClass#3 (1) {
    public $value =>
    string(5) "test2"
  }
  [2] =>
  class stdClass#4 (1) {
    public $value =>
    string(5) "test3"
  }
}

array(3) {
  [0] =>
  class stdClass#9 (1) {
    public $value =>
    string(5) "test1"
  }
  [1] =>
  class stdClass#10 (1) {
    public $value =>
    string(5) "test2"
  }
  [2] =>
  class stdClass#11 (1) {
    public $value =>
    string(5) "test3"
  }
}

CombineIterator

Similar to array_combine(). However, iterators can have non-unique keys. Be aware of this when using iterator_to_array();, _(*39)

use Gielfeldt\Iterators\CombineIterator;

$keys = new \ArrayIterator(['key1', 'key2', 'key3', 'key1', 'key2', 'key3']);
$values = new \ArrayIterator(['value1', 'value2', 'value3', 'value4', 'value5', 'value6']);

$iterator = new CombineIterator($keys, $values);
foreach ($iterator as $key => $value) {
    print "$key => $value\n";
}

print_r(iterator_to_array($iterator));

Output:, _(*40)

key1 => value1
key2 => value2
key3 => value3
key1 => value4
key2 => value5
key3 => value6
Array
(
    [key1] => value4
    [key2] => value5
    [key3] => value6
)

CountableIterator

Takes any iterator and makes it countable, simply by iterating through it and counting., _(*41)

use Gielfeldt\Iterators\CountableIterator;

$some_noncountable_iterator = new \IteratorIterator(new \ArrayIterator([1, 2, 3]));
$iterator = new CountableIterator($some_noncountable_iterator);
var_dump(count($iterator));

Output:, _(*42)

int(3)

DiffIterator

Compares two iterators. Similar to array_diff(). Possible to set a custom compare function., _(*43)

use Gielfeldt\Iterators\DiffIterator;

$input1 = new \ArrayIterator(['key1'  => 'value1', 'key2'  => 'value2', 'key3'  => 'value3']);
$input2 = new \ArrayIterator(['key11' => 'value1', 'key22' => 'value1', 'key2'  => 'value3']);
$input3 = new \ArrayIterator(['key1'  => 'value2', 'key2'  => 'value2', 'key33' => 'value3']);

$iterator = new DiffIterator($input1, $input2, $input3);
$iterator->setDiff(function ($iterator, $key, $value) {
    return $iterator->key() == $key && $iterator->current() == $value;
});
print_r(iterator_to_array($iterator));

Output:, _(*44)

Array
(
    [key1] => value1
    [key3] => value3
)

FiniteIterator

Provide an end condition through an anonymous function for an iterator., _(*45)

use Gielfeldt\Iterators\FiniteIterator;

$input = new \ArrayIterator(range(1, 8));
$some = new FiniteIterator($input, function ($iterator) {
    return $iterator->current() > 5;
});

print_r(iterator_to_array($some));

Output:, _(*46)

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

FlipIterator

Similar to array_flip(). However, iterators can have non-unique keys. Be aware of this when using iterator_to_array();, _(*47)

use Gielfeldt\Iterators\FlipIterator;

$input = new \ArrayIterator([
    'key1'  => 'value1',
    'key2'  => 'value2',
    'key3'  => 'value3',
    'key4'  => 'value1',
    'key5'  => 'value2',
    'key6'  => 'value3',
]);

$iterator = new FlipIterator($input);
foreach ($iterator as $key => $value) {
    print "$key => $value\n";
}

print_r(iterator_to_array($iterator));

Output:, _(*48)

value1 => key1
value2 => key2
value3 => key3
value1 => key4
value2 => key5
value3 => key6
Array
(
    [value1] => key4
    [value2] => key5
    [value3] => key6
)

GlobIterator

Similar to \GlobIterator, but supports **, _(*49)

use Gielfeldt\Iterators\GlobIterator;

$iterator = new GlobIterator('/tmp/**.log');
var_dump(iterator_to_array($iterator));

Output:, _(*50)

array(2) {
  '/tmp/one.log' =>
  class Gielfeldt\Iterators\GlobIteratorFileInfo#17 (2) {
    private $pathName =>
    string(20) "/tmp/one.log"
    private $fileName =>
    string(10) "one.log"
  }
  '/tmp/somedir/two.log' =>
  class Gielfeldt\Iterators\GlobIteratorFileInfo#16 (2) {
    private $pathName =>
    string(20) "/tmp/somedir/two.log"
    private $fileName =>
    string(15) "two.log"
  }
}

IndexIterator

Iterate only through certain rows of an iterator., _(*51)

use Gielfeldt\Iterators\IndexIterator;

$input = new \ArrayIterator([
    'test1' => 'val6',
    'test2' => 'val5',
    'test3' => 'val4',
    'test4' => 'val3',
    'test5' => 'val2',
    'test6' => 'val1',
]);
$some = new IndexIterator($input, [2, 3, 5]);

print_r(iterator_to_array($some));

Output:, _(*52)

Array
(
    [test3] => val4
    [test4] => val3
    [test6] => val1
)

InfiniteIterator

Like SPL's InfiniteIterator but provides an additional method, getCurrentIteration()., _(*53)

use Gielfeldt\Iterators\InfiniteIterator;
use Gielfeldt\Iterators\FiniteIterator;

$input = new \ArrayIterator(range(1, 4));
$infinite = new InfiniteIterator($input);
$some = new FiniteIterator($infinite, function ($iterator) {
    return $iterator->getCurrentIteration() >= 2 && $iterator->current() > 2;
});

foreach ($some as $k => $v) {
    print $some->getCurrentIteration() . ": $k => $v\n";
}

Output:, _(*54)

0: 0 => 1
0: 1 => 2
0: 2 => 3
0: 3 => 4
1: 0 => 1
1: 1 => 2
1: 2 => 3
1: 3 => 4
2: 0 => 1
2: 1 => 2

InterleaveIterator

Interleave multiple iterators., _(*55)

use Gielfeldt\Iterators\InterleaveIterator;

$input1 = new \ArrayIterator([
    'key1' => 'value11',
    'key2' => 'value12',
    'key3' => 'value13',
]);

$input2 = new \ArrayIterator([
    'key21' => 'value21',
    'key22' => 'value22',
    'key23' => 'value23',
]);

$input3 = new \ArrayIterator([
    'key1' => 'value31',
    'key2' => 'value32',
    'key3' => 'value33',
]);

$iterator = new InterleaveIterator($input1, $input2, $input3);
foreach ($iterator as $key => $value) {
    print "$key => $value\n";
}

print_r(iterator_to_array($iterator));

Output:, _(*56)

key1 => value11
key21 => value21
key1 => value31
key2 => value12
key22 => value22
key2 => value32
key3 => value13
key23 => value23
key3 => value33
Array
(
    [key1] => value31
    [key21] => value21
    [key2] => value32
    [key22] => value22
    [key3] => value33
    [key23] => value23
)

IntersectIterator

Similar to array_intersect(). Possible to set a custom compare function., _(*57)

use Gielfeldt\Iterators\IntersectIterator;

$input1 = new \ArrayIterator(['key1'  => 'value1', 'key2' => 'value2', 'key3' => 'value3']);
$input2 = new \ArrayIterator(['key11' => 'value1', 'key1' => 'value1', 'key2' => 'value3']);
$input3 = new \ArrayIterator(['key1'  => 'value2', 'key2' => 'value2', 'key1' => 'value1']);

$iterator = new IntersectIterator($input1, $input2, $input3);
$iterator->setDiff(function ($iterator, $key, $value) {
    return $iterator->key() == $key && $iterator->current() == $value;
});
print_r(iterator_to_array($iterator));

Output:, _(*58)

Array
(
    [key1] => value1
)

TraversableIterator

Like SPL's IteratorIterator, but with a more meaningful name :-) and provides a getIndex() method., _(*59)

use Gielfeldt\Iterators\TraversableIterator;

$keys = range(1, 10);
shuffle($keys);
$values = range(1, 10);
shuffle($values);

$input = new \ArrayIterator(array_combine($keys, $values));
$iterator = new TraversableIterator($input);

foreach ($iterator as $k => $v) {
    print $iterator->getIndex() . ": $k => $v\n";
}

Output:, _(*60)

0: 1 => 3
1: 4 => 2
2: 9 => 10
3: 3 => 8
4: 2 => 6
5: 5 => 5
6: 8 => 1
7: 10 => 9
8: 6 => 7
9: 7 => 4

KeysIterator

Similar to array_keys()., _(*61)

use Gielfeldt\Iterators\KeysIterator;

$input = new \ArrayIterator([
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3',
]);

$iterator = new KeysIterator($input);

print_r(iterator_to_array($iterator));

Output:, _(*62)

Array
(
    [0] => key1
    [1] => key2
    [2] => key3
)

MapIterator

Similar to array_map()., _(*63)

use Gielfeldt\Iterators\MapIterator;

$input = new \ArrayIterator([
    'key1'  => 'value1',
    'key2'  => 'value2',
    'key3'  => 'value3',
    'key4'  => 'value1',
    'key5'  => 'value2',
    'key6'  => 'value3',
]);

// Flip keys and values.
$iterator = new MapIterator($input, function ($iterator) {
    return [$iterator->current(), $iterator->key()];
});

foreach ($iterator as $key => $value) {
    print "$key => $value\n";
}

print_r(iterator_to_array($iterator));

Output:, _(*64)

value1 => key1
value2 => key2
value3 => key3
value1 => key4
value2 => key5
value3 => key6
Array
(
    [value1] => key4
    [value2] => key5
    [value3] => key6
)

RandomIterator

Selects a set of random elements from a traversable. Does not work with iterators that can only be traversed once. For that, see the ReservoirSamplingIterator., _(*65)

use Gielfeldt\Iterators\RandomIterator;

$input = new \ArrayIterator(range(1, 10));
$random = new RandomIterator($input, 4);

var_dump(count($random));

print_r(iterator_to_array($random));

Output:, _(*66)

int(4)
Array
(
    [1] => 2
    [6] => 7
    [7] => 8
    [8] => 9
)

RepeatIterator

Repeat and iterator n times., _(*67)

use Gielfeldt\Iterators\RepeatIterator;

$input = new \ArrayIterator([
    'key1'  => 'value1',
    'key2'  => 'value2',
    'key3'  => 'value3',
]);

$iterator = new RepeatIterator($input, 3);

foreach ($iterator as $key => $value) {
    print "$key => $value\n";
}

print_r(iterator_to_array($iterator));

Output:, _(*68)

key1 => value1
key2 => value2
key3 => value3
key1 => value1
key2 => value2
key3 => value3
key1 => value1
key2 => value2
key3 => value3
Array
(
    [key1] => value1
    [key2] => value2
    [key3] => value3
)

ReplaceableIterator

Just like TraversableIterator but with a setInnerIterator() method., _(*69)

use Gielfeldt\Iterators\ReplaceableIterator;

$iterator = new ReplaceableIterator(new \ArrayIterator(range(1, 4)));
print_r(iterator_to_array($iterator));

$iterator->setInnerIterator(new \ArrayIterator(range(5, 8)));
print_r(iterator_to_array($iterator));

Output:, _(*70)

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)
Array
(
    [0] => 5
    [1] => 6
    [2] => 7
    [3] => 8
)

ReservoirSamplingIterator

Like RandomIterator but works more effeciently on iterators of unknown size or which can be traversed only once., _(*71)

use Gielfeldt\Iterators\ReservoirSamplingIterator;

$input = new \ArrayIterator(range(1, 10));
$input = new \NoRewindIterator($input);
$random = new ReservoirSamplingIterator($input, 4);

print_r(iterator_to_array($random));

Output:, _(*72)

int(4)
Array
(
    [1] => 2
    [6] => 7
    [7] => 8
    [8] => 9
)

ShuffleIterator

Iterate randomly over a traversable., _(*73)

use Gielfeldt\Iterators\ShuffleIterator;

$input = new \ArrayIterator(range(1, 10));
$shuffled = new ShuffleIterator($input);

print_r(iterator_to_array($shuffled));
print_r(iterator_to_array($shuffled));

Output:, _(*74)

Array
(
    [1] => 2
    [4] => 5
    [0] => 1
    [9] => 10
    [7] => 8
    [5] => 6
    [2] => 3
    [8] => 9
    [3] => 4
    [6] => 7
)
Array
(
    [1] => 2
    [9] => 10
    [4] => 5
    [2] => 3
    [5] => 6
    [0] => 1
    [8] => 9
    [3] => 4
    [7] => 8
    [6] => 7
)

SortIterator

use Gielfeldt\Iterators\SortIterator;

$input = new \ArrayIterator([6, 3, 2, 7, 1, 9]);
$iterator = new SortIterator($input);
print_r(iterator_to_array($iterator));

$input = new \ArrayIterator([6, 3, 2, 7, 1, 9]);
$iterator = new SortIterator($input, SortIterator::SORT_DESC);
print_r(iterator_to_array($iterator));

$input = new \ArrayIterator([6, 3, 2, 7, 1, 9]);
$iterator = new SortIterator($input, SortIterator::SORT_ASC, SortIterator::SORT_REINDEX);
print_r(iterator_to_array($iterator));

$input = new \ArrayIterator([6, 3, 2, 7, 1, 9]);
$iterator = new SortIterator($input, SortIterator::SORT_ASC, SortIterator::SORT_REINDEX, function ($a, $b) {
    return -$a->current <=> -$b->current;
});
print_r(iterator_to_array($iterator));

Output:, _(*75)

Array
(
    [4] => 1
    [2] => 2
    [1] => 3
    [0] => 6
    [3] => 7
    [5] => 9
)
Array
(
    [5] => 9
    [3] => 7
    [0] => 6
    [1] => 3
    [2] => 2
    [4] => 1
)
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 6
    [4] => 7
    [5] => 9
)
Array
(
    [0] => 9
    [1] => 7
    [2] => 6
    [3] => 3
    [4] => 2
    [5] => 1
)

StepIterator

Iterate over a traversable in steps., _(*76)

use Gielfeldt\Iterators\StepIterator;

$input = new \ArrayIterator(range(1, 10));
$stepped = new StepIterator($input, 2);

print_r(iterator_to_array($stepped));

Output:, _(*77)

Array
(
    [0] => 1
    [2] => 3
    [4] => 5
    [6] => 7
    [8] => 9
)

UniqueIterator

Similar to array_unique(). Also supports a custom callback function., _(*78)

use Gielfeldt\Iterators\UniqueIterator;

$input = new \ArrayIterator([-4, -3, -2, -1, 0, 1, 2, 3, 5]);

// Unique elements by their square.
$iterator = new UniqueIterator($input, UniqueIterator::REINDEX, function ($iterator) {
    return $iterator->current() * $iterator->current();
});

print_r(iterator_to_array($iterator));

Output:, _(*79)

Array
(
    [0] => -4
    [1] => -3
    [2] => -2
    [3] => -1
    [4] => 0
    [8] => 5
)

ValuesIterator

Similar to array_vales()., _(*80)

use Gielfeldt\Iterators\ValuesIterator;

$input = new \ArrayIterator([
    'key1' => 'value1',
    'key2' => 'value2',
    'key3' => 'value3',
]);

$iterator = new ValuesIterator($input);

print_r(iterator_to_array($iterator));

Output:, _(*81)

Array
(
    [0] => value1
    [1] => value2
    [2] => value3
)

Not iterators as such ...

These are more an extension of the SPL file handling., _(*82)

CsvFileObject, _(*83)

AtomicTempFileObject, _(*84)

AtomicTempFileObjects, _(*85)

CsvFileObject

An extension of SplFileObject in csv mode, but with csv header support., _(*86)

use Gielfeldt\Iterators\CsvFileObject;

// Load csv file and dump it.
$file = new CsvFileObject('somefile.csv');
print_r(iterator_to_array($file));

// Same but csv comes via a string variable.
$csvdata = "Columm1,Column2\nValue1,Value2\nValue3,Value4";
$file = new CsvFileObject('data://application/octet,' . $csvdata);
print_r(iterator_to_array($file));

Output:, _(*87)

Array
(
    [0] => Array
        (
            [Columm1] => Value1
            [Column2] => Value2
        )

    [1] => Array
        (
            [Columm1] => Value3
            [Column2] => Value4
        )

)
Array
(
    [0] => Array
        (
            [Columm1] => Value1
            [Column2] => Value2
        )

    [1] => Array
        (
            [Columm1] => Value3
            [Column2] => Value4
        )

)

AtomicTempFileObject

AtomicTempFileObjects

Helpers

Contains various helper methods., _(*88)

Iterator

use Gielfeldt\Iterators\Iterator;

$input = new \ArrayIterator([1,2,3,4,5,6]);
var_dump(Iterator::sum($input));
var_dump(Iterator::product($input));
var_dump(Iterator::average($input));
var_dump(Iterator::min($input));
var_dump(Iterator::max($input));

Output:, _(*89)

int(21)

int(720)

double(3.5)

int(1)

int(6)

Caveats

1. Lots probably.