php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-11-04 06:37:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

finished Dictionary.

Browse Source
This commit is contained in:
Qiang Xue
2011-07-16 14:18:23 -04:00
parent 83068e0d36
commit 688870c197
3 changed files with 213 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

318
framework/base/Dictionary.php
View File

@ -1,91 +1,81 @@
<?php <?php
/**
* Dictionary class file.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @link http://www.yiiframework.com/
* @copyright Copyright &copy; 2008-2012 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\base; namespace yii\base;
/** /**
* This file contains classes implementing Map feature. * Dictionary implements a collection that stores key-value pairs.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @link http://www.yiiframework.com/
* @copyright Copyright &copy; 2008-2011 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
/**
* CMap implements a collection that takes key-value pairs.
* *
* You can access, add or remove an item with a key by using * You can access, add or remove an item with a key by using
* {@link itemAt}, {@link add}, and {@link remove}. * [[itemAt]], [[add]], and [[remove]].
* To get the number of the items in the map, use {@link getCount}. *
* CMap can also be used like a regular array as follows, * To get the number of the items in the dictionary, use [[getCount]].
* <pre> *
* $map[$key]=$value; // add a key-value pair * Because Dictionary implements a set of SPL interfaces, it can be used
* unset($map[$key]); // remove the value with the specified key * like a regular PHP array as follows,
* if(isset($map[$key])) // if the map contains the key *
* foreach($map as $key=>$value) // traverse the items in the map * ~~~php
* $n=count($map); // returns the number of items in the map * $dictionary[$key] = $value; // add a key-value pair
* </pre> * unset($dictionary[$key]); // remove the value with the specified key
* if (isset($dictionary[$key])) // if the dictionary contains the key
* foreach ($dictionary as $key=>$value) // traverse the items in the dictionary
* $n = count($dictionary); // returns the number of items in the dictionary
* ~~~
* *
* @author Qiang Xue <qiang.xue@gmail.com> * @author Qiang Xue <qiang.xue@gmail.com>
* @version $Id: CMap.php 3153 2011-04-01 12:50:06Z qiang.xue $ * @since 2.0
* @package system.collections
* @since 1.0
*/ */
class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess, \Countable class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess, \Countable
{ {
/**
* @var boolean whether this vector is read-only or not.
* If the vector is read-only, adding or moving items will throw an exception.
*/
public $readOnly;
/** /**
* @var array internal data storage * @var array internal data storage
*/ */
private $_d=array(); private $_d = array();
/**
* @var boolean whether this list is read-only
*/
private $_r=false;
/** /**
* Constructor. * Constructor.
* Initializes the list with an array or an iterable object. * Initializes the dictionary with an array or an iterable object.
* @param array $data the intial data. Default is null, meaning no initialization. * @param mixed $data the initial data to be populated into the dictionary.
* @param boolean $readOnly whether the list is read-only * This can be an array or an iterable object.
* @throws CException If data is not null and neither an array nor an iterator. * @param boolean $readOnly whether the dictionary is read-only
* @throws Exception if data is not well formed (neither an array nor an iterable object)
*/ */
public function __construct($data=null,$readOnly=false) public function __construct($data = array(), $readOnly = false)
{ {
if($data!==null) if ($data !== array()) {
$this->copyFrom($data); $this->copyFrom($data);
$this->setReadOnly($readOnly); }
$this->readOnly = $readOnly;
} }
/** /**
* @return boolean whether this map is read-only or not. Defaults to false. * Returns an iterator for traversing the items in the dictionary.
*/ * This method is required by the SPL interface `IteratorAggregate`.
public function getReadOnly() * It will be implicitly called when you use `foreach` to traverse the dictionary.
{ * @return DictionaryIterator an iterator for traversing the items in the dictionary.
return $this->_r;
}
/**
* @param boolean $value whether this list is read-only or not
*/
protected function setReadOnly($value)
{
$this->_r=$value;
}
/**
* Returns an iterator for traversing the items in the list.
* This method is required by the interface IteratorAggregate.
* @return CMapIterator an iterator for traversing the items in the list.
*/ */
public function getIterator() public function getIterator()
{ {
return new CMapIterator($this->_d); return new DictionaryIterator($this->_d);
} }
/** /**
* Returns the number of items in the map. * Returns the number of items in the dictionary.
* This method is required by Countable interface. * This method is required by the SPL `Countable` interface.
* @return integer number of items in the map. * It will be implicitly called when you use `count($dictionary)`.
* @return integer number of items in the dictionary.
*/ */
public function count() public function count()
{ {
@ -93,8 +83,8 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
} }
/** /**
* Returns the number of items in the map. * Returns the number of items in the dictionary.
* @return integer the number of items in the map * @return integer the number of items in the dictionary
*/ */
public function getCount() public function getCount()
{ {
@ -102,6 +92,7 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
} }
/** /**
* Returns the keys stored in the dictionary.
* @return array the key list * @return array the key list
*/ */
public function getKeys() public function getKeys()
@ -111,84 +102,83 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
/** /**
* Returns the item with the specified key. * Returns the item with the specified key.
* This method is exactly the same as {@link offsetGet}.
* @param mixed $key the key * @param mixed $key the key
* @return mixed the element at the offset, null if no element is found at the offset * @return mixed the element with the specified key.
* Null if the key cannot be found in the dictionary.
*/ */
public function itemAt($key) public function itemAt($key)
{ {
if(isset($this->_d[$key])) return isset($this->_d[$key]) ? $this->_d[$key] : null;
return $this->_d[$key];
else
return null;
} }
/** /**
* Adds an item into the map. * Adds an item into the dictionary.
* Note, if the specified key already exists, the old value will be overwritten. * Note, if the specified key already exists, the old value will be overwritten.
* @param mixed $key key * @param mixed $key key
* @param mixed $value value * @param mixed $value value
* @throws CException if the map is read-only * @throws Exception if the dictionary is read-only
*/ */
public function add($key,$value) public function add($key, $value)
{ {
if(!$this->_r) if (!$this->readOnly) {
{ if ($key === null) {
if($key===null) $this->_d[] = $value;
$this->_d[]=$value; }
else else {
$this->_d[$key]=$value; $this->_d[$key] = $value;
}
}
else {
throw new Exception('Dictionary is read only.');
} }
else
throw new CException(Yii::t('yii','The map is read only.'));
} }
/** /**
* Removes an item from the map by its key. * Removes an item from the dictionary by its key.
* @param mixed $key the key of the item to be removed * @param mixed $key the key of the item to be removed
* @return mixed the removed value, null if no such key exists. * @return mixed the removed value, null if no such key exists.
* @throws CException if the map is read-only * @throws Exception if the dictionary is read-only
*/ */
public function remove($key) public function remove($key)
{ {
if(!$this->_r) if (!$this->readOnly) {
{ if (isset($this->_d[$key])) {
if(isset($this->_d[$key])) $value = $this->_d[$key];
{
$value=$this->_d[$key];
unset($this->_d[$key]); unset($this->_d[$key]);
return $value; return $value;
} }
else else { // the value is null
{
// it is possible the value is null, which is not detected by isset
unset($this->_d[$key]); unset($this->_d[$key]);
return null; return null;
} }
} }
else else {
throw new CException(Yii::t('yii','The map is read only.')); throw new Exception('Dictionary is read only.');
}
} }
/** /**
* Removes all items in the map. * Removes all items in the dictionary.
*/ */
public function clear() public function clear()
{ {
foreach(array_keys($this->_d) as $key) foreach (array_keys($this->_d) as $key) {
$this->remove($key); $this->remove($key);
} }
}
/** /**
* Returns a value indicating whether the dictionary contains the specified key.
* @param mixed $key the key * @param mixed $key the key
* @return boolean whether the map contains an item with the specified key * @return boolean whether the dictionary contains an item with the specified key
*/ */
public function contains($key) public function contains($key)
{ {
return isset($this->_d[$key]) || array_key_exists($key,$this->_d); return isset($this->_d[$key]) || array_key_exists($key, $this->_d);
} }
/** /**
* Returns the dictionary as a PHP array.
* @return array the list of items in array * @return array the list of items in array
*/ */
public function toArray() public function toArray()
@ -197,33 +187,37 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
} }
/** /**
* Copies iterable data into the map. * Copies iterable data into the dictionary.
* Note, existing data in the map will be cleared first. * Note, existing data in the dictionary will be cleared first.
* @param mixed $data the data to be copied from, must be an array or object implementing Traversable * @param mixed $data the data to be copied from, must be an array or an object implementing `Traversable`
* @throws CException If data is neither an array nor an iterator. * @throws Exception if data is neither an array nor an iterator.
*/ */
public function copyFrom($data) public function copyFrom($data)
{ {
if(is_array($data) || $data instanceof Traversable) if (is_array($data) || $data instanceof Traversable)
{ {
if($this->getCount()>0) if (($this->_d !== array()) {
$this->clear(); $this->clear();
if($data instanceof CMap)
$data=$data->_d;
foreach($data as $key=>$value)
$this->add($key,$value);
} }
else if($data!==null) if ($data instanceof self) {
throw new CException(Yii::t('yii','Map data must be an array or an object implementing Traversable.')); $data = $data->_d;
}
foreach ($data as $key => $value) {
$this->add($key, $value);
}
}
else {
throw new Exception('Data must be either an array or an object implementing Traversable.');
}
} }
/** /**
* Merges iterable data into the map. * Merges iterable data into the dictionary.
* *
* Existing elements in the map will be overwritten if their keys are the same as those in the source. * Existing elements in the dictionary will be overwritten if their keys are the same as those in the source.
* If the merge is recursive, the following algorithm is performed: * If the merge is recursive, the following algorithm is performed:
* <ul> * <ul>
* <li>the map data is saved as $a, and the source data is saved as $b;</li> * <li>the dictionary data is saved as $a, and the source data is saved as $b;</li>
* <li>if $a and $b both have an array indxed at the same string key, the arrays will be merged using this algorithm;</li> * <li>if $a and $b both have an array indxed at the same string key, the arrays will be merged using this algorithm;</li>
* <li>any integer-indexed elements in $b will be appended to $a and reindxed accordingly;</li> * <li>any integer-indexed elements in $b will be appended to $a and reindxed accordingly;</li>
* <li>any string-indexed elements in $b will overwrite elements in $a with the same index;</li> * <li>any string-indexed elements in $b will overwrite elements in $a with the same index;</li>
@ -236,13 +230,13 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
*/ */
public function mergeWith($data,$recursive=true) public function mergeWith($data,$recursive=true)
{ {
if(is_array($data) || $data instanceof Traversable) if (is_array($data) || $data instanceof Traversable)
{ {
if($data instanceof CMap) if ($data instanceof Dictionary)
$data=$data->_d; $data=$data->_d;
if($recursive) if ($recursive)
{ {
if($data instanceof Traversable) if ($data instanceof Traversable)
{ {
$d=array(); $d=array();
foreach($data as $key=>$value) foreach($data as $key=>$value)
@ -258,8 +252,61 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
$this->add($key,$value); $this->add($key,$value);
} }
} }
else if($data!==null) else if ($data!==null)
throw new CException(Yii::t('yii','Map data must be an array or an object implementing Traversable.')); throw new CException(Yii::t('yii','Dictionary data must be an array or an object implementing Traversable.'));
}
/**
* Returns whether there is an element at the specified offset.
* This method is required by the SPL interface `ArrayAccess`.
* It is implicitly called when you use something like `isset($vector[$index])`.
* This is equivalent to [[contains]].
* @param mixed $offset the offset to check on
* @return boolean
*/
public function offsetExists($offset)
{
return $this->contains($offset);
}
/**
* Returns the element at the specified offset.
* This method is required by the SPL interface `ArrayAccess`.
* It is implicitly called when you use something like `$value = $dictionary[$index];`.
* This is equivalent to [[itemAt]].
* @param integer $offset the offset to retrieve element.
* @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.
* This method is required by the SPL interface `ArrayAccess`.
* It is implicitly called when you use something like `$dictionary[$key] = $value;`.
* 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
* @param mixed $item the element value
*/
public function offsetSet($offset, $item)
{
$this->add($offset,$item);
}
/**
* Unsets the element at the specified offset.
* This method is required by the SPL interface `ArrayAccess`.
* It is implicitly called when you use something like `unset($dictionary[$index])`.
* This is equivalent to [[remove]].
* @param mixed $offset the offset to unset element
*/
public function offsetUnset($offset)
{
$this->remove($offset);
} }
/** /**
@ -288,47 +335,4 @@ class Dictionary extends Component implements \IteratorAggregate, \ArrayAccess,
} }
return $a; return $a;
} }
/**
* Returns whether there is an element at the specified offset.
* This method is required by the interface ArrayAccess.
* @param mixed $offset the offset to check on
* @return boolean
*/
public function offsetExists($offset)
{
return $this->contains($offset);
}
/**
* Returns the element at the specified offset.
* This method is required by the interface ArrayAccess.
* @param integer $offset the offset to retrieve element.
* @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.
* This method is required by the interface ArrayAccess.
* @param integer $offset the offset to set element
* @param mixed $item the element value
*/
public function offsetSet($offset,$item)
{
$this->add($offset,$item);
}
/**
* Unsets the element at the specified offset.
* This method is required by the interface ArrayAccess.
* @param mixed $offset the offset to unset element
*/
public function offsetUnset($offset)
{
$this->remove($offset);
}
} }

56
framework/base/DictionaryIterator.php
View File

@ -1,25 +1,23 @@
<?php <?php
/**
* DictionaryIterator class file.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @link http://www.yiiframework.com/
* @copyright Copyright &copy; 2008-2012 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\base; namespace yii\base;
/** /**
* CMapIterator class file. * DictionaryIterator implements the SPL `Iterator` interface for [[Dictionary]].
*
* It allows [[Dictionary]] to return a new iterator for data traversing purpose.
* You normally do not use this class directly.
* *
* @author Qiang Xue <qiang.xue@gmail.com> * @author Qiang Xue <qiang.xue@gmail.com>
* @link http://www.yiiframework.com/ * @since 2.0
* @copyright Copyright &copy; 2008-2011 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
/**
* CMapIterator implements an interator for {@link CMap}.
*
* It allows CMap to return a new iterator for traversing the items in the map.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @version $Id: CMapIterator.php 3186 2011-04-15 22:34:55Z alexander.makarow $
* @package system.collections
* @since 1.0
*/ */
class DictionaryIterator implements \Iterator class DictionaryIterator implements \Iterator
{ {
@ -42,23 +40,23 @@ class DictionaryIterator implements \Iterator
*/ */
public function __construct(&$data) public function __construct(&$data)
{ {
$this->_d=&$data; $this->_d = &$data;
$this->_keys=array_keys($data); $this->_keys = array_keys($data);
$this->_key=reset($this->_keys); $this->_key = reset($this->_keys);
} }
/** /**
* Rewinds internal array pointer. * Rewinds the index of the current item.
* This method is required by the interface Iterator. * This method is required by the SPL interface `Iterator`.
*/ */
public function rewind() public function rewind()
{ {
$this->_key=reset($this->_keys); $this->_key = reset($this->_keys);
} }
/** /**
* Returns the key of the current array element. * Returns the key of the current array element.
* This method is required by the interface Iterator. * This method is required by the SPL interface `Iterator`.
* @return mixed the key of the current array element * @return mixed the key of the current array element
*/ */
public function key() public function key()
@ -68,7 +66,7 @@ class DictionaryIterator implements \Iterator
/** /**
* Returns the current array element. * Returns the current array element.
* This method is required by the interface Iterator. * This method is required by the SPL interface `Iterator`.
* @return mixed the current array element * @return mixed the current array element
*/ */
public function current() public function current()
@ -77,21 +75,21 @@ class DictionaryIterator implements \Iterator
} }
/** /**
* Moves the internal pointer to the next array element. * Moves the internal pointer to the next element.
* This method is required by the interface Iterator. * This method is required by the SPL interface `Iterator`.
*/ */
public function next() public function next()
{ {
$this->_key=next($this->_keys); $this->_key = next($this->_keys);
} }
/** /**
* Returns whether there is an element at current position. * Returns whether there is an element at current position.
* This method is required by the interface Iterator. * This method is required by the SPL interface `Iterator`.
* @return boolean * @return boolean whether there is an item at current position.
*/ */
public function valid() public function valid()
{ {
return $this->_key!==false; return $this->_key !== false;
} }
} }

