Vector.php 10.3 KB
Newer Older
Qiang Xue committed
1 2 3 4 5
<?php
/**
 * Vector class file.
 *
 * @link http://www.yiiframework.com/
Qiang Xue committed
6
 * @copyright Copyright &copy; 2008 Yii Software LLC
Qiang Xue committed
7 8 9 10 11 12 13 14 15
 * @license http://www.yiiframework.com/license/
 */

namespace yii\base;

/**
 * Vector implements an integer-indexed collection class.
 *
 * You can access, append, insert, remove an item from the vector
Qiang Xue committed
16 17
 * by calling methods such as [[itemAt()]], [[add()]], [[insertAt()]],
 * [[remove()]] and [[removeAt()]].
Qiang Xue committed
18
 *
Qiang Xue committed
19
 * To get the number of the items in the vector, use [[getCount()]].
Qiang Xue committed
20 21 22 23
 *
 * Because Vector implements a set of SPL interfaces, it can be used
 * like a regular PHP array as follows,
 *
w  
Qiang Xue committed
24
 * ~~~
Qiang Xue committed
25 26 27 28
 * $vector[] = $item;				// append new item at the end
 * $vector[$index] = $item;			// set new item at $index
 * unset($vector[$index]);			// remove the item at $index
 * if (isset($vector[$index]))		// if the vector has an item at $index
Qiang Xue committed
29
 * foreach ($vector as $index=>$item) // traverse each item in the vector
Qiang Xue committed
30
 * $n = count($vector);				// count the number of items
Qiang Xue committed
31 32 33 34
 * ~~~
 *
 * Note that if you plan to extend Vector by performing additional operations
 * with each addition or removal of an item (e.g. performing type check),
Qiang Xue committed
35 36 37
 * please make sure you override [[insertAt()]] and [[removeAt()]].
 *
 * @property integer $count the number of items in the vector
Qiang Xue committed
38 39 40 41
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
42
class Vector extends Object implements \IteratorAggregate, \ArrayAccess, \Countable
Qiang Xue committed
43 44 45 46 47 48 49 50 51 52 53 54 55 56
{
	/**
	 * @var array internal data storage
	 */
	private $_d = array();
	/**
	 * @var integer number of items
	 */
	private $_c = 0;

	/**
	 * Constructor.
	 * Initializes the vector with an array or an iterable object.
	 * @param mixed $data the initial data to be populated into the vector.
Qiang Xue committed
57
	 * This can be an array or an iterable object.
Qiang Xue committed
58
	 * @param array $config name-value pairs that will be used to initialize the object properties
Qiang Xue committed
59 60
	 * @throws Exception if data is not well formed (neither an array nor an iterable object)
	 */
Qiang Xue committed
61
	public function __construct($data = array(), $config = array())
