Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
4 / 4
100.00%
1 / 1
 CRAP
100.00%
1 / 1
TrimIteratorIterator
100.00%
4 / 4
100.00%
1 / 1
 1
100.00%
1 / 1
 __construct
100.00%
4 / 4
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
21/**
22 * An iterator that trims each value within a `iterable`.
23 *
24 * This class extends `ClosureIteratorIterator` and applies `trim()`
25 * to each element, removing leading and trailing characters based on
26 * the specified character mask.
27 *
28 * ## Usage Example:
29 *
30 * @example Basic Usage
31 * ```php
32 * use FastForward\Iterator\TrimIteratorIterator;
33 * use ArrayIterator;
34 *
35 * $data = new ArrayIterator(["  hello  ", "\nworld\n", "\tPHP\t"]);
36 * $trimIterator = new TrimIteratorIterator($data);
37 *
38 * foreach ($trimIterator as $value) {
39 *     echo $value . ' | '; // Outputs: "hello | world | PHP | "
40 * }
41 * ```
42 * @example Custom Trim Characters
43 * ```php
44 * use FastForward\Iterator\TrimIteratorIterator;
45 * use ArrayIterator;
46 *
47 * $data = new ArrayIterator(["--Hello--", "**World**", "!!PHP!!"]);
48 * $trimIterator = new TrimIteratorIterator($data, "-*!");
49 *
50 * foreach ($trimIterator as $value) {
51 *     echo $value . ' | '; // Outputs: "Hello | World | PHP | "
52 * }
53 * ```
54 *
55 * **Note:** If `$characters` is `null`, the default trim characters
56 * (`" \n\r\t\v\x00"`) will be used.
57 *
58 * @since 1.0.0
59 */
60class TrimIteratorIterator extends ClosureIteratorIterator
61{
62    /**
63     * @var string the default characters to trim
64     */
65    private const string DEFAULT_CHARACTERS = " \n\r\t\v\x00";
66
67    /**
68     * Initializes the TrimIteratorIterator.
69     *
70     * @param iterable $iterator the iterator containing values to be trimmed
71     * @param string|null $characters A string defining the characters to be trimmed.
72     *                                Defaults to standard whitespace characters.
73     */
74    public function __construct(iterable $iterator, ?string $characters = self::DEFAULT_CHARACTERS)
75    {
76        parent::__construct(
77            new IterableIterator($iterator),
78            static fn($current): string => mb_trim($current, $characters ?? self::DEFAULT_CHARACTERS)
79        );
80    }
81}