README

Hoa 是一套 模块化、可扩展 和 结构化 的 PHP 库。
此外，Hoa 致力于成为工业界和学术界之间的桥梁。

Hoa\Iterator

此库提供了一组有用的迭代器（兼容 PHP 迭代器）。现有的 PHP 迭代器已经更新，以获得新特性和与早期 PHP 版本的兼容性。

了解更多.

安装

使用 Composer，要将此库包含到依赖项中，您需要要求 hoa/iterator

$ composer require hoa/iterator '~2.0'

有关更多安装说明，请参阅 源代码页面。

测试

在运行测试套件之前，必须安装开发依赖项

$ composer install

然后，要运行所有测试套件

$ vendor/bin/hoa test:run

有关更多信息，请参阅 贡献者指南。

快速使用

我们提供了一个关于所有迭代器的快速概述。

单一

Hoa\Iterator\Iterator 定义了迭代器的基础。它扩展了 Iterator。

外部迭代器

Hoa\Iterator\Aggregate 允许一个类通过 getIterator 方法使用外部迭代器。它扩展了 IteratorAggregate。

可遍历到迭代器

Hoa\Iterator\IteratorIterator 将任何可 遍历 的内容转换为迭代器。它扩展了 IteratorIterator。

迭代器迭代器

Hoa\Iterator\Outer 表示一个迭代迭代器的迭代器。它扩展了 OuterIterator。

模拟

Hoa\Iterator\Mock 表示一个空的迭代器。它扩展了 EmptyIterator。

可寻址

Hoa\Iterator\Seekable 表示一个可寻址的迭代器。它扩展了 SeekableIterator。

映射

Hoa\Iterator\Map 允许迭代数组。它扩展了 ArrayIterator。

$foobar = new Hoa\Iterator\Map(['f', 'o', 'o', 'b', 'a', 'r']);

foreach ($foobar as $value) {
    echo $value;
}

/**
 * Will output:
 *     foobar
 */

过滤器

Hoa\Iterator\Filter 和 Hoa\Iterator\CallbackFilter 允许过滤迭代器的内容。它扩展了 FilterIterator 和 CallbackFilterIterator。

$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
 */

此外，Hoa\Iterator\RegularExpression 允许根据正则表达式进行过滤。

限制

Hoa\Iterator\Limit 允许从特定偏移量开始迭代迭代器的 n 个元素。它扩展了 LimitIterator。

$limit = new Hoa\Iterator\Limit($foobar, 2, 3);

foreach ($limit as $value) {
    echo $value;
}

/**
 * Will output:
 *     oba
 */

无限

Hoa\Iterator\Infinite 允许反复迭代相同的迭代器。它扩展了 InfiniteIterator。

$infinite = new Hoa\Iterator\Infinite($foobar);
$limit    = new Hoa\Iterator\Limit($infinite, 0, 21);

foreach ($limit as $value) {
    echo $value;
}

/**
 * Will output:
 *     foobarfoobarfoobarfoo
 */

此外，Hoa\Iterator\NoRewind 是一个不回滚的迭代器。它扩展了 NoRewindIterator。

重复

Hoa\Iterator\Repeater 允许重复迭代器 n 次。

$repeater = new Hoa\Iterator\Repeater(
    $foobar,
    3,
    function ($i) {
        echo "\n";
    }
);

foreach ($repeater as $value) {
    echo $value;
}

/**
 * Will output:
 *     foobar
 *     foobar
 *     foobar
 */

计数器

Hoa\Iterator\Counter 等同于 for($i = $from, $i < $to, $i += $step) 循环。

$counter = new Hoa\Iterator\Counter(0, 12, 3);

foreach ($counter as $value) {
    echo $value, ' ';
}

/**
 * Will output:
 *     0 3 6 9
 */

迭代器联合

Hoa\Iterator\Append 允许逐个遍历迭代器。它扩展了 AppendIterator。

$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 
 */

多个

Hoa\Iterator\Multiple 允许同时遍历多个迭代器。它扩展了 MultipleIterator。

$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 | ?
 */

解复用器

Hoa\Iterator\Demultiplexer 解复用另一个迭代器的结果。这个迭代器在某种程度上与 Hoa\Iterator\Multiple 迭代器相反。

$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 
 */

文件系统

Hoa\Iterator\Directory 和 Hoa\Iterator\FileSystem 允许遍历文件系统，其中文件由 Hoa\Iterator\SplFileInfo 的实例表示。它们分别扩展了 DirectoryIterator、FilesystemIterator 和 SplFileInfo。

$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
 *     …
 */

此外，Hoa\Iterator\Glob 允许使用 glob 策略进行迭代。它扩展了 GlobIterator。因此

$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
 */

预览

Hoa\Iterator\Lookahead 允许预览下一个元素

$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
 */

同样存在 Hoa\Iterator\Lookbehind，它允许回顾前一个元素。

缓冲区

Hoa\Iterator\Buffer 允许像往常一样向前移动，但也可以在另一个迭代器上向后移动，直到达到给定的缓冲区大小。

$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
 */

回调生成器

Hoa\Iterator\CallbackGenerator 允许将任何可调用函数转换为迭代器。这对于与其他迭代器结合使用非常有用，例如与 Hoa\Iterator\Limit 结合。

$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 
 */

递归迭代器

递归迭代器是一个其值是其他迭代器的迭代器。最重要的接口是 Hoa\Iterator\Recursive\Recursive（它扩展了 RecursiveIterator）。然后我们可以找到（按字母顺序）

• Hoa\Iterator\Recursive\CallbackFilter（它扩展了 RecursiveCallbackFilterIterator），
• Hoa\Iterator\Recursive\Directory（它扩展了 RecursiveDirectoryIterator），
• Hoa\Iterator\Recursive\Filter（它扩展了 RecursiveFilterIterator），
• Hoa\Iterator\Recursive\Iterator（它扩展了 RecursiveIteratorIterator），
• Hoa\Iterator\Recursive\Map（它扩展了 RecursiveArrayIterator），
• Hoa\Iterator\Recursive\Mock,
• Hoa\Iterator\Recursive\RegularExpression（它扩展了 RecursiveRegularExpression）。

文档

《Hoa\Iterator》黑客手册 包含有关如何使用此库及其工作原理的详细信息。

要本地生成文档，请执行以下命令

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

更多文档可以在项目网站上找到： hoa-project.net。

获取帮助

主要有两种获取帮助的方式

• 在 #hoaproject IRC 频道中，
• 在 users.hoa-project.net 的论坛上。

贡献

你想贡献吗？谢谢！详细的 贡献指南 解释了你需要知道的一切。

许可证

Hoa 采用新 BSD 许可证（BSD-3-Clause）。请参阅 LICENSE 以获取详细信息。