Adding TabularDataReader::map method

CHANGELOG.md

@@ -6,7 +6,7 @@ All Notable changes to `Csv` will be documented in this file
 
 ### Added
 
-- None
+- Adding the `TabularDataReader::map` method.
 
 ### Deprecated
 

docs/9.0/reader/tabular-data-reader.md

@@ -372,6 +372,28 @@ $nbTotalCells = $resultSet->reduce(fn (?int $carry, array $records) => ($carry ?
 
 The closure is similar as the one used with `array_reduce`.
 
+### map
+
+<p class="message-notice">Added in version <code>9.21.0</code> for <code>Reader</code> and <code>ResultSet</code>.</p>
+
+The `map` method iterates over the tabular data records on map the found records to a defined structure.
+
+```php
+use League\Csv\Reader;
+use League\Csv\ResultSet;
+
+$reader = Reader::createFromPath('/path/to/my/file.csv', 'r');
+$resultSet = ResultSet::createFromTabularDataReader($reader);
+
+$mapper = fn (array $records, int $offset): int => 42;
+foreach ($resultSet->map($mapper) as $member) {
+    echo $member; //will always return the integer 42.
+}
+```
+
+<p class="message-info">This method is useful if you want, for instance, to cast the record to an instance
+you do not have control over and thus you can not use any <code>*asObject</code> methods.</p>
+
 ## Collection methods
 
 The following methods return all a new `TabularDataReader` instance.

src/Reader.php

@@ -358,6 +358,20 @@ public function reduce(callable $callback, mixed $initial = null): mixed
         return ResultSet::createFromTabularDataReader($this)->reduce($callback, $initial);
     }
 
+    /**
+     * Run a map over each container members.
+     *
+     * @template TMap
+     *
+     * @param callable(array, int): TMap $callback
+     *
+     * @return Iterator<TMap>
+     */
+    public function map(callable $callback): Iterator
+    {
+        return MapIterator::fromIterable($this, $callback);
+    }
+
     /**
      * @param positive-int $recordsCount
      *

src/ResultSet.php

@@ -164,6 +164,20 @@ public function reduce(callable $callback, mixed $initial = null): mixed
         return $initial;
     }
 
+    /**
+     * Run a map over each container members.
+     *
+     * @template TMap
+     *
+     * @param callable(array, int): TMap $callback
+     *
+     * @return Iterator<TMap>
+     */
+    public function map(callable $callback): Iterator
+    {
+        return MapIterator::fromIterable($this, $callback);
+    }
+
     /**
      * @param positive-int $recordsCount
      *

src/TabularDataReader.php

@@ -32,6 +32,7 @@
  * @method bool each(Closure $callback) iterates over each record and passes it to a closure. Iteration is interrupted if the closure returns false
  * @method bool exists(Closure $callback) tells whether at least one record satisfies the predicate.
  * @method mixed reduce(Closure $callback, mixed $initial = null) reduces the collection to a single value, passing the result of each iteration into the subsequent iteration
+ * @method Iterator map(callable $callback) Run a map over each container members.
  * @method Iterator getObjects(string $className, array $header = []) Returns the tabular data records as an iterator object containing instance of the defined class name.
  * @method Iterator getRecordsAsObject(string $className, array $header = []) Returns the tabular data records as an iterator object containing instance of the defined class name.
  * @method TabularDataReader filter(Query\Predicate|Closure $predicate) returns all the elements of this collection for which your callback function returns `true`

src/TabularDataReaderTestCase.php

@@ -308,6 +308,15 @@ public function it_fails_if_no_row_is_found(): void
         $this->tabularData()->matchingFirstOrFail('row=42');
     }
 
+    /***************************
+     * TabularDataReader::mao
+     ****************************/
+
+    public function testMap(): void
+    {
+        self::assertContains(42, $this->tabularData()->map(fn (array $record, int $offset): int => 42));
+    }
+
     /***************************
      * TabularDataReader::reduce
      ****************************/