Skip to content

Commit 0997992

Browse files
oliverearloliverearl
authored
Merge pull request #7 from petrobolos/docs/update-readme
Docs/update readme
2 parents 3ff52a1 + 6c5157b commit 0997992

File tree

1 file changed

+77
-40
lines changed

1 file changed

+77
-40
lines changed

‎README.md

+77-40
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,16 @@
11
# Fixed Array Functions
22

33
[![Latest Version on Packagist](https://img.shields.io/packagist/v/petrobolos/fixed-array-functions.svg?style=flat-square)](https://packagist.org/packages/petrobolos/fixed-array-functions)
4+
[![GitHub issues](https://img.shields.io/github/issues/petrobolos/fixed-array-functions)](https://github.com/petrobolos/fixed-array-functions/issues)
45
[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/petrobolos/fixed-array-functions/run-tests?label=tests)](https://github.com/petrobolos/fixed-array-functions/actions?query=workflow%3Arun-tests+branch%3Amain)
56
[![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/petrobolos/fixed-array-functions/Check%20&%20fix%20styling?label=code%20style)](https://github.com/petrobolos/fixed-array-functions/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
67
[![Total Downloads](https://img.shields.io/packagist/dt/petrobolos/fixed-array-functions.svg?style=flat-square)](https://packagist.org/packages/petrobolos/fixed-array-functions)
8+
[![GitHub](https://img.shields.io/github/license/petrobolos/fixed-array-functions)](https://www.github.com/petrobolos/fixed-array-functions)
79

8-
SplFixedArrays are an implementation of a traditional, bounded array in the PHP standard library. While they require
9-
manual resizing, they're significantly faster than regular arrays or collections when working with large sets of data.
10+
SplFixedArrays are an implementation of a traditional, bounded array in the PHP standard library.
1011

11-
Working with large amounts of game data is increasingly common at Petrobolos, so this library was born to make things
12-
easier and as efficient as possible.
13-
14-
## Full list of working methods:
15-
16-
| Method | Description | Example |
17-
|:---------------|:----------------------------------------------------------------------------|------------------------------------------------:|
18-
| add | Alias for push. | `FixedArray::add('bacon', $arr)` |
19-
| addFrom | Add an array or collection of items to an array. | `FixedArray::addFrom([1, 2, 3], $arr)` |
20-
| contains | Checks whether an item exists in a given array. | `FixedArray::contains('needle', $haystack)` |
21-
| count | Returns the number of items in a given array. | `FixedArray::count($array)` |
22-
| create | Creates a new fixed array. | `FixedArray::create(10)` |
23-
| first | Returns the first element of the array. | `FixedArray::first($array)` |
24-
| fromArray | Creates a new fixed array from a standard array. | `FixedArray::fromArray([1, 2, 3])` |
25-
| fromCollection | Creates a new fixed array from an Illuminate collection. | `FixedArray::fromCollection(collect([1, 2, 3])` |
26-
| getSize | Alias for count. | `FixedArray::getSize($array)` |
27-
| isFixedArray | Returns whether a given item is a fixed array. | `FixedArray::isFixedArray($potentialArray)` |
28-
| last | Returns the last element in an array. | `FixedArray::last($array)` |
29-
| merge | Merges given arrays, fixed arrays, or collections into a given fixed array. | `FixedArray::merge($array, $array2, $array3)` |
30-
| nullify | Overwrite all elements in an array with `null`. | `FixedArray::nullify($array)` |
31-
| offsetExists | Returns whether a given array offset exists. | `FixedArray::offsetExists(3, $haystack)` |
32-
| offsetGet | Retrieves the value at a given array offset. | `FixedArray::offsetGet(3, $haystack)` |
33-
| offsetNull | Replaces the value at a given array offset with `null`. | `FixedArray::offsetNull(3, $haystack)` |
34-
| offsetSet | Replaces the value at a given array offset with a provided value. | `FixedArray::offsetSet(3, $value, $haystack)` |
35-
| pop | Pops the latest value from the array. | `FixedArray::pop($array)` |
36-
| push | Pushes a given value to the first available space on the array. | `FixedArray::push($value, $array)` |
37-
| resize | Alias for setSize. | `FixedArray::resize(10, $array)` |
38-
| second | Returns the second value from the array. | `FixedArray::second($array)` |
39-
| setSize | Resizes the array to a given size. | `FixedArray::setSize(10, $array)` |
40-
| toArray | Converts a fixed array into a standard array. | `FixedArray::toArray($array)` |
41-
| toCollection | Converts a fixed array into an Illuminate collection. | `FixedArray::toCollection($array)` |
42-
43-
**NB:** Methods `current`, `key`, `next`, `rewind`, and `valid` are legacy alias operations for pointer-based array
44-
methods and simply return `null` currently. They will be implemented in a future version.
12+
While they require manual resizing, they're significantly faster than regular arrays or collections when working with
13+
large sets of data.
4514

4615
## Requirements
4716
Currently, requires PHP 8 or above, but work to backport support for 7.4 is in progress. This package is designed
@@ -55,10 +24,40 @@ You can install the package via Composer:
5524
composer require petrobolos/fixed-array-functions
5625
```
5726

58-
## Usage
27+
## Fluent interface
28+
FixedArray is best used with its fluent interface. If you're familiar with Illuminate collections, you'll feel right at
29+
home. Provide it an SplFixedArray to get started, or a standard array or collection that will be automatically
30+
converted. If you provide any other kind of data, including `null`, it will be inserted into a new SplFixedArray.
5931

60-
A fluent interface is planned for a future release - for now, `FixedArray` is available to be imported and used
61-
anywhere in your code, as its functions are static.
32+
```php
33+
use Petrobolos\FixedArray\FixedArrayable;
34+
35+
// You can start by either instantiating a new instance of FixedArrayable, or by calling its helper method:
36+
// The array provided will be converted internally into an SplFixedArray.
37+
$array = new FixedArrayable([1, 2, 3]);
38+
39+
// You can also use the helper function to do the same thing!
40+
$array = fixedArray([1, 2, 3]);
41+
42+
// Lastly, you can use specific methods to begin building your interface logic:
43+
// The same will happen with this collection.
44+
$array = FixedArrayable::fromCollection(collect([1, 2, 3]);
45+
46+
// From here, you can chain different methods, just like you would a collection.
47+
$result = $array
48+
->addFrom([4, 5, 6])
49+
->resize(20)
50+
->filter(fn ($value) => $value % 2 === 0))
51+
->map(fn ($value) => $value * 2))
52+
->get();
53+
54+
// The result will be a SplFixedArray containing [2, 4, 6] but still with 20 indices.
55+
```
56+
57+
## Static methods:
58+
59+
You aren't forced to use the fluent interface and can access methods directly by calling them. This is useful if you
60+
only need to do one or two operations on a fixed array.
6261

6362
```php
6463
use Petrobolos\FixedArray;
@@ -77,6 +76,41 @@ $everything = FixedArray::merge(
7776
);
7877
```
7978

79+
## Full list of working methods:
80+
81+
| Method | Description | Example |
82+
|:---------------|:----------------------------------------------------------------------------|--------------------------------------------------------------:|
83+
| add | Alias for push. | `FixedArray::add('bacon', $arr)` |
84+
| addFrom | Add an array or collection of items to an array. | `FixedArray::addFrom([1, 2, 3], $arr)` |
85+
| contains | Checks whether an item exists in a given array. | `FixedArray::contains('needle', $haystack)` |
86+
| count | Returns the number of items in a given array. | `FixedArray::count($array)` |
87+
| create | Creates a new fixed array. | `FixedArray::create(10)` |
88+
| each | Apply a callback to each item in the array without modifying the original. | `FixedArray::each($array, fn () => var_dump($value))` |
89+
| filter | Applies a filter to a given fixed array. | `FixedArray::filter($array, fn ($value) => $value % 2 === 0)` |
90+
| first | Returns the first element of the array. | `FixedArray::first($array)` |
91+
| fromArray | Creates a new fixed array from a standard array. | `FixedArray::fromArray([1, 2, 3])` |
92+
| fromCollection | Creates a new fixed array from an Illuminate collection. | `FixedArray::fromCollection(collect([1, 2, 3])` |
93+
| getSize | Alias for count. | `FixedArray::getSize($array)` |
94+
| isFixedArray | Returns whether a given item is a fixed array. | `FixedArray::isFixedArray($potentialArray)` |
95+
| last | Returns the last element in an array. | `FixedArray::last($array)` |
96+
| map | Applies a callback to each item in the array and returns it. | `FixedArray::map($array, fn ($value) => (string) $value)` |
97+
| merge | Merges given arrays, fixed arrays, or collections into a given fixed array. | `FixedArray::merge($array, $array2, $array3)` |
98+
| nullify | Overwrite all elements in an array with `null`. | `FixedArray::nullify($array)` |
99+
| offsetExists | Returns whether a given array offset exists. | `FixedArray::offsetExists(3, $haystack)` |
100+
| offsetGet | Retrieves the value at a given array offset. | `FixedArray::offsetGet(3, $haystack)` |
101+
| offsetNull | Replaces the value at a given array offset with `null`. | `FixedArray::offsetNull(3, $haystack)` |
102+
| offsetSet | Replaces the value at a given array offset with a provided value. | `FixedArray::offsetSet(3, $value, $haystack)` |
103+
| pop | Pops the latest value from the array. | `FixedArray::pop($array)` |
104+
| push | Pushes a given value to the first available space on the array. | `FixedArray::push($value, $array)` |
105+
| resize | Alias for setSize. | `FixedArray::resize(10, $array)` |
106+
| second | Returns the second value from the array. | `FixedArray::second($array)` |
107+
| setSize | Resizes the array to a given size. | `FixedArray::setSize(10, $array)` |
108+
| toArray | Converts a fixed array into a standard array. | `FixedArray::toArray($array)` |
109+
| toCollection | Converts a fixed array into an Illuminate collection. | `FixedArray::toCollection($array)` |
110+
111+
**NB:** Methods `current`, `key`, `next`, `rewind`, and `valid` are legacy alias operations for pointer-based array
112+
methods and simply return `null` currently. They will be implemented in a future version.
113+
80114
## Testing
81115

82116
Tests are run using Pest. You can run the suite like so:
@@ -91,7 +125,10 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re
91125

92126
## Contributing
93127

94-
We welcome pull requests! Please ensure any functionality submitted has adequate test coverage.
128+
We welcome pull requests, especially those improving the package's optimisation and speed, and new
129+
features to bring it into parity with Collection.
130+
131+
Please ensure any functionality submitted has adequate test coverage and documentation (at least in English.)
95132

96133
## License
97134

0 commit comments

Comments
 (0)