Qiang Xue committed
62 63 64 65
	{
		if ($data !== array()) {
			$this->copyFrom($data);
		}
Qiang Xue committed
66
		parent::__construct($config);
Qiang Xue committed
67 68 69 70 71 72
	}

	/**
	 * Returns an iterator for traversing the items in the vector.
	 * This method is required by the SPL interface `IteratorAggregate`.
	 * It will be implicitly called when you use `foreach` to traverse the vector.
Qiang Xue committed
73
	 * @return VectorIterator an iterator for traversing the items in the vector.
Qiang Xue committed
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
	 */
	public function getIterator()
	{
		return new VectorIterator($this->_d);
	}

	/**
	 * Returns the number of items in the vector.
	 * This method is required by the SPL `Countable` interface.
	 * It will be implicitly called when you use `count($vector)`.
	 * @return integer number of items in the vector.
	 */
	public function count()
	{
		return $this->getCount();
	}

	/**
	 * Returns the number of items in the vector.
	 * @return integer the number of items in the vector
	 */
	public function getCount()
	{
		return $this->_c;
	}

	/**
	 * Returns the item at the specified index.
	 * @param integer $index the index of the item
	 * @return mixed the item at the index
Qiang Xue committed
104
	 * @throws InvalidCallException if the index is out of range
Qiang Xue committed
105 106 107 108 109
	 */
	public function itemAt($index)
	{
		if (isset($this->_d[$index])) {
			return $this->_d[$index];
Qiang Xue committed
110
		} elseif ($index >= 0 && $index < $this->_c) { // in case the value is null
Qiang Xue committed
111
			return $this->_d[$index];
Qiang Xue committed
112
		} else {
Qiang Xue committed
113
			throw new InvalidCallException('Index out of range: ' . $index);
Qiang Xue committed
114
		}
Qiang Xue committed
115 116 117 118 119 120 121 122 123 124 125
	}

	/**
	 * Appends an item at the end of the vector.
	 * @param mixed $item new item
	 * @return integer the zero-based index at which the item is added
	 * @throws Exception if the vector is read-only.
	 */
	public function add($item)
	{
		$this->insertAt($this->_c, $item);
Qiang Xue committed
126
		return $this->_c - 1;
Qiang Xue committed
127 128 129 130 131 132 133 134
	}

	/**
	 * Inserts an item at the specified position.
	 * Original item at the position and the following items will be moved
	 * one step towards the end.
	 * @param integer $index the specified position.
	 * @param mixed $item new item to be inserted into the vector
Qiang Xue committed
135
	 * @throws InvalidCallException if the index specified is out of range, or the vector is read-only.
Qiang Xue committed
136 137 138
	 */
	public function insertAt($index, $item)
	{
w  
Qiang Xue committed
139 140
		if ($index === $this->_c) {
			$this->_d[$this->_c++] = $item;
Qiang Xue committed
141
		} elseif ($index >= 0 && $index < $this->_c) {
w  
Qiang Xue committed
142 143
			array_splice($this->_d, $index, 0, array($item));
			$this->_c++;
Qiang Xue committed
144
		} else {
Qiang Xue committed
145
			throw new InvalidCallException('Index out of range: ' . $index);
Qiang Xue committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159
		}
	}

	/**
	 * Removes an item from the vector.
	 * The vector will search for the item, and the first item found
	 * will be removed from the vector.
	 * @param mixed $item the item to be removed.
	 * @return mixed the index at which the item is being removed, or false
	 * if the item cannot be found in the vector.
	 * @throws Exception if the vector is read only.
	 */
	public function remove($item)
	{
Qiang Xue committed
160
		if (($index = $this->indexOf($item)) >= 0) {
Qiang Xue committed
161 162
			$this->removeAt($index);
			return $index;
Qiang Xue committed
163
		} else {
Qiang Xue committed
164
			return false;
Qiang Xue committed
165
		}
Qiang Xue committed
166 167 168 169 170 171
	}

	/**
	 * Removes an item at the specified position.
	 * @param integer $index the index of the item to be removed.
	 * @return mixed the removed item.
Qiang Xue committed
172
	 * @throws InvalidCallException if the index is out of range, or the vector is read only.
Qiang Xue committed
173 174 175
	 */
	public function removeAt($index)
	{
w  
Qiang Xue committed
176 177 178 179
		if ($index >= 0 && $index < $this->_c) {
			$this->_c--;
			if ($index === $this->_c) {
				return array_pop($this->_d);
Qiang Xue committed
180
			} else {
w  
Qiang Xue committed
181 182 183
				$item = $this->_d[$index];
				array_splice($this->_d, $index, 1);
				return $item;
Qiang Xue committed
184
			}
Qiang Xue committed
185
		} else {
Qiang Xue committed
186
			throw new InvalidCallException('Index out of range: ' . $index);
Qiang Xue committed
187 188 189 190 191
		}
	}

	/**
	 * Removes all items from the vector.
192 193 194
	 * @param boolean $safeClear whether to clear every item by calling [[removeAt]].
	 * Defaults to false, meaning all items in the vector will be cleared directly
	 * without calling [[removeAt]].
Qiang Xue committed
195
	 */
196
	public function clear($safeClear = false)
Qiang Xue committed
197
	{
198
		if ($safeClear) {
Qiang Xue committed
199
			for ($i = $this->_c - 1; $i >= 0; --$i) {
200 201
				$this->removeAt($i);
			}
Qiang Xue committed
202
		} else {
203 204
			$this->_d = array();
			$this->_c = 0;
Qiang Xue committed
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
		}
	}

	/**
	 * Returns a value indicating whether the vector contains the specified item.
	 * Note that the search is based on strict PHP comparison.
	 * @param mixed $item the item
	 * @return boolean whether the vector contains the item
	 */
	public function contains($item)
	{
		return $this->indexOf($item) >= 0;
	}

	/**
	 * Returns the index of the specified item in the vector.
	 * The index is zero-based. If the item is not found in the vector, -1 will be returned.
	 * Note that the search is based on strict PHP comparison.
	 * @param mixed $item the item
	 * @return integer the index of the item in the vector (0 based), -1 if not found.
	 */
	public function indexOf($item)
	{
		$index = array_search($item, $this->_d, true);
		return $index === false ? -1 : $index;
	}

	/**
	 * Returns the vector as a PHP array.
	 * @return array the items in the vector.
	 */
	public function toArray()
	{
		return $this->_d;
	}

	/**
	 * Copies iterable data into the vector.
	 * Note, existing data in the vector 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
245
	 * @throws InvalidCallException if data is neither an array nor an object implementing `Traversable`.
Qiang Xue committed
246
	 */
Qiang Xue committed
247
	public function copyFrom($data)
Qiang Xue committed
248
	{
249
		if (is_array($data) || $data instanceof \Traversable) {
Qiang Xue committed
250 251 252 253 254 255 256 257 258
			if ($this->_c > 0) {
				$this->clear();
			}
			if ($data instanceof self) {
				$data = $data->_d;
			}
			foreach ($data as $item) {
				$this->add($item);
			}
Qiang Xue committed
259
		} else {
Qiang Xue committed
260
			throw new InvalidCallException('Data must be either an array or an object implementing Traversable.');
Qiang Xue committed
261
		}
Qiang Xue committed
262 263 264 265 266
	}

	/**
	 * Merges iterable data into the vector.
	 * New items will be appended to the end of the existing items.
Qiang Xue committed
267
	 * @param array|\Traversable $data the data to be merged with. It must be an array or object implementing Traversable
Qiang Xue committed
268
	 * @throws InvalidCallException if data is neither an array nor an object implementing `Traversable`.
Qiang Xue committed
269 270 271
	 */
	public function mergeWith($data)
	{
272
		if (is_array($data) || ($data instanceof \Traversable)) {
Qiang Xue committed
273 274 275 276 277 278
			if ($data instanceof Vector) {
				$data = $data->_d;
			}
			foreach ($data as $item) {
				$this->add($item);
			}
Qiang Xue committed
279
		} else {
Qiang Xue committed
280
			throw new InvalidCallException('The data to be merged with must be an array or an object implementing Traversable.');
Qiang Xue committed
281
		}
Qiang Xue committed
282 283 284 285 286
	}

	/**
	 * Returns a value indicating whether there is an item at the specified offset.
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
287
	 * It is implicitly called when you use something like `isset($vector[$offset])`.
Qiang Xue committed
288 289 290 291 292 293 294 295 296 297 298
	 * @param integer $offset the offset to be checked
	 * @return boolean whether there is an item at the specified offset.
	 */
	public function offsetExists($offset)
	{
		return $offset >= 0 && $offset < $this->_c;
	}

	/**
	 * Returns the item at the specified offset.
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
299
	 * It is implicitly called when you use something like `$value = $vector[$offset];`.
Qiang Xue committed
300
	 * This is equivalent to [[itemAt]].
Qiang Xue committed
301 302 303 304 305 306 307 308 309 310 311 312
	 * @param integer $offset the offset to retrieve item.
	 * @return mixed the item at the offset
	 * @throws Exception if the offset is out of range
	 */
	public function offsetGet($offset)
	{
		return $this->itemAt($offset);
	}

	/**
	 * Sets the item at the specified offset.
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
313
	 * It is implicitly called when you use something like `$vector[$offset] = $item;`.
Qiang Xue committed
314 315 316 317 318 319 320 321 322 323 324
	 * If the offset is null or equal to the number of the existing items,
	 * the new item will be appended to the vector.
	 * Otherwise, the existing item at the offset will be replaced with the new item.
	 * @param integer $offset the offset to set item
	 * @param mixed $item the item value
	 * @throws Exception if the offset is out of range, or the vector is read only.
	 */
	public function offsetSet($offset, $item)
	{
		if ($offset === null || $offset === $this->_c) {
			$this->insertAt($this->_c, $item);
Qiang Xue committed
325
		} else {
Qiang Xue committed
326 327 328 329 330 331 332 333
			$this->removeAt($offset);
			$this->insertAt($offset, $item);
		}
	}

	/**
	 * Unsets the item at the specified offset.
	 * This method is required by the SPL interface `ArrayAccess`.
w  
Qiang Xue committed
334
	 * It is implicitly called when you use something like `unset($vector[$offset])`.
Qiang Xue committed
335 336 337 338 339 340 341 342 343
	 * This is equivalent to [[removeAt]].
	 * @param integer $offset the offset to unset item
	 * @throws Exception if the offset is out of range, or the vector is read only.
	 */
	public function offsetUnset($offset)
	{
		$this->removeAt($offset);
	}
}