21
framework/base/Vector.php
View File

@ -58,7 +58,7 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
* Constructor. * Constructor.
* Initializes the vector with an array or an iterable object. * Initializes the vector with an array or an iterable object.
* @param mixed $data the initial data to be populated into the vector. * @param mixed $data the initial data to be populated into the vector.
* This can be an array or an iterable object. If null, the vector will be set as empty. * This can be an array or an iterable object.
* @param boolean $readOnly whether the vector should be marked as read-only. * @param boolean $readOnly whether the vector should be marked as read-only.
* @throws Exception if data is not well formed (neither an array nor an iterable object) * @throws Exception if data is not well formed (neither an array nor an iterable object)
*/ */
@ -115,9 +115,10 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
elseif ($index >= 0 && $index < $this->_c) { // in case the value is null elseif ($index >= 0 && $index < $this->_c) { // in case the value is null
return $this->_d[$index]; return $this->_d[$index];
} }
else {
throw new Exception('Index out of range: ' . $index); throw new Exception('Index out of range: ' . $index);
} }
}
/** /**
* Appends an item at the end of the vector. * Appends an item at the end of the vector.
@ -149,10 +150,14 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
array_splice($this->_d, $index, 0, array($item)); array_splice($this->_d, $index, 0, array($item));
$this->_c++; $this->_c++;
} }
else {
throw new Exception('Index out of range: ' . $index); throw new Exception('Index out of range: ' . $index);
} }
}
else {
throw new Exception('Vector is read only.'); throw new Exception('Vector is read only.');
} }
}
/** /**
* Removes an item from the vector. * Removes an item from the vector.
@ -170,9 +175,10 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
$this->removeAt($index); $this->removeAt($index);
return $index; return $index;
} }
else else {
return false; return false;
} }
}
/** /**
* Removes an item at the specified position. * Removes an item at the specified position.
@ -194,10 +200,14 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
return $item; return $item;
} }
} }
else {
throw new Exception('Index out of range: ' . $index); throw new Exception('Index out of range: ' . $index);
} }
}
else {
throw new Exception('Vector is read only.'); throw new Exception('Vector is read only.');
} }
}
/** /**
* Removes all items from the vector. * Removes all items from the vector.
@ -261,8 +271,10 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
$this->add($item); $this->add($item);
} }
} }
else {
throw new Exception('Data must be either an array or an object implementing Traversable.'); throw new Exception('Data must be either an array or an object implementing Traversable.');
} }
}
/** /**
* Merges iterable data into the vector. * Merges iterable data into the vector.
@ -280,8 +292,10 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
$this->add($item); $this->add($item);
} }
} }
else {
throw new Exception('Data must be either an array or an object implementing Traversable.'); throw new Exception('Data must be either an array or an object implementing Traversable.');
} }
}
/** /**
* Returns a value indicating whether there is an item at the specified offset. * Returns a value indicating whether there is an item at the specified offset.
@ -299,6 +313,7 @@ class Vector extends Component implements \IteratorAggregate, \ArrayAccess, \Cou
* Returns the item at the specified offset. * Returns the item at the specified offset.
* This method is required by the SPL interface `ArrayAccess`. * This method is required by the SPL interface `ArrayAccess`.
* It is implicitly called when you use something like `$value = $vector[$index];`. * It is implicitly called when you use something like `$value = $vector[$index];`.
* This is equivalent to [[itemAt]].
* @param integer $offset the offset to retrieve item. * @param integer $offset the offset to retrieve item.
* @return mixed the item at the offset * @return mixed the item at the offset
* @throws Exception if the offset is out of range * @throws Exception if the offset is out of range