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/