From 942a4139844ace89190a3d3fbf50bfeedfc077bd Mon Sep 17 00:00:00 2001 From: Mark Rogoyski Date: Thu, 21 Mar 2024 22:21:19 -0700 Subject: [PATCH 1/2] Updates to README. --- README.md | 82 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 1ed694c..cc14c8e 100644 --- a/README.md +++ b/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,44 @@ composer require smoren/array-view ``` ## Usage -## Quick examples -### Indexing and Slicing +### Indexing + +Index into an array forward or backwards using positive or negative indexes. +```php +use Smoren\ArrayView\Views\ArrayView; + +$view = ArrayView::toView([1, 2, 3, 4, 5, 6, 7, 8, 9]); + +$view[0]; // 1 +$view[1]; // 2 +$view[-1]; // 9 +$view[-2]; // 8 +``` + +### 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 +70,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,19 +96,23 @@ 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; @@ -97,6 +120,8 @@ 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 +131,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 +144,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; From e3760db8e5b4a360f91ed96e86d1c28ab24cad55 Mon Sep 17 00:00:00 2001 From: Mark Rogoyski Date: Thu, 21 Mar 2024 22:37:28 -0700 Subject: [PATCH 2/2] Add table. --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cc14c8e..348322d 100644 --- a/README.md +++ b/README.md @@ -26,15 +26,20 @@ composer require smoren/array-view ### 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, 8, 9]); +$view = ArrayView::toView([1, 2, 3, 4, 5, 6, 7]); $view[0]; // 1 $view[1]; // 2 -$view[-1]; // 9 -$view[-2]; // 8 +$view[-1]; // 7 +$view[-2]; // 6 ``` ### Slices