Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
2 / 2
100.00%
2 / 2
 CRAP
100.00%
1 / 1
RepeatableIteratorIterator
100.00%
2 / 2
100.00%
2 / 2
 2
100.00%
1 / 1
 __construct
100.00%
1 / 1
100.00%
1 / 1
 1
 count
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 LimitIterator;
22use Countable;
23use InfiniteIterator;
24
25/**
26 * An iterator that enables repeated iteration over a finite subset of an infinite iterator.
27 *
28 * This iterator wraps an `Iterator` and applies a `LimitIterator` over an `InfiniteIterator`,
29 * allowing a limited number of repeated iterations without modifying the underlying iterator.
30 *
31 * It also implements `Countable` to return the number of elements available in the limited iteration.
32 *
33 * ## Usage Example:
34 *
35 * @example Limiting an Infinite Iterator
36 * ```php
37 * use FastForward\Iterator\RepeatableIteratorIterator;
38 * use ArrayIterator;
39 *
40 * $data = new ArrayIterator([1, 2, 3, 4, 5]);
41 * $repeatableIterator = new RepeatableIteratorIterator($data, 3);
42 *
43 * echo count($repeatableIterator); // Outputs: 3
44 *
45 * foreach ($repeatableIterator as $value) {
46 *     echo $value . ' '; // Outputs: 1 2 3
47 * }
48 * ```
49 *
50 * **Note:** The iterator **does not consume** values permanently,
51 * as it is backed by an `InfiniteIterator` and `LimitIterator`.
52 *
53 * @since 1.0.0
54 */
55class RepeatableIteratorIterator extends LimitIterator implements Countable
56{
57    /**
58     * Initializes the RepeatableIteratorIterator.
59     *
60     * @param iterable $iterator the iterator to be wrapped in an infinite loop
61     * @param int $limit the maximum number of elements to iterate over per cycle
62     * @param int $offset the starting offset within the iterator
63     */
64    public function __construct(
65        iterable $iterator,
66        private  int $limit,
67        int $offset = 0
68    ) {
69        parent::__construct(new InfiniteIterator(new IterableIterator($iterator)), $offset, $this->limit);
70    }
71
72    /**
73     * Returns the number of elements that can be iterated per cycle.
74     *
75     * @return int the count of items in the limited iteration
76     */
77    public function count(): int
78    {
79        return $this->limit;
80    }
81}