Dictionary.php 8.86 KB
Newer Older
w  
Qiang Xue committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
w  
Qiang Xue committed
5 6 7
 * @license http://www.yiiframework.com/license/
 */

Qiang Xue committed
8 9
namespace yii\base;

Qiang Xue committed
10
use yii\helpers\ArrayHelper;
Qiang Xue committed
11

w  
Qiang Xue committed
12
/**
Qiang Xue committed
13
 * Dictionary implements a collection that stores key-value pairs.
w  
Qiang Xue committed
14 15
 *
 * You can access, add or remove an item with a key by using
Qiang Xue committed
16
 * [[itemAt()]], [[add()]], and [[remove()]].
Qiang Xue committed
17
 *
Qiang Xue committed
18
 * To get the number of the items in the dictionary, use [[getCount()]].
Qiang Xue committed
19 20 21 22
 *
 * Because Dictionary implements a set of SPL interfaces, it can be used
 * like a regular PHP array as follows,
 *
w  
Qiang Xue committed
23
 * ~~~
Qiang Xue committed
24 25 26
 * $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
Qiang Xue committed
27
 * foreach ($dictionary as $key=>$value) // traverse the items in the dictionary
Qiang Xue committed
28
 * $n = count($dictionary);			  // returns the number of items in the dictionary
Qiang Xue committed
29
 * ~~~
w  
Qiang Xue committed
30
 *
Qiang Xue committed
31
 * @property integer $count the number of items in the dictionary
Qiang Xue committed
32
 * @property array $keys The keys in the dictionary
Qiang Xue committed
33
 *
w  
Qiang Xue committed
34
 * @author Qiang Xue <qiang.xue@gmail.com>
Qiang Xue committed
35
 * @since 2.0
w  
Qiang Xue committed
36
 */
37
class Dictionary extends Object implements \IteratorAggregate, \ArrayAccess, \Countable
w  
Qiang Xue committed
38 39
{
	/**
Qiang Xue committed
40
	 * @var array internal data storage
w  
Qiang Xue committed
41
	 */
Qiang Xue committed
42
	private $_d = array();
w  
Qiang Xue committed
43 44 45

	/**
	 * Constructor.
Qiang Xue committed
46 47 48
	 * 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.
Qiang Xue committed
49
	 * @param array $config name-value pairs that will be used to initialize the object properties
Qiang Xue committed
50
	 * @throws Exception if data is not well formed (neither an array nor an iterable object)
w  
Qiang Xue committed
51
	 */
Qiang Xue committed
52
	public function __construct($data = array(), $config = array())
w  
Qiang Xue committed
53
	{
Qiang Xue committed
54
		if ($data !== array()) {
w  
Qiang Xue committed
55
			$this->copyFrom($data);
Qiang Xue committed
56
		}
Qiang Xue committed
57
		parent::__construct($config);
w  
Qiang Xue committed
58 59 60
	}

	/**
Qiang Xue committed
61 62 63 64
	 * 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.
w  
Qiang Xue committed
65 66 67
	 */
	public function getIterator()
	{
Qiang Xue committed
68
		return new DictionaryIterator($this->_d);
w  
Qiang Xue committed
69 70 71
	}

	/**
Qiang Xue committed
72 73 74 75
	 * 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.
w  
Qiang Xue committed
76 77 78 79 80 81 82
	 */
	public function count()
	{
		return $this->getCount();
	}

	/**
Qiang Xue committed
83 84
	 * Returns the number of items in the dictionary.
	 * @return integer the number of items in the dictionary
w  
Qiang Xue committed
85 86 87 88 89 90 91
	 */
	public function getCount()
	{
		return count($this->_d);
	}

	/**
Qiang Xue committed
92
	 * Returns the keys stored in the dictionary.
w  
Qiang Xue committed
93 94 95 96 97 98 99 100 101 102
	 * @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
Qiang Xue committed
103 104
	 * @return mixed the element with the specified key.
	 * Null if the key cannot be found in the dictionary.
w  
Qiang Xue committed
105 106 107
	 */
	public function itemAt($key)
	{
Qiang Xue committed
108
		return isset($this->_d[$key]) ? $this->_d[$key] : null;
w  
Qiang Xue committed
109 110 111
	}

	/**
Qiang Xue committed
112
	 * Adds an item into the dictionary.
w  
Qiang Xue committed
113 114 115
	 * Note, if the specified key already exists, the old value will be overwritten.
	 * @param mixed $key key
	 * @param mixed $value value
Qiang Xue committed
116
	 * @throws Exception if the dictionary is read-only
w  
Qiang Xue committed
117
	 */
Qiang Xue committed
118
	public function add($key, $value)
w  
Qiang Xue committed
119
	{
w  
Qiang Xue committed
120 121
		if ($key === null) {
			$this->_d[] = $value;
Qiang Xue committed
122
		} else {
w  
Qiang Xue committed
123
			$this->_d[$key] = $value;
w  
Qiang Xue committed
124 125 126 127
		}
	}

	/**
Qiang Xue committed
128
	 * Removes an item from the dictionary by its key.
w  
Qiang Xue committed
129 130
	 * @param mixed $key the key of the item to be removed
	 * @return mixed the removed value, null if no such key exists.
Qiang Xue committed
131
	 * @throws Exception if the dictionary is read-only
w  
Qiang Xue committed
132 133 134
	 */
	public function remove($key)
	{
w  
Qiang Xue committed
135 136 137 138
		if (isset($this->_d[$key])) {
			$value = $this->_d[$key];
			unset($this->_d[$key]);
			return $value;
Qiang Xue committed
139
		} else { // the value is null
w  
Qiang Xue committed
140 141
			unset($this->_d[$key]);
			return null;
Qiang Xue committed
142
		}
w  
Qiang Xue committed
143 144 145
	}

	/**
146 147 148 149
	 * 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]].
w  
Qiang Xue committed
150
	 */
Qiang Xue committed
151
	public function removeAll($safeClear = false)
w  
Qiang Xue committed
152
	{
153 154 155 156
		if ($safeClear) {
			foreach (array_keys($this->_d) as $key) {
				$this->remove($key);
			}
Qiang Xue committed
157
		} else {
158
			$this->_d = array();
Qiang Xue committed
159
		}
w  
Qiang Xue committed
160 161 162
	}

	/**
Qiang Xue committed
163
	 * Returns a value indicating whether the dictionary contains the specified key.
w  
Qiang Xue committed
164
	 * @param mixed $key the key
Qiang Xue committed
165
	 * @return boolean whether the dictionary contains an item with the specified key
w  
Qiang Xue committed
166
	 */
Qiang Xue committed
167
	public function has($key)
w  
Qiang Xue committed
168
	{
Qiang Xue committed
169
		return isset($this->_d[$key]) || array_key_exists($key, $this->_d);
w  
Qiang Xue committed
170 171 172
	}

	/**
Qiang Xue committed
173
	 * Returns the dictionary as a PHP array.
w  
Qiang Xue committed
174 175 176 177 178 179 180 181
	 * @return array the list of items in array
	 */
	public function toArray()
	{
		return $this->_d;
	}

	/**
Qiang Xue committed
182 183 184
	 * 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`
Qiang Xue committed
185
	 * @throws InvalidParamException if data is neither an array nor an iterator.
w  
Qiang Xue committed
186
	 */
Qiang Xue committed
187
	public function copyFrom($data)
w  
Qiang Xue committed
188
	{
Qiang Xue committed
189
		if (is_array($data) || $data instanceof \Traversable) {
190
			if ($this->_d !== array()) {
Qiang Xue committed
191
				$this->removeAll();
Qiang Xue committed
192 193 194 195 196 197 198
			}
			if ($data instanceof self) {
				$data = $data->_d;
			}
			foreach ($data as $key => $value) {
				$this->add($key, $value);
			}
Qiang Xue committed
199
		} else {
Qiang Xue committed
200
			throw new InvalidParamException('Data must be either an array or an object implementing Traversable.');
w  
Qiang Xue committed
201 202 203 204
		}
	}

	/**
Qiang Xue committed
205
	 * Merges iterable data into the dictionary.
w  
Qiang Xue committed
206
	 *
Qiang Xue committed
207
	 * Existing elements in the dictionary will be overwritten if their keys are the same as those in the source.
w  
Qiang Xue committed
208 209
	 * If the merge is recursive, the following algorithm is performed:
	 *
Qiang Xue committed
210 211 212 213
	 * - 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;
w  
Qiang Xue committed
214
	 *
Qiang Xue committed
215 216
	 * @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.
Qiang Xue committed
217
	 * @throws InvalidParamException if data is neither an array nor an object implementing `Traversable`.
w  
Qiang Xue committed
218
	 */
Qiang Xue committed
219
	public function mergeWith($data, $recursive = true)
w  
Qiang Xue committed
220
	{
221 222 223 224 225 226
		if (is_array($data) || $data instanceof \Traversable) {
			if ($data instanceof self) {
				$data = $data->_d;
			}
			if ($recursive) {
				if ($data instanceof \Traversable) {
Qiang Xue committed
227 228
					$d = array();
					foreach ($data as $key => $value) {
229 230
						$d[$key] = $value;
					}
Qiang Xue committed
231
					$this->_d = ArrayHelper::merge($this->_d, $d);
Qiang Xue committed
232
				} else {
Qiang Xue committed
233
					$this->_d = ArrayHelper::merge($this->_d, $data);
w  
Qiang Xue committed
234
				}
Qiang Xue committed
235
			} else {
Qiang Xue committed
236
				foreach ($data as $key => $value) {
237 238
					$this->add($key, $value);
				}
w  
Qiang Xue committed
239
			}
Qiang Xue committed
240
		} else {
Qiang Xue committed
241
			throw new InvalidParamException('The data to be merged with must be an array or an object implementing Traversable.');
242
		}
w  
Qiang Xue committed
243 244 245 246
	}

	/**
	 * Returns whether there is an element at the specified offset.
Qiang Xue committed
247
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
248
	 * It is implicitly called when you use something like `isset($dictionary[$offset])`.
Qiang Xue committed
249
	 * This is equivalent to [[contains]].
w  
Qiang Xue committed
250 251 252 253 254
	 * @param mixed $offset the offset to check on
	 * @return boolean
	 */
	public function offsetExists($offset)
	{
Qiang Xue committed
255
		return $this->has($offset);
w  
Qiang Xue committed
256 257 258 259
	}

	/**
	 * Returns the element at the specified offset.
Qiang Xue committed
260
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
261
	 * It is implicitly called when you use something like `$value = $dictionary[$offset];`.
Qiang Xue committed
262
	 * This is equivalent to [[itemAt]].
w  
Qiang Xue committed
263
	 * @param mixed $offset the offset to retrieve element.
w  
Qiang Xue committed
264 265 266 267 268 269 270 271 272
	 * @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.
Qiang Xue committed
273
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
274
	 * It is implicitly called when you use something like `$dictionary[$offset] = $item;`.
Qiang Xue committed
275 276 277 278
	 * 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
w  
Qiang Xue committed
279 280
	 * @param mixed $item the element value
	 */
Qiang Xue committed
281
	public function offsetSet($offset, $item)
w  
Qiang Xue committed
282
	{
Qiang Xue committed
283
		$this->add($offset, $item);
w  
Qiang Xue committed
284 285 286 287
	}

	/**
	 * Unsets the element at the specified offset.
Qiang Xue committed
288
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
289
	 * It is implicitly called when you use something like `unset($dictionary[$offset])`.
Qiang Xue committed
290
	 * This is equivalent to [[remove]].
w  
Qiang Xue committed
291 292 293 294 295 296 297
	 * @param mixed $offset the offset to unset element
	 */
	public function offsetUnset($offset)
	{
		$this->remove($offset);
	}
}