doc

readme.md

@@ -13,45 +13,56 @@ Most of its functionality is based on native _generators_ for efficiency with la
 
 Toru provides a few common **iteration primitives** (e.g. `map`, `filter`, `tap`),
 **aggregates** (e.g. `reduce`, `search`, `count`)
-and utility functions (e.g. `chain`) implemented using _generators_.
+and utility functions (e.g. `chain`) implemented using **generators**.
 
-Key abilities:
+TL;DR:
 
-- transform elements of `iterable` type* collections (iterators and arrays alike) _without_ converting to arrays
-- provide _keys_ as well as values for every mapper, filter, reducer or effect function
+- transform elements of native `iterable` type* collections (iterators and arrays) _without_ converting to arrays
+- keys (indexes) provided for every mapper, filter, reducer or effect function
+- fluent call chaining enabled (Lodash-style)
+- lazy per-element evaluation of transformations
 - transform large data sets without increasing memory usage
-- lazy evaluation of all transformations
-- fluent call chaining enabled
 - better memory efficiency of generators compared to native array functions
 - slower than native array functions or direct transformations inside a `foreach` block
 
+>
+> \* The `iterable` is a built-in compile time type alias for `array|Traversable` encompassing all arrays and iterators,
+> so it's not exactly a native type, technically speaking.
+>
 
-Toru implements **Lodash-style fluent call chaining** to simplify composition of various transformations on iterable collections.
+Lodash-style **fluent call chaining** enables neat transformation composition.
+```php
+_dash($collection)
+    ->filter(predicate: $filterFunction)
+    ->map(values: $mapperFunction)
+    ->chain($moreElements)
+    ->valuesOnly();
+```
 
-The aim of Toru is to provide simple tools to work with the native `iterable` type*.  
-Leveraging generators, Toru enables memory-efficient operations on large data sets.
+Toru enables memory-efficient operations on large data sets,
+because it leverages generators, which work on per-element basis and do not allocate extra memory.
+```php
+// no extra memory wasted on creating a filtered array
+$filtered = Itera::filter(input: $hugeDataSet, predicate: $filterFunction);
+foreach($filtered as $key => $value){ /* ... */ }
+```
 
 All callable parameters always **receive keys** along with values.  
 This is a key advantage over native functions like `array_map`, `array_reduce`, `array_walk`, or `array_filter`.
+```php
+$addresses = [
+    'john.doe@example.com' => 'John Doe',
+    'jane.doe@example.com' => 'Jane Doe',
+];
+$recipients = Itera::map(
+    $addresses, 
+    fn($recipientName, $recipientAddress) => new Recipient($recipientAddress, $recipientName),
+);
+Mailer::send($mail, $recipients);
+```
 
 The package name comes from Japanese word "toru" (取る), which may mean "to take", "to pick up" or even "to collect".
 
-Use Toru when:
-
-- in need to perform operations on `iterable` _without_ converting to arrays
-- in need to work with _keys_, as alternative to `array_map`, `array_filter` or `array_reduce`
-- unable to use `foreach`
-- working with large data sets
-- running out of memory when transforming large collections (using arrays)
-- wanting to compose collection transformations neatly in fluent call chain, Lodash-style
-- in need of lazy evaluation (on-demand, per-element transformations)
-
->
-> \* The `iterable` is a built-in compile time type alias for `array|Traversable` encompassing all arrays and iterators,
-> so it's not exactly a native type, technically speaking.
->
-
-
 
 ## Examples