1: <?php
2: /**
3: * This file contains classes implementing Map feature.
4: *
5: * @author Qiang Xue <qiang.xue@gmail.com>
6: * @link http://www.yiiframework.com/
7: * @copyright 2008-2013 Yii Software LLC
8: * @license http://www.yiiframework.com/license/
9: */
10:
11: /**
12: * CMap implements a collection that takes key-value pairs.
13: *
14: * You can access, add or remove an item with a key by using
15: * {@link itemAt}, {@link add}, and {@link remove}.
16: * To get the number of the items in the map, use {@link getCount}.
17: * CMap can also be used like a regular array as follows,
18: * <pre>
19: * $map[$key]=$value; // add a key-value pair
20: * unset($map[$key]); // remove the value with the specified key
21: * if(isset($map[$key])) // if the map contains the key
22: * foreach($map as $key=>$value) // traverse the items in the map
23: * $n=count($map); // returns the number of items in the map
24: * </pre>
25: *
26: * @property boolean $readOnly Whether this map is read-only or not. Defaults to false.
27: * @property CMapIterator $iterator An iterator for traversing the items in the list.
28: * @property integer $count The number of items in the map.
29: * @property array $keys The key list.
30: *
31: * @author Qiang Xue <qiang.xue@gmail.com>
32: * @package system.collections
33: * @since 1.0
34: */
35: class CMap extends CComponent implements IteratorAggregate,ArrayAccess,Countable
36: {
37: /**
38: * @var array internal data storage
39: */
40: private $_d=array();
41: /**
42: * @var boolean whether this list is read-only
43: */
44: private $_r=false;
45:
46: /**
47: * Constructor.
48: * Initializes the list with an array or an iterable object.
49: * @param array $data the initial data. Default is null, meaning no initialization.
50: * @param boolean $readOnly whether the list is read-only
51: * @throws CException If data is not null and neither an array nor an iterator.
52: */
53: public function __construct($data=null,$readOnly=false)
54: {
55: if($data!==null)
56: $this->copyFrom($data);
57: $this->setReadOnly($readOnly);
58: }
59:
60: /**
61: * @return boolean whether this map is read-only or not. Defaults to false.
62: */
63: public function getReadOnly()
64: {
65: return $this->_r;
66: }
67:
68: /**
69: * @param boolean $value whether this list is read-only or not
70: */
71: protected function setReadOnly($value)
72: {
73: $this->_r=$value;
74: }
75:
76: /**
77: * Returns an iterator for traversing the items in the list.
78: * This method is required by the interface IteratorAggregate.
79: * @return CMapIterator an iterator for traversing the items in the list.
80: */
81: public function getIterator()
82: {
83: return new CMapIterator($this->_d);
84: }
85:
86: /**
87: * Returns the number of items in the map.
88: * This method is required by Countable interface.
89: * @return integer number of items in the map.
90: */
91: public function count()
92: {
93: return $this->getCount();
94: }
95:
96: /**
97: * Returns the number of items in the map.
98: * @return integer the number of items in the map
99: */
100: public function getCount()
101: {
102: return count($this->_d);
103: }
104:
105: /**
106: * @return array the key list
107: */
108: public function getKeys()
109: {
110: return array_keys($this->_d);
111: }
112:
113: /**
114: * Returns the item with the specified key.
115: * This method is exactly the same as {@link offsetGet}.
116: * @param mixed $key the key
117: * @return mixed the element at the offset, null if no element is found at the offset
118: */
119: public function itemAt($key)
120: {
121: if(isset($this->_d[$key]))
122: return $this->_d[$key];
123: else
124: return null;
125: }
126:
127: /**
128: * Adds an item into the map.
129: * Note, if the specified key already exists, the old value will be overwritten.
130: * @param mixed $key key
131: * @param mixed $value value
132: * @throws CException if the map is read-only
133: */
134: public function add($key,$value)
135: {
136: if(!$this->_r)
137: {
138: if($key===null)
139: $this->_d[]=$value;
140: else
141: $this->_d[$key]=$value;
142: }
143: else
144: throw new CException(Yii::t('yii','The map is read only.'));
145: }
146:
147: /**
148: * Removes an item from the map by its key.
149: * @param mixed $key the key of the item to be removed
150: * @return mixed the removed value, null if no such key exists.
151: * @throws CException if the map is read-only
152: */
153: public function remove($key)
154: {
155: if(!$this->_r)
156: {
157: if(isset($this->_d[$key]))
158: {
159: $value=$this->_d[$key];
160: unset($this->_d[$key]);
161: return $value;
162: }
163: else
164: {
165: // it is possible the value is null, which is not detected by isset
166: unset($this->_d[$key]);
167: return null;
168: }
169: }
170: else
171: throw new CException(Yii::t('yii','The map is read only.'));
172: }
173:
174: /**
175: * Removes all items in the map.
176: */
177: public function clear()
178: {
179: foreach(array_keys($this->_d) as $key)
180: $this->remove($key);
181: }
182:
183: /**
184: * @param mixed $key the key
185: * @return boolean whether the map contains an item with the specified key
186: */
187: public function contains($key)
188: {
189: return isset($this->_d[$key]) || array_key_exists($key,$this->_d);
190: }
191:
192: /**
193: * @return array the list of items in array
194: */
195: public function toArray()
196: {
197: return $this->_d;
198: }
199:
200: /**
201: * Copies iterable data into the map.
202: * Note, existing data in the map will be cleared first.
203: * @param mixed $data the data to be copied from, must be an array or object implementing Traversable
204: * @throws CException If data is neither an array nor an iterator.
205: */
206: public function copyFrom($data)
207: {
208: if(is_array($data) || $data instanceof Traversable)
209: {
210: if($this->getCount()>0)
211: $this->clear();
212: if($data instanceof CMap)
213: $data=$data->_d;
214: foreach($data as $key=>$value)
215: $this->add($key,$value);
216: }
217: elseif($data!==null)
218: throw new CException(Yii::t('yii','Map data must be an array or an object implementing Traversable.'));
219: }
220:
221: /**
222: * Merges iterable data into the map.
223: *
224: * Existing elements in the map will be overwritten if their keys are the same as those in the source.
225: * If the merge is recursive, the following algorithm is performed:
226: * <ul>
227: * <li>the map data is saved as $a, and the source data is saved as $b;</li>
228: * <li>if $a and $b both have an array indexed at the same string key, the arrays will be merged using this algorithm;</li>
229: * <li>any integer-indexed elements in $b will be appended to $a and reindexed accordingly;</li>
230: * <li>any string-indexed elements in $b will overwrite elements in $a with the same index;</li>
231: * </ul>
232: *
233: * @param mixed $data the data to be merged with, must be an array or object implementing Traversable
234: * @param boolean $recursive whether the merging should be recursive.
235: *
236: * @throws CException If data is neither an array nor an iterator.
237: */
238: public function mergeWith($data,$recursive=true)
239: {
240: if(is_array($data) || $data instanceof Traversable)
241: {
242: if($data instanceof CMap)
243: $data=$data->_d;
244: if($recursive)
245: {
246: if($data instanceof Traversable)
247: {
248: $d=array();
249: foreach($data as $key=>$value)
250: $d[$key]=$value;
251: $this->_d=self::mergeArray($this->_d,$d);
252: }
253: else
254: $this->_d=self::mergeArray($this->_d,$data);
255: }
256: else
257: {
258: foreach($data as $key=>$value)
259: $this->add($key,$value);
260: }
261: }
262: elseif($data!==null)
263: throw new CException(Yii::t('yii','Map data must be an array or an object implementing Traversable.'));
264: }
265:
266: /**
267: * Merges two or more arrays into one recursively.
268: * If each array has an element with the same string key value, the latter
269: * will overwrite the former (different from array_merge_recursive).
270: * Recursive merging will be conducted if both arrays have an element of array
271: * type and are having the same key.
272: * For integer-keyed elements, the elements from the latter array will
273: * be appended to the former array.
274: * @param array $a array to be merged to
275: * @param array $b array to be merged from. You can specify additional
276: * arrays via third argument, fourth argument etc.
277: * @return array the merged array (the original arrays are not changed.)
278: * @see mergeWith
279: */
280: public static function mergeArray($a,$b)
281: {
282: $args=func_get_args();
283: $res=array_shift($args);
284: while(!empty($args))
285: {
286: $next=array_shift($args);
287: foreach($next as $k => $v)
288: {
289: if(is_integer($k))
290: isset($res[$k]) ? $res[]=$v : $res[$k]=$v;
291: elseif(is_array($v) && isset($res[$k]) && is_array($res[$k]))
292: $res[$k]=self::mergeArray($res[$k],$v);
293: else
294: $res[$k]=$v;
295: }
296: }
297: return $res;
298: }
299:
300: /**
301: * Returns whether there is an element at the specified offset.
302: * This method is required by the interface ArrayAccess.
303: * @param mixed $offset the offset to check on
304: * @return boolean
305: */
306: public function offsetExists($offset)
307: {
308: return $this->contains($offset);
309: }
310:
311: /**
312: * Returns the element at the specified offset.
313: * This method is required by the interface ArrayAccess.
314: * @param integer $offset the offset to retrieve element.
315: * @return mixed the element at the offset, null if no element is found at the offset
316: */
317: public function offsetGet($offset)
318: {
319: return $this->itemAt($offset);
320: }
321:
322: /**
323: * Sets the element at the specified offset.
324: * This method is required by the interface ArrayAccess.
325: * @param integer $offset the offset to set element
326: * @param mixed $item the element value
327: */
328: public function offsetSet($offset,$item)
329: {
330: $this->add($offset,$item);
331: }
332:
333: /**
334: * Unsets the element at the specified offset.
335: * This method is required by the interface ArrayAccess.
336: * @param mixed $offset the offset to unset element
337: */
338: public function offsetUnset($offset)
339: {
340: $this->remove($offset);
341: }
342: }
343: