, (*1)
, (*2)
Hoa is a modular, extensible and
structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.
, (*3)
Hoa\Iterator
, (*4)
This library provides a set of useful iterator (compatible with PHP iterators).
Existing PHP iterators have been updated to get new features and prior PHP
versions compatibility., (*5)
Learn more., (*6)
Installation
With Composer, to include this library into
your dependencies, you need to
require hoa/iterator
:, (*7)
$ composer require hoa/iterator '~2.0'
For more installation procedures, please read the Source
page., (*8)
Testing
Before running the test suites, the development dependencies must be installed:, (*9)
$ composer install
Then, to run all the test suites:, (*10)
$ vendor/bin/hoa test:run
For more information, please read the contributor
guide., (*11)
Quick usage
We propose a quick overview of all iterators., (*12)
The One
Hoa\Iterator\Iterator
defines the basis of an iterator. It extends
Iterator
., (*13)
External iterator
Hoa\Iterator\Aggregate
allows a class to use an external iterator through the
getIterator
method. It extends
IteratorAggregate
, (*14)
Traversable to iterator
Hoa\Iterator\IteratorIterator
transforms anything that is
traversable into an iterator. It extends
IteratorIterator
., (*15)
Iterator of iterators
Hoa\Iterator\Outer
represents an iterator that iterates over iterators. It
extends OuterIterator
., (*16)
Mock
Hoa\Iterator\Mock
represents an empty iterator. It extends
EmptyIterator
., (*17)
Seekable
Hoa\Iterator\Seekable
represents an iterator that can be seeked. It extends
SeekableIterator
., (*18)
Map
Hoa\Iterator\Map
allows to iterate an array. It extends
ArrayIterator
., (*19)
$foobar = new Hoa\Iterator\Map(['f', 'o', 'o', 'b', 'a', 'r']);
foreach ($foobar as $value) {
echo $value;
}
/**
* Will output:
* foobar
*/
Filters
Hoa\Iterator\Filter
and Hoa\Iterator\CallbackFilter
allows to filter the
content of an iterator. It extends
FilterIterator
and
CallbackFilterIterator
., (*20)
$filter = new Hoa\Iterator\CallbackFilter(
$foobar,
function ($value, $key, $iterator) {
return false === in_array($value, ['a', 'e', 'i', 'o', 'u']);
}
);
foreach ($filter as $value) {
echo $value;
}
/**
* Will output:
* fbr
*/
Also, Hoa\Iterator\RegularExpression
allows to filter based on a regular
expression., (*21)
Limit
Hoa\Iterator\Limit
allows to iterate n elements of an iterator starting from
a specific offset. It extends LimitIterator
., (*22)
$limit = new Hoa\Iterator\Limit($foobar, 2, 3);
foreach ($limit as $value) {
echo $value;
}
/**
* Will output:
* oba
*/
Infinity
Hoa\Iterator\Infinite
allows to iterate over and over again the same iterator.
It extends InfiniteIterator
., (*23)
$infinite = new Hoa\Iterator\Infinite($foobar);
$limit = new Hoa\Iterator\Limit($infinite, 0, 21);
foreach ($limit as $value) {
echo $value;
}
/**
* Will output:
* foobarfoobarfoobarfoo
*/
Also, Hoa\Iterator\NoRewind
is an iterator that does not rewind. It extends
NoRewindIterator
., (*24)
Repeater
Hoa\Iterator\Repeater
allows to repeat an iterator n times., (*25)
$repeater = new Hoa\Iterator\Repeater(
$foobar,
3,
function ($i) {
echo "\n";
}
);
foreach ($repeater as $value) {
echo $value;
}
/**
* Will output:
* foobar
* foobar
* foobar
*/
Counter
Hoa\Iterator\Counter
is equivalent to a for($i = $from, $i < $to, $i +=
$step)
loop., (*26)
$counter = new Hoa\Iterator\Counter(0, 12, 3);
foreach ($counter as $value) {
echo $value, ' ';
}
/**
* Will output:
* 0 3 6 9
*/
Union of iterators
Hoa\Iterator\Append
allows to iterate over iterators one after another. It
extends AppendIterator
., (*27)
$counter1 = new Hoa\Iterator\Counter(0, 12, 3);
$counter2 = new Hoa\Iterator\Counter(13, 23, 2);
$append = new Hoa\Iterator\Append();
$append->append($counter1);
$append->append($counter2);
foreach ($append as $value) {
echo $value, ' ';
}
/**
* Will output:
* 0 3 6 9 13 15 17 19 21
*/
Multiple
Hoa\Iterator\Multiple
allows to iterate over several iterator at the same
times. It extends MultipleIterator
., (*28)
$foobar = new Hoa\Iterator\Map(['f', 'o', 'o', 'b', 'a', 'r']);
$baz = new Hoa\Iterator\Map(['b', 'a', 'z']);
$multiple = new Hoa\Iterator\Multiple(
Hoa\Iterator\Multiple::MIT_NEED_ANY
| Hoa\Iterator\Multiple::MIT_KEYS_ASSOC
);
$multiple->attachIterator($foobar, 'one', '!');
$multiple->attachIterator($baz, 'two', '?');
foreach ($multiple as $iterators) {
echo $iterators['one'], ' | ', $iterators['two'], "\n";
}
/**
* Will output:
* f | b
* o | a
* o | z
* b | ?
* a | ?
* r | ?
*/
Demultiplexer
Hoa\Iterator\Demultiplexer
demuxes result from another iterator. This iterator
is somehow the opposite of the Hoa\Iterator\Multiple
iterator., (*29)
$counter = new Hoa\Iterator\Counter(0, 10, 1);
$multiple = new Hoa\Iterator\Multiple();
$multiple->attachIterator($counter);
$multiple->attachIterator(clone $counter);
$demultiplexer = new Hoa\Iterator\Demultiplexer(
$multiple,
function ($current) {
return $current[0] * $current[1];
}
);
foreach ($demultiplexer as $value) {
echo $value, ' ';
}
/**
* Will output:
* 0 1 4 9 16 25 36 49 64 81
*/
File system
Hoa\Iterator\Directory
and Hoa\Iterator\FileSystem
allow to iterate the file
system where files are represented by instances of Hoa\Iterator\SplFileInfo
.
They respectively extend
DirectoryIterator
,
FilesystemIterator
and
SplFileInfo
., (*30)
$directory = new Hoa\Iterator\Directory(resolve('hoa://Library/Iterator'));
foreach ($directory as $value) {
echo $value->getFilename(), "\n";
}
/**
* Will output:
* .
* ..
* .State
* Aggregate.php
* Append.php
* CallbackFilter.php
* composer.json
* Counter.php
* Demultiplexer.php
* …
*/
Also, the Hoa\Iterator\Glob
allows to iterator with the glob strategy. It
extends GlobIterator
. Thus:, (*31)
$glob = new Hoa\Iterator\Glob(resolve('hoa://Library/Iterator') . '/M*.php');
foreach ($glob as $value) {
echo $value->getFilename(), "\n";
}
/**
* Will output:
* Map.php
* Mock.php
* Multiple.php
*/
Look ahead
Hoa\Iterator\Lookahead
allows to look ahead for the next element:, (*32)
$counter = new Hoa\Iterator\Counter(0, 5, 1);
$lookahead = new Hoa\Iterator\Lookahead($counter);
foreach ($lookahead as $value) {
echo $value;
if (true === $lookahead->hasNext()) {
echo ' (next: ', $lookahead->getNext(), ')';
}
echo "\n";
}
/**
* Will output:
* 0 (next: 1)
* 1 (next: 2)
* 2 (next: 3)
* 3 (next: 4)
* 4
*/
The Hoa\Iterator\Lookbehind
also exists and allows to look behind for the
previous element., (*33)
Buffer
Hoa\Iterator\Buffer
allows to move forward as usual but also backward up to a
given buffer size over another iterator:, (*34)
$abcde = new Hoa\Iterator\Map(['a', 'b', 'c', 'd', 'e']);
$buffer = new Hoa\Iterator\Buffer($abcde, 3);
$buffer->rewind();
echo $buffer->current(); // a
$buffer->next();
echo $buffer->current(); // b
$buffer->next();
echo $buffer->current(); // c
$buffer->previous();
echo $buffer->current(); // b
$buffer->previous();
echo $buffer->current(); // a
$buffer->next();
echo $buffer->current(); // b
/**
* Will output:
* abcbab
*/
Callback generator
Hoa\Iterator\CallbackGenerator
allows to transform any callable into an
iterator. This is very useful when combined with other iterators, for instance
with Hoa\Iterator\Limit
:, (*35)
$generator = new Hoa\Iterator\CallbackGenerator(function ($key) {
return mt_rand($key, $key * 2);
});
$limit = new Hoa\Iterator\Limit($generator, 0, 10);
foreach ($limit as $value) {
echo $value, ' ';
}
/**
* Could output:
* 0 2 3 4 4 7 8 10 12 18
*/
Recursive iterators
A recursive iterator is an iterator where its values is other iterators. The
most important interface is Hoa\Iterator\Recursive\Recursive
(it extends
RecursiveIterator
). Then we find (in
alphabetic order):, (*36)
Documentation
The
hack book of Hoa\Iterator
contains
detailed information about how to use this library and how it works., (*37)
To generate the documentation locally, execute the following commands:, (*38)
$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open
More documentation can be found on the project's website:
hoa-project.net., (*39)
Getting help
There are mainly two ways to get help:, (*40)
Contribution
Do you want to contribute? Thanks! A detailed contributor
guide explains
everything you need to know., (*41)
License
Hoa is under the New BSD License (BSD-3-Clause). Please, see
LICENSE
for details., (*42)