153 lines
4.0 KiB
ReStructuredText
153 lines
4.0 KiB
ReStructuredText
PHP Collection
|
|
==============
|
|
This library adds basic collections for PHP.
|
|
|
|
Collections can be seen as more specialized arrays for which certain contracts are guaranteed.
|
|
|
|
Supported Collections:
|
|
|
|
- Sequences
|
|
|
|
- Keys: numerical, consequentially increasing, no gaps
|
|
- Values: anything, duplicates allowed
|
|
- Classes: ``Sequence``, ``SortedSequence``
|
|
|
|
|
|
- Maps
|
|
|
|
- Keys: strings or objects, duplicate keys not allowed
|
|
- Values: anything, duplicates allowed
|
|
- Classes: ``Map``, ``ObjectMap`` (not yet implemented)
|
|
|
|
|
|
- Sets
|
|
|
|
- Keys: not meaningful
|
|
- Values: objects, or scalars, each value is guaranteed to be unique (see Set usage below for details)
|
|
- Classes: ``Set``
|
|
|
|
General Characteristics:
|
|
|
|
- Collections are mutable (new elements may be added, existing elements may be modified or removed). Specialized
|
|
immutable versions may be added in the future though.
|
|
- Equality comparison between elements are always performed using the shallow comparison operator (===).
|
|
- Sorting algorithms are unstable, that means the order for equal elements is undefined (the default, and only PHP behavior).
|
|
|
|
|
|
Installation
|
|
------------
|
|
PHP Collection can easily be installed via composer
|
|
|
|
.. code-block :: bash
|
|
|
|
composer require phpcollection/phpcollection
|
|
|
|
or add it to your ``composer.json`` file.
|
|
|
|
Usage
|
|
-----
|
|
Collection classes provide a rich API.
|
|
|
|
Sets
|
|
~~~~
|
|
In a Set each value is guaranteed to be unique. The ``Set`` class supports objects, and scalars as value. Equality
|
|
is determined via the following steps.
|
|
|
|
**Equality of Objects**
|
|
|
|
1. If an object implements ``ObjectBasics``, equality is determined by the ``equals()`` method.
|
|
2. If an object has an external handler like the ``DateTime`` that was registered via ``ObjectBasicsHandlerRegistry::registerHandlerFor``,
|
|
equality is determined by that handler's ``equals()`` method.
|
|
3. If none of the above is applicable, equality is determined by identity ``$a === $b``.
|
|
|
|
**Equality of Scalars**
|
|
|
|
Scalar are considered equal if ``$a === $b`` is true.
|
|
|
|
|
|
.. code-block :: php
|
|
|
|
$set = new Set();
|
|
$set->add(new \DateTime('today'));
|
|
$set->add(new \DateTime('today'));
|
|
|
|
var_dump(count($set)); // int(1) -> the same date is not added twice
|
|
|
|
foreach ($set as $date) {
|
|
var_dump($date);
|
|
}
|
|
|
|
$set->all();
|
|
$set->addSet($otherSet);
|
|
$set->addAll($someElements);
|
|
|
|
|
|
Sequences
|
|
~~~~~~~~~
|
|
|
|
.. code-block :: php
|
|
|
|
// Read Operations
|
|
$seq = new Sequence([0, 2, 3, 2]);
|
|
$seq->get(2); // int(3)
|
|
$seq->all(); // [0, 2, 3, 2]
|
|
|
|
$seq->first(); // Some(0)
|
|
$seq->last(); // Some(2)
|
|
|
|
// Write Operations
|
|
$seq = new Sequence([1, 5]);
|
|
$seq->get(0); // int(1)
|
|
$seq->update(0, 4);
|
|
$seq->get(0); // int(4)
|
|
$seq->remove(0);
|
|
$seq->get(0); // int(5)
|
|
|
|
$seq = new Sequence([1, 4]);
|
|
$seq->add(2);
|
|
$seq->all(); // [1, 4, 2]
|
|
$seq->addAll(array(4, 5, 2));
|
|
$seq->all(); // [1, 4, 2, 4, 5, 2]
|
|
|
|
// Sort
|
|
$seq = new Sequence([0, 5, 4, 2]);
|
|
$seq->sortWith(function($a, $b) { return $a - $b; });
|
|
$seq->all(); // [0, 2, 4, 5]
|
|
|
|
Maps
|
|
~~~~
|
|
|
|
.. code-block :: php
|
|
|
|
// Read Operations
|
|
$map = new Map(['foo' => 'bar', 'baz' => 'boo']);
|
|
$map->get('foo'); // Some('bar')
|
|
$map->get('foo')->get(); // string('bar')
|
|
$map->keys(); // ['foo', 'baz']
|
|
$map->values(); // ['bar', 'boo']
|
|
iterator_to_array($map); // ['foo' => 'bar', 'baz' => 'boo']
|
|
|
|
$map->first()->get(); // ['foo', 'bar']
|
|
$map->last()->get(); // ['baz', 'boo']
|
|
|
|
// Write Operations
|
|
$map = new Map();
|
|
$map->set('foo', 'bar');
|
|
$map->setAll(array('bar' => 'baz', 'baz' => 'boo'));
|
|
$map->remove('foo');
|
|
|
|
// Sort
|
|
$map->sortWith('strcmp');
|
|
|
|
License
|
|
-------
|
|
|
|
The code is released under the business-friendly `Apache2 license`_.
|
|
|
|
Documentation is subject to the `Attribution-NonCommercial-NoDerivs 3.0 Unported
|
|
license`_.
|
|
|
|
.. _Apache2 license: http://www.apache.org/licenses/LICENSE-2.0.html
|
|
.. _Attribution-NonCommercial-NoDerivs 3.0 Unported license: http://creativecommons.org/licenses/by-nc-nd/3.0/
|
|
|