You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
298 lines
8.9 KiB
298 lines
8.9 KiB
14 years ago
|
<?php
|
||
|
/**
|
||
|
* @link http://www.yiiframework.com/
|
||
12 years ago
|
* @copyright Copyright (c) 2008 Yii Software LLC
|
||
14 years ago
|
* @license http://www.yiiframework.com/license/
|
||
|
*/
|
||
|
|
||
14 years ago
|
namespace yii\base;
|
||
|
|
||
12 years ago
|
use yii\helpers\ArrayHelper;
|
||
13 years ago
|
|
||
14 years ago
|
/**
|
||
14 years ago
|
* Dictionary implements a collection that stores key-value pairs.
|
||
14 years ago
|
*
|
||
|
* You can access, add or remove an item with a key by using
|
||
13 years ago
|
* [[itemAt()]], [[add()]], and [[remove()]].
|
||
14 years ago
|
*
|
||
13 years ago
|
* To get the number of the items in the dictionary, use [[getCount()]].
|
||
14 years ago
|
*
|
||
|
* Because Dictionary implements a set of SPL interfaces, it can be used
|
||
|
* like a regular PHP array as follows,
|
||
|
*
|
||
14 years ago
|
* ~~~
|
||
13 years ago
|
* $dictionary[$key] = $value; // add a key-value pair
|
||
|
* unset($dictionary[$key]); // remove the value with the specified key
|
||
|
* if (isset($dictionary[$key])) // if the dictionary contains the key
|
||
14 years ago
|
* foreach ($dictionary as $key=>$value) // traverse the items in the dictionary
|
||
13 years ago
|
* $n = count($dictionary); // returns the number of items in the dictionary
|
||
14 years ago
|
* ~~~
|
||
14 years ago
|
*
|
||
13 years ago
|
* @property integer $count the number of items in the dictionary
|
||
13 years ago
|
* @property array $keys The keys in the dictionary
|
||
13 years ago
|
*
|
||
14 years ago
|
* @author Qiang Xue <qiang.xue@gmail.com>
|
||
14 years ago
|
* @since 2.0
|
||
14 years ago
|
*/
|
||
13 years ago
|
class Dictionary extends Object implements \IteratorAggregate, \ArrayAccess, \Countable
|
||
14 years ago
|
{
|
||
|
/**
|
||
14 years ago
|
* @var array internal data storage
|
||
14 years ago
|
*/
|
||
14 years ago
|
private $_d = array();
|
||
14 years ago
|
|
||
|
/**
|
||
|
* Constructor.
|
||
14 years ago
|
* Initializes the dictionary with an array or an iterable object.
|
||
|
* @param mixed $data the initial data to be populated into the dictionary.
|
||
|
* This can be an array or an iterable object.
|
||
13 years ago
|
* @param array $config name-value pairs that will be used to initialize the object properties
|
||
14 years ago
|
* @throws Exception if data is not well formed (neither an array nor an iterable object)
|
||
14 years ago
|
*/
|
||
13 years ago
|
public function __construct($data = array(), $config = array())
|
||
14 years ago
|
{
|
||
12 years ago
|
if (!empty($data)) {
|
||
14 years ago
|
$this->copyFrom($data);
|
||
14 years ago
|
}
|
||
13 years ago
|
parent::__construct($config);
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Returns an iterator for traversing the items in the dictionary.
|
||
|
* This method is required by the SPL interface `IteratorAggregate`.
|
||
|
* It will be implicitly called when you use `foreach` to traverse the dictionary.
|
||
|
* @return DictionaryIterator an iterator for traversing the items in the dictionary.
|
||
14 years ago
|
*/
|
||
|
public function getIterator()
|
||
|
{
|
||
14 years ago
|
return new DictionaryIterator($this->_d);
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Returns the number of items in the dictionary.
|
||
|
* This method is required by the SPL `Countable` interface.
|
||
|
* It will be implicitly called when you use `count($dictionary)`.
|
||
|
* @return integer number of items in the dictionary.
|
||
14 years ago
|
*/
|
||
|
public function count()
|
||
|
{
|
||
|
return $this->getCount();
|
||
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Returns the number of items in the dictionary.
|
||
|
* @return integer the number of items in the dictionary
|
||
14 years ago
|
*/
|
||
|
public function getCount()
|
||
|
{
|
||
|
return count($this->_d);
|
||
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Returns the keys stored in the dictionary.
|
||
14 years ago
|
* @return array the key list
|
||
|
*/
|
||
|
public function getKeys()
|
||
|
{
|
||
|
return array_keys($this->_d);
|
||
|
}
|
||
|
|
||
|
/**
|
||
|
* Returns the item with the specified key.
|
||
|
* @param mixed $key the key
|
||
14 years ago
|
* @return mixed the element with the specified key.
|
||
|
* Null if the key cannot be found in the dictionary.
|
||
14 years ago
|
*/
|
||
|
public function itemAt($key)
|
||
|
{
|
||
14 years ago
|
return isset($this->_d[$key]) ? $this->_d[$key] : null;
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Adds an item into the dictionary.
|
||
14 years ago
|
* Note, if the specified key already exists, the old value will be overwritten.
|
||
|
* @param mixed $key key
|
||
|
* @param mixed $value value
|
||
14 years ago
|
* @throws Exception if the dictionary is read-only
|
||
14 years ago
|
*/
|
||
14 years ago
|
public function add($key, $value)
|
||
14 years ago
|
{
|
||
14 years ago
|
if ($key === null) {
|
||
|
$this->_d[] = $value;
|
||
13 years ago
|
} else {
|
||
14 years ago
|
$this->_d[$key] = $value;
|
||
14 years ago
|
}
|
||
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Removes an item from the dictionary by its key.
|
||
14 years ago
|
* @param mixed $key the key of the item to be removed
|
||
|
* @return mixed the removed value, null if no such key exists.
|
||
14 years ago
|
* @throws Exception if the dictionary is read-only
|
||
14 years ago
|
*/
|
||
|
public function remove($key)
|
||
|
{
|
||
14 years ago
|
if (isset($this->_d[$key])) {
|
||
|
$value = $this->_d[$key];
|
||
|
unset($this->_d[$key]);
|
||
|
return $value;
|
||
13 years ago
|
} else { // the value is null
|
||
14 years ago
|
unset($this->_d[$key]);
|
||
|
return null;
|
||
14 years ago
|
}
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
13 years ago
|
* Removes all items from the dictionary.
|
||
|
* @param boolean $safeClear whether to clear every item by calling [[remove]].
|
||
|
* Defaults to false, meaning all items in the dictionary will be cleared directly
|
||
|
* without calling [[remove]].
|
||
14 years ago
|
*/
|
||
12 years ago
|
public function removeAll($safeClear = false)
|
||
14 years ago
|
{
|
||
13 years ago
|
if ($safeClear) {
|
||
|
foreach (array_keys($this->_d) as $key) {
|
||
|
$this->remove($key);
|
||
|
}
|
||
13 years ago
|
} else {
|
||
13 years ago
|
$this->_d = array();
|
||
14 years ago
|
}
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Returns a value indicating whether the dictionary contains the specified key.
|
||
14 years ago
|
* @param mixed $key the key
|
||
14 years ago
|
* @return boolean whether the dictionary contains an item with the specified key
|
||
14 years ago
|
*/
|
||
12 years ago
|
public function has($key)
|
||
14 years ago
|
{
|
||
14 years ago
|
return isset($this->_d[$key]) || array_key_exists($key, $this->_d);
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Returns the dictionary as a PHP array.
|
||
14 years ago
|
* @return array the list of items in array
|
||
|
*/
|
||
|
public function toArray()
|
||
|
{
|
||
|
return $this->_d;
|
||
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Copies iterable data into the dictionary.
|
||
|
* Note, existing data in the dictionary will be cleared first.
|
||
|
* @param mixed $data the data to be copied from, must be an array or an object implementing `Traversable`
|
||
12 years ago
|
* @throws InvalidParamException if data is neither an array nor an iterator.
|
||
14 years ago
|
*/
|
||
13 years ago
|
public function copyFrom($data)
|
||
14 years ago
|
{
|
||
13 years ago
|
if (is_array($data) || $data instanceof \Traversable) {
|
||
12 years ago
|
if (!empty($this->_d)) {
|
||
12 years ago
|
$this->removeAll();
|
||
14 years ago
|
}
|
||
|
if ($data instanceof self) {
|
||
|
$data = $data->_d;
|
||
|
}
|
||
|
foreach ($data as $key => $value) {
|
||
|
$this->add($key, $value);
|
||
|
}
|
||
13 years ago
|
} else {
|
||
12 years ago
|
throw new InvalidParamException('Data must be either an array or an object implementing Traversable.');
|
||
14 years ago
|
}
|
||
|
}
|
||
|
|
||
|
/**
|
||
14 years ago
|
* Merges iterable data into the dictionary.
|
||
14 years ago
|
*
|
||
14 years ago
|
* Existing elements in the dictionary will be overwritten if their keys are the same as those in the source.
|
||
14 years ago
|
* If the merge is recursive, the following algorithm is performed:
|
||
|
*
|
||
13 years ago
|
* - the dictionary data is saved as $a, and the source data is saved as $b;
|
||
|
* - if $a and $b both have an array indexed at the same string key, the arrays will be merged using this algorithm;
|
||
|
* - any integer-indexed elements in $b will be appended to $a;
|
||
|
* - any string-indexed elements in $b will overwrite elements in $a with the same index;
|
||
14 years ago
|
*
|
||
13 years ago
|
* @param array|\Traversable $data the data to be merged with. It must be an array or object implementing Traversable
|
||
|
* @param boolean $recursive whether the merging should be recursive.
|
||
12 years ago
|
* @throws InvalidParamException if data is neither an array nor an object implementing `Traversable`.
|
||
14 years ago
|
*/
|
||
13 years ago
|
public function mergeWith($data, $recursive = true)
|
||
14 years ago
|
{
|
||
14 years ago
|
if (is_array($data) || $data instanceof \Traversable) {
|
||
|
if ($data instanceof self) {
|
||
|
$data = $data->_d;
|
||
|
}
|
||
|
if ($recursive) {
|
||
|
if ($data instanceof \Traversable) {
|
||
13 years ago
|
$d = array();
|
||
|
foreach ($data as $key => $value) {
|
||
14 years ago
|
$d[$key] = $value;
|
||
|
}
|
||
13 years ago
|
$this->_d = ArrayHelper::merge($this->_d, $d);
|
||
13 years ago
|
} else {
|
||
13 years ago
|
$this->_d = ArrayHelper::merge($this->_d, $data);
|
||
14 years ago
|
}
|
||
13 years ago
|
} else {
|
||
13 years ago
|
foreach ($data as $key => $value) {
|
||
14 years ago
|
$this->add($key, $value);
|
||
|
}
|
||
14 years ago
|
}
|
||
13 years ago
|
} else {
|
||
12 years ago
|
throw new InvalidParamException('The data to be merged with must be an array or an object implementing Traversable.');
|
||
14 years ago
|
}
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
|
* Returns whether there is an element at the specified offset.
|
||
14 years ago
|
* This method is required by the SPL interface `ArrayAccess`.
|
||
14 years ago
|
* It is implicitly called when you use something like `isset($dictionary[$offset])`.
|
||
14 years ago
|
* This is equivalent to [[contains]].
|
||
14 years ago
|
* @param mixed $offset the offset to check on
|
||
|
* @return boolean
|
||
|
*/
|
||
|
public function offsetExists($offset)
|
||
|
{
|
||
12 years ago
|
return $this->has($offset);
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
|
* Returns the element at the specified offset.
|
||
14 years ago
|
* This method is required by the SPL interface `ArrayAccess`.
|
||
14 years ago
|
* It is implicitly called when you use something like `$value = $dictionary[$offset];`.
|
||
14 years ago
|
* This is equivalent to [[itemAt]].
|
||
14 years ago
|
* @param mixed $offset the offset to retrieve element.
|
||
14 years ago
|
* @return mixed the element at the offset, null if no element is found at the offset
|
||
|
*/
|
||
|
public function offsetGet($offset)
|
||
|
{
|
||
|
return $this->itemAt($offset);
|
||
|
}
|
||
|
|
||
|
/**
|
||
|
* Sets the element at the specified offset.
|
||
14 years ago
|
* This method is required by the SPL interface `ArrayAccess`.
|
||
14 years ago
|
* It is implicitly called when you use something like `$dictionary[$offset] = $item;`.
|
||
14 years ago
|
* If the offset is null, the new item will be appended to the dictionary.
|
||
|
* Otherwise, the existing item at the offset will be replaced with the new item.
|
||
|
* This is equivalent to [[add]].
|
||
|
* @param mixed $offset the offset to set element
|
||
14 years ago
|
* @param mixed $item the element value
|
||
|
*/
|
||
14 years ago
|
public function offsetSet($offset, $item)
|
||
14 years ago
|
{
|
||
13 years ago
|
$this->add($offset, $item);
|
||
14 years ago
|
}
|
||
|
|
||
|
/**
|
||
|
* Unsets the element at the specified offset.
|
||
14 years ago
|
* This method is required by the SPL interface `ArrayAccess`.
|
||
14 years ago
|
* It is implicitly called when you use something like `unset($dictionary[$offset])`.
|
||
14 years ago
|
* This is equivalent to [[remove]].
|
||
14 years ago
|
* @param mixed $offset the offset to unset element
|
||
|
*/
|
||
|
public function offsetUnset($offset)
|
||
|
{
|
||
|
$this->remove($offset);
|
||
|
}
|
||
|
}
|