README Improvements

README.md

@@ -5,17 +5,16 @@
 ![Build and test](https://github.com/Smoren/array-view-php/actions/workflows/test.yml/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Array View** is a PHP library that provides a powerful set of utilities for working with arrays in
-a versatile and efficient manner. These classes enable developers to create views of arrays, manipulate data with ease,
-and select specific elements using index lists, masks, and slice parameters.
-
-Array View offers a Python-like slicing experience for efficient data manipulation and selection of array elements.
+**Array View** is a PHP library that provides powerful abstractions and utilities for working with lists of data.
+Create views of arrays, slice and index using Python-like notation, transform and select your data using chained and
+fluent operations.
 
 ## Features
-- Create array views for easy data manipulation.
-- Select elements using [Python-like slice notation](https://www.geeksforgeeks.org/python-list-slicing/).
-- Handle array slicing operations with ease.
-- Enable efficient selection of elements using index lists and boolean masks.
+- Array views as an abstraction over an array
+- Forward and backward array indexing
+- Selecting and slicing using [Python-like slice notation](https://www.geeksforgeeks.org/python-list-slicing/)
+- Filtering, mapping, matching and masking
+- Chaining operations via pipes and fluent interfaces
 
 
 ## How to install to your project
@@ -24,28 +23,49 @@ composer require smoren/array-view
 ```
 
 ## Usage
-## Quick examples
-### Indexing and Slicing
+### Indexing
+
+Index into an array forward or backwards using positive or negative indexes.
+
+| Data             |   1  |   2  |   3  |   4  |   5  |   6  |   7  |
+| ---------------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
+| *Positive Index* |  *0* |  *1* |  *2* | *3*  |  *4* |  *5* |  *6* |
+| *Negative Index* | *-7* | *-6* | *-5* | *-4* | *-3* | *-2* | *-1* |
+```php
+use Smoren\ArrayView\Views\ArrayView;
+
+$view = ArrayView::toView([1, 2, 3, 4, 5, 6, 7]);
+
+$view[0];  // 1
+$view[1];  // 2
+$view[-1]; // 7
+$view[-2]; // 6
+```
+
+### Slices
+
+Use [Python-like slice notation](https://www.geeksforgeeks.org/python-list-slicing/) to select a range of elements: `[start, stop, step]`.
 ```php
 use Smoren\ArrayView\Views\ArrayView;
 
 $originalArray = [1, 2, 3, 4, 5, 6, 7, 8, 9];
 $view = ArrayView::toView($originalArray);
 
+$view['1:6'];   // [2, 3, 4, 5, 6]
 $view['1:7:2']; // [2, 4, 6]
-$view[':3']; // [1, 2, 3]
-$view['::-1']; // [9, 8, 7, 6, 5, 4, 3, 2, 1]
-
-$view[2]; // 3
-$view[4]; // 5
-$view[-1]; // 9
-$view[-2]; // 8
+$view[':3'];    // [1, 2, 3]
+$view['::-1'];  // [9, 8, 7, 6, 5, 4, 3, 2, 1]
+```
 
+Insert into parts of the array.
+```php
 $view['1:7:2'] = [22, 44, 66];
 print_r($originalArray); // [1, 22, 3, 44, 5, 66, 7, 8, 9]
 ```
 
 ### Subviews
+
+Create subviews of the original view using masks, indexes, and slices.
 ```php
 use Smoren\ArrayView\Selectors\IndexListSelector;
 use Smoren\ArrayView\Selectors\MaskSelector;
@@ -55,19 +75,23 @@ use Smoren\ArrayView\Views\ArrayView;
 $originalArray = [1, 2, 3, 4, 5];
 $view = ArrayView::toView($originalArray);
 
+// Object-oriented style
 $view->subview(new MaskSelector([true, false, true, false, true]))->toArray(); // [1, 3, 5]
-$view->subview(new IndexListSelector([1, 2, 4]))->toArray(); // [2, 3, 5]
-$view->subview(new SliceSelector('::-1'))->toArray(); // [5, 4, 3, 2, 1]
+$view->subview(new IndexListSelector([1, 2, 4]))->toArray();                   // [2, 3, 5]
+$view->subview(new SliceSelector('::-1'))->toArray();                          // [5, 4, 3, 2, 1]
 
+// Scripting style 
 $view->subview([true, false, true, false, true])->toArray(); // [1, 3, 5]
-$view->subview([1, 2, 4])->toArray(); // [2, 3, 5]
-$view->subview('::-1')->toArray(); // [5, 4, 3, 2, 1]
+$view->subview([1, 2, 4])->toArray();                        // [2, 3, 5]
+$view->subview('::-1')->toArray();                           // [5, 4, 3, 2, 1]
 
 $view->subview(new MaskSelector([true, false, true, false, true]))->apply(fn ($x) => x * 10);
 print_r($originalArray); // [10, 2, 30, 4, 50]
 ```
 
-### Subarrays
+### Subarray Multi-indexing
+
+Directly select multiple elements using an array-index multi-selection.
 ```php
 use Smoren\ArrayView\Selectors\IndexListSelector;
 use Smoren\ArrayView\Selectors\MaskSelector;
@@ -77,26 +101,32 @@ use Smoren\ArrayView\Views\ArrayView;
 $originalArray = [1, 2, 3, 4, 5];
 $view = ArrayView::toView($originalArray);
 
+// Object-oriented style
 $view[new MaskSelector([true, false, true, false, true])]; // [1, 3, 5]
-$view[new IndexListSelector([1, 2, 4])]; // [2, 3, 5]
-$view[new SliceSelector('::-1')]; // [5, 4, 3, 2, 1]
+$view[new IndexListSelector([1, 2, 4])];                   // [2, 3, 5]
+$view[new SliceSelector('::-1')];                          // [5, 4, 3, 2, 1]
 
+// Scripting style
 $view[[true, false, true, false, true]]; // [1, 3, 5]
-$view[[1, 2, 4]]; // [2, 3, 5]
-$view['::-1']; // [5, 4, 3, 2, 1]
+$view[[1, 2, 4]];                        // [2, 3, 5]
+$view['::-1'];                           // [5, 4, 3, 2, 1]
 
 $view[new MaskSelector([true, false, true, false, true])] = [10, 30, 50];
 print_r($originalArray); // [10, 2, 30, 4, 50]
 ```
 
 ### Combining Subviews
+
+Combine and chain subviews one after another in a fluent interface to perform multiple selection operations.
 ```php
 use Smoren\ArrayView\Selectors\IndexListSelector;
 use Smoren\ArrayView\Selectors\MaskSelector;
 use Smoren\ArrayView\Selectors\SliceSelector;
 use Smoren\ArrayView\Views\ArrayView;
 
 $originalArray = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+// Fluent object-oriented style
 $subview = ArrayView::toView($originalArray)
     ->subview(new SliceSelector('::2'))                          // [1, 3, 5, 7, 9]
     ->subview(new MaskSelector([true, false, true, true, true])) // [1, 5, 7, 9]
@@ -106,6 +136,7 @@ $subview = ArrayView::toView($originalArray)
 $subview[':'] = [55, 77];
 print_r($originalArray); // [1, 2, 3, 4, 55, 6, 77, 8, 9, 10]
 
+// Fluent scripting style
 $originalArray = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 $subview = ArrayView::toView($originalArray)
     ->subview('::2')                           // [1, 3, 5, 7, 9]
@@ -118,6 +149,8 @@ print_r($originalArray); // [1, 2, 3, 4, 55, 6, 77, 8, 9, 10]
 ```
 
 ### Selectors Pipe
+
+Create pipelines of selections that can be saved and applied again and again to new array views.
 ```php
 use Smoren\ArrayView\Selectors\IndexListSelector;
 use Smoren\ArrayView\Selectors\MaskSelector;