Dictionary

A Dictionary is a basic container to store key/value pairs. It implements Countable, IteratorAggregate and ArrayAccess to use it like a normal array. Like all collection classes it returns itself on every manipulating method to allow fluid syntax.

Adding key/value pairs

In addition to php array syntax $dict[$key] = $value a Dictionary has a set() $method to allow fluid syntax.

use Collection\Dictionary;

$dict = new Dictionary;
$dict->set('sally'=>32);
// Result: Dictionary['sally'=>32]
$dict->set('harry',25)->set('joe',33);
// Result: Dictionary['sally'=>32,'harry'=>25,'joe'=>33]

Adding key/value if not exist

This is a typical combination of accessing the Dictionary. Use $dict->setDefault($key, $default) to set the value if it does not exist and return it. If it does exist just return that value and ignore the passed default value.

Getting value by key

In addition to php array syntax $dict[$key] a Dictionary has a get() method. While the array syntax (offsetGet) will throw an exception if the value does not exist, get() will not. Additionally the get() method has a second parameter to return a value if the key does not exist.

use Collection\Dictionary;

$dict = new Dictionary(['foo'=>32,'bar'=>55]);
$dict->get('foo');
// Return value: 32
$dict->get('baz');
// Return value: null
$dict->get('baz', 88);
// Return value: 88
$dict['foo'];
// Return value: 32
$dict['baz'];
// Throws OutOfBoundsException

Setting values be reference

If you like to pass a value by reference use setRef($value).

Check if a key is set

To check if a key exists use hasKey($key) or isset($dict[$key]). In opposite to the original array implementation in php a key is also set if the value is NULL.

Check if key is set and is true(-like)

To check if a Dictionary 'has something' use the has() method. This is a shortcut for isset($dict[$key]) && dict[key] to reduce redundant code.

use Collection\Dictionary;

$dict = new Dictionary(['foo'=>32,'bar'=>55,'baz'=>false]);
$dict->has('foo'); // true
$dict->has('baz'); // false
$dict->has('fi'); // false

Retrieve keys, items and values

To retrieve the keys or values use $dict->keys(), $dict->values(). This will return a OrderedList of all key/items.

Remove an item by key

Additional to the php array syntax unset($dict[$key]) Dictionary provides a pop($key) method. The pop method will remove and return the item by key. If the key does not exist an exception will be thrown. A second parameter allows to pass a default value which will be return if the key does not exist.

use Collection\Dictionary;

$dict = new Dictionary(['foo'=>32,'bar'=>55,'baz'=>false]);
$dict->pop('foo');
// Return value: 32, ['bar'=>55,'baz'=>false]
$dict->pop('boo');
// Throws OutOfBoundsException
$dict->pop('boo',true);
// Return value: true

Clear the Dictionary

To empty the Dictionary use $dict->clear()

Merge 2 Dictionaries

To merge two dictionaries use the update method.

use Collection\Dictionary;

$dict = new Dictionary(['foo'=>32,'bar'=>55,'baz'=>false]);
$dict2 = new Dictionary(['boo'=>34,'bar'=>32,'bee'=>1]);

$dict->update($dict2);
// $dict is now: Dictionary['foo'=>32,'bar'=>32,'baz'=>false,'boo'=>34,'bee'=>1]

Fluid syntax and batch operations

All manipulating methods will alter the dictionary. If you like to return new objects use the copy() method. (Or clone $dict).

use Collection\Dictionary;

$dict = new Dictionary(['foo'=>32,'bar'=>55,'baz'=>false]);
$dict2 = $dict->copy()->set('boo','bee')->pop('foo');
// $dict2 will be Dictionary['bar'=>55,'baz'=>false,'boo'=>'bee']
// $dict will be untouched

Shortcut to copy and remove keys

To have a copy with one key removed use the without() method.

use Collection\Dictionary;

$dict = new Dictionary(['foo'=>32,'bar'=>55,'baz'=>false]);
$dict2 = $dict->without('bar');
// $dict2 will be Dictionary['foo'=>32,'baz'=>false]
// $dict will be untouched