Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
2 / 2
100.00%
2 / 2
 CRAP
100.00%
1 / 1
ClosureFactoryIteratorAggregate
100.00%
2 / 2
100.00%
2 / 2
 2
100.00%
1 / 1
 __construct
100.00%
1 / 1
100.00%
1 / 1
 1
 getIterator
100.00%
1 / 1
100.00%
1 / 1
 1
1<?php
2
3declare(strict_types=1);
4
5/**
6 * This file is part of php-fast-forward/iterators.
7 *
8 * This source file is subject to the license that is bundled
9 * with this source code in the file LICENSE.
10 *
11 * @copyright Copyright (c) 2025-2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12 * @license   https://opensource.org/licenses/MIT MIT License
13 *
14 * @see       https://github.com/php-fast-forward/iterators
15 * @see       https://github.com/php-fast-forward
16 * @see       https://datatracker.ietf.org/doc/html/rfc2119
17 */
18
19namespace FastForward\Iterator;
20
21use Closure;
22use Traversable;
23
24/**
25 * Provides an iterator implementation based on a closure factory.
26 *
27 * This class allows dynamic generation of iterators using a provided closure.
28 * It is particularly useful in scenarios where deferred computation or dynamic
29 * iterable generation is needed.
30 *
31 * ## Usage Examples:
32 *
33 * ### Using Generator Function:
34 *
35 * @example
36 * ```php
37 * use FastForward\Iterator\ClosureFactoryIteratorAggregate;
38 *
39 * $iterator = new ClosureFactoryIteratorAggregate(function () {
40 *      yield 1;
41 *      yield 2;
42 *      yield 3;x
43 * });
44 *
45 * foreach ($iterator as $value) {
46 *     echo $value; // Outputs: 1 2 3
47 * }
48 * ```
49 *
50 * ### Using Array Iterator:
51 * @example
52 * ```php
53 * use FastForward\Iterator\ClosureFactoryIteratorAggregate;
54 * use ArrayIterator;
55 *
56 * $array = [10, 20, 30];
57 * $iterator = new ClosureFactoryIteratorAggregate(fn () => new ArrayIterator($array));
58 *
59 * foreach ($iterator as $value) {
60 *     echo $value; // Outputs: 10 20 30
61 * }
62 * ```
63 *
64 * ### Generator with `return` Statement:
65 * @example
66 * ```php
67 * use FastForward\Iterator\ClosureFactoryIteratorAggregate;
68 *
69 * $iterator = new ClosureFactoryIteratorAggregate(
70 *     fn () => (function () {
71 *         yield 'A';
72 *         yield 'B';
73 *         return 'This will not be iterated';
74 *     })()
75 * );
76 *
77 * foreach ($iterator as $value) {
78 *     echo $value; // Outputs: A B
79 * }
80 * ```
81 * **Note:** If a `Generator` function includes a `return` statement,
82 * its return value will **not** be iterated.
83 *
84 * @since 1.0.0
85 */
86class ClosureFactoryIteratorAggregate extends CountableIteratorAggregate
87{
88    /**
89     * Initializes the ClosureFactoryIteratorAggregate with a closure.
90     *
91     * @param Closure $factory a function that returns an iterable structure
92     */
93    public function __construct(
94        private  Closure $factory
95    ) {}
96
97    /**
98     * Retrieves the iterator generated by the factory closure.
99     *
100     * This method invokes the provided closure and returns the resulting `Traversable` instance.
101     * **Important:** If the generator contains a `return` statement, its return value **will not** be iterated.
102     *
103     * @return Traversable the iterator generated by the factory function
104     */
105    public function getIterator(): Traversable
106    {
107        return new IterableIterator(\call_user_func($this->factory));
108    }
109}