Add new iterators & add support to allow iterables on construction of iterators

Author: coisa

composer.json

@@ -23,7 +23,7 @@
         "source": "https://github.com/php-fast-forward/iterators"
     },
     "require": {
-        "php": "^7.4 || ^8.0"
+        "php": "^8.1"
     },
     "require-dev": {
         "coisa/php-cs-fixer": "^2.1",

examples/chain-iterator.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/iterators.
+ *
+ * This source file is subject to the license that is bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/iterators
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <[email protected]>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+require_once dirname(__DIR__) . '/vendor/autoload.php';
+
+use FastForward\Iterator\ChainIterableIterator;
+
+use function FastForward\Iterator\debugIterable;
+
+/**
+ * Sample dataset for testing InterleaveIteratorIterator.
+ *
+ * @var ArrayIterator<int, int> $data1
+ * @var ArrayIterator<int, int> $data2
+ * @var ArrayIterator<int, int> $data3
+ */
+$data1 = [1, 4, 7];
+$data2 = new ArrayIterator([2, 5, 8]);
+$data3 = new ArrayIterator([3, 6, 9]);
+
+/**
+ * Creates a ChainIterableIterator with iterables to chain.
+ *
+ * @var ChainIterableIterator<int> $chain
+ */
+$chain = new ChainIterableIterator($data1, $data2, $data3);
+
+// Debugging the output of InterleaveIteratorIterator.
+debugIterable($chain, 'InterleaveIteratorIterator :: Interleaved Iteration');

examples/closure-iterator-iterator.php

@@ -19,6 +19,11 @@
 
 require_once dirname(__DIR__) . '/vendor/autoload.php';
 
+/**
+ * Sample dataset for testing ClosureIteratorIterator..
+ *
+ * @var array<int, int> $dataSet
+ */
 $data = [1, 2, 3, 4, 5];
 
 /**
@@ -29,7 +34,7 @@
  * @return ClosureIteratorIterator<int, int> the transformed iterator
  */
 $doubleIterator = new ClosureIteratorIterator(
-    new ArrayIterator($data),
+    $data,
     static fn (int $value): int => $value * 2
 );
 

examples/consecutive-group-iterator.php

@@ -22,9 +22,9 @@
 /**
  * Sample dataset for testing ConsecutiveGroupIterator.
  *
- * @var ArrayIterator<int, int> $dataSet
+ * @var array|ArrayIterator<int, int> $dataSet
  */
-$dataSet = new ArrayIterator([1, 1, 2, 2, 2, 3, 4, 4, 5]);
+$dataSet = [1, 1, 2, 2, 2, 3, 4, 4, 5];
 
 /**
  * Creates a ConsecutiveGroupIterator to group consecutive equal elements.

examples/interleave-iterator-iterator.php

@@ -26,7 +26,7 @@
  * @var ArrayIterator<int, int> $data2
  * @var ArrayIterator<int, int> $data3
  */
-$data1 = new ArrayIterator([1, 4, 7]);
+$data1 = [1, 4, 7];
 $data2 = new ArrayIterator([2, 5, 8]);
 $data3 = new ArrayIterator([3, 6, 9]);
 

src/ChainIterableIterator.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/iterators.
+ *
+ * This source file is subject to the license that is bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/iterators
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <[email protected]>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Iterator;
+
+/**
+ * Class ChainIterableIterator.
+ *
+ * An iterator that chains multiple iterable sources together into a single unified iterator.
+ *
+ * This iterator SHALL accept any number of iterable values (arrays, Traversables, or Iterators)
+ * and iterate over them in order. When the current iterator is exhausted, it proceeds to the next.
+ *
+ * The class MUST ensure all incoming values are wrapped as \Iterator instances, either natively
+ * or by converting Traversables or arrays using standard SPL iterators.
+ *
+ * Example usage:
+ *
+ * ```php
+ * $it = new ChainIterableIterator([1, 2], new ArrayIterator([3, 4]));
+ * foreach ($it as $value) {
+ *     echo $value;
+ * }
+ * // Output: 1234
+ * ```
+ *
+ * @package FastForward\Iterator
+ *
+ * @since 1.1.0
+ */
+final class ChainIterableIterator implements \Iterator
+{
+    /**
+     * @var \Iterator[] a list of iterators chained in sequence
+     */
+    private array $iterators;
+
+    /**
+     * @var int the index of the currently active iterator
+     */
+    private int $currentIndex = 0;
+
+    /**
+     * Constructs a ChainIterableIterator with one or more iterable sources.
+     *
+     * Each iterable SHALL be normalized to a \Iterator instance using:
+     * - \ArrayIterator for arrays
+     * - \IteratorIterator for Traversable objects
+     * - Directly used if already an \Iterator
+     *
+     * @param iterable ...$iterables One or more iterable data sources to chain.
+     */
+    public function __construct(iterable ...$iterables)
+    {
+        $this->iterators = array_map(
+            static fn (iterable $iterable) => new IterableIterator($iterable),
+            $iterables
+        );
+    }
+
+    /**
+     * Rewinds all underlying iterators and resets the position.
+     *
+     * Each chained iterator SHALL be rewound to its beginning.
+     */
+    public function rewind(): void
+    {
+        foreach ($this->iterators as $iterable) {
+            $iterable->rewind();
+        }
+
+        $this->currentIndex = 0;
+    }
+
+    /**
+     * Checks whether the current position is valid across chained iterators.
+     *
+     * Iteration continues until the current iterator is valid or all are exhausted.
+     *
+     * @return bool TRUE if there are more elements to iterate; FALSE otherwise
+     */
+    public function valid(): bool
+    {
+        while (isset($this->iterators[$this->currentIndex])) {
+            if ($this->iterators[$this->currentIndex]->valid()) {
+                return true;
+            }
+            ++$this->currentIndex;
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns the current element from the active iterator.
+     *
+     * @return null|mixed the current element or NULL if iteration is invalid
+     */
+    public function current(): mixed
+    {
+        if (!$this->valid()) {
+            return null;
+        }
+
+        return $this->iterators[$this->currentIndex]->current();
+    }
+
+    /**
+     * Returns the current key from the active iterator.
+     *
+     * @return null|mixed the current key or NULL if iteration is invalid
+     */
+    public function key(): mixed
+    {
+        if (!$this->valid()) {
+            return null;
+        }
+
+        return $this->iterators[$this->currentIndex]->key();
+    }
+
+    /**
+     * Moves the pointer of the active iterator forward.
+     */
+    public function next(): void
+    {
+        if (!$this->valid()) {
+            return;
+        }
+
+        $this->iterators[$this->currentIndex]->next();
+    }
+}

src/ClosureFactoryIteratorAggregate.php

@@ -109,6 +109,6 @@ public function __construct(\Closure $factory)
      */
     public function getIterator(): \Traversable
     {
-        return \call_user_func($this->factory);
+        return new IterableIterator(\call_user_func($this->factory));
     }
 }

src/ClosureIteratorIterator.php

@@ -57,12 +57,12 @@ class ClosureIteratorIterator extends \IteratorIterator
     /**
      * Initializes the ClosureIteratorIterator.
      *
-     * @param \Traversable $iterator the underlying iterator to wrap
-     * @param \Closure     $closure  the transformation function applied to each element
+     * @param iterable $iterator the underlying iterator to wrap
+     * @param \Closure $closure  the transformation function applied to each element
      */
-    public function __construct(\Traversable $iterator, \Closure $closure)
+    public function __construct(iterable $iterator, \Closure $closure)
     {
-        parent::__construct($iterator);
+        parent::__construct(new IterableIterator($iterator));
         $this->closure = $closure;
     }
 

src/ConsecutiveGroupIterator.php

@@ -67,14 +67,14 @@ class ConsecutiveGroupIterator extends \IteratorIterator
     /**
      * Initializes the ConsecutiveGroupIterator.
      *
-     * @param \Traversable $iterator the iterator containing values to be chunked
-     * @param \Closure     $callback The function that determines whether elements should be in the same chunk.
-     *                               It receives two arguments: `$previous` and `$current`,
-     *                               and must return `true` to keep them together or `false` to start a new chunk.
+     * @param iterable $iterator the iterator containing values to be chunked
+     * @param \Closure $callback The function that determines whether elements should be in the same chunk.
+     *                           It receives two arguments: `$previous` and `$current`,
+     *                           and must return `true` to keep them together or `false` to start a new chunk.
      */
-    public function __construct(\Traversable $iterator, \Closure $callback)
+    public function __construct(iterable $iterator, \Closure $callback)
     {
-        parent::__construct($iterator);
+        parent::__construct(new IterableIterator($iterator));
         $this->callback = $callback;
     }
 

src/FileExtensionFilterIterator.php

@@ -57,7 +57,7 @@ class FileExtensionFilterIterator extends \FilterIterator
     /**
      * Initializes the FileExtensionFilterIterator.
      *
-     * @param \FilesystemIterator|\RecursiveDirectoryIterator $iterator The directory iterator to wrap.
+     * @param \FilesystemIterator|\RecursiveDirectoryIterator $iterator      the directory iterator to wrap
      * @param string                                          ...$extensions The allowed file extensions.
      */
     public function __construct(\FilesystemIterator $iterator, string ...$extensions)