[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * TMap, TMapIterator classes
   4   *
   5   * @author Qiang Xue <qiang.xue@gmail.com>
   6   * @link http://www.pradosoft.com/
   7   * @copyright Copyright &copy; 2005 PradoSoft
   8   * @license http://www.pradosoft.com/license/
   9   * @version $Id: TMap.php 1397 2006-09-07 07:55:53Z wei $
  10   * @package System.Collections
  11   */
  12  
  13  /**
  14   * TMap class
  15   *
  16   * TMap implements a collection that takes key-value pairs.
  17   *
  18   * You can access, add or remove an item with a key by using
  19   * {@link itemAt}, {@link add}, and {@link remove}.
  20   * To get the number of the items in the map, use {@link getCount}.
  21   * TMap can also be used like a regular array as follows,
  22   * <code>
  23   * $map[$key]=$value; // add a key-value pair
  24   * unset($map[$key]); // remove the value with the specified key
  25   * if(isset($map[$key])) // if the map contains the key
  26   * foreach($map as $key=>$value) // traverse the items in the map
  27   * $n=count($map);  // returns the number of items in the map
  28   * </code>
  29   *
  30   * @author Qiang Xue <qiang.xue@gmail.com>
  31   * @version $Id: TMap.php 1397 2006-09-07 07:55:53Z wei $
  32   * @package System.Collections
  33   * @since 3.0
  34   */
  35  class TMap extends TComponent 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|Iterator the intial data. Default is null, meaning no initialization.
  50       * @param boolean whether the list is read-only
  51       * @throws TInvalidDataTypeException 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 whether this list is read-only or not
  70       */
  71  	protected function setReadOnly($value)
  72      {
  73          $this->_r=TPropertyValue::ensureBoolean($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 Iterator an iterator for traversing the items in the list.
  80       */
  81  	public function getIterator()
  82      {
  83          return new TMapIterator($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       * @return integer the number of items in the map
  98       */
  99  	public function getCount()
 100      {
 101          return count($this->_d);
 102      }
 103  
 104      /**
 105       * @return array the key list
 106       */
 107  	public function getKeys()
 108      {
 109          return array_keys($this->_d);
 110      }
 111  
 112      /**
 113       * Returns the item with the specified key.
 114       * This method is exactly the same as {@link offsetGet}.
 115       * @param mixed the key
 116       * @return mixed the element at the offset, null if no element is found at the offset
 117       */
 118  	public function itemAt($key)
 119      {
 120          return isset($this->_d[$key]) ? $this->_d[$key] : null;
 121      }
 122  
 123      /**
 124       * Adds an item into the map.
 125       * Note, if the specified key already exists, the old value will be overwritten.
 126       * @param mixed key
 127       * @param mixed value
 128       * @throws TInvalidOperationException if the map is read-only
 129       */
 130  	public function add($key,$value)
 131      {
 132          if(!$this->_r)
 133              $this->_d[$key]=$value;
 134          else
 135              throw new TInvalidOperationException('map_readonly',get_class($this));
 136      }
 137  
 138      /**
 139       * Removes an item from the map by its key.
 140       * @param mixed the key of the item to be removed
 141       * @return mixed the removed value, null if no such key exists.
 142       * @throws TInvalidOperationException if the map is read-only
 143       */
 144  	public function remove($key)
 145      {
 146          if(!$this->_r)
 147          {
 148              if(isset($this->_d[$key]) || array_key_exists($key,$this->_d))
 149              {
 150                  $value=$this->_d[$key];
 151                  unset($this->_d[$key]);
 152                  return $value;
 153              }
 154              else
 155                  return null;
 156          }
 157          else
 158              throw new TInvalidOperationException('map_readonly',get_class($this));
 159      }
 160  
 161      /**
 162       * Removes all items in the map.
 163       */
 164  	public function clear()
 165      {
 166          foreach(array_keys($this->_d) as $key)
 167              $this->remove($key);
 168      }
 169  
 170      /**
 171       * @param mixed the key
 172       * @return boolean whether the map contains an item with the specified key
 173       */
 174  	public function contains($key)
 175      {
 176          return isset($this->_d[$key]) || array_key_exists($key,$this->_d);
 177      }
 178  
 179      /**
 180       * @return array the list of items in array
 181       */
 182  	public function toArray()
 183      {
 184          return $this->_d;
 185      }
 186  
 187      /**
 188       * Copies iterable data into the map.
 189       * Note, existing data in the map will be cleared first.
 190       * @param mixed the data to be copied from, must be an array or object implementing Traversable
 191       * @throws TInvalidDataTypeException If data is neither an array nor an iterator.
 192       */
 193  	public function copyFrom($data)
 194      {
 195          if(is_array($data) || $data instanceof Traversable)
 196          {
 197              if($this->getCount()>0)
 198                  $this->clear();
 199              foreach($data as $key=>$value)
 200                  $this->add($key,$value);
 201          }
 202          else if($data!==null)
 203              throw new TInvalidDataTypeException('map_data_not_iterable');
 204      }
 205  
 206      /**
 207       * Merges iterable data into the map.
 208       * Existing data in the map will be kept and overwritten if the keys are the same.
 209       * @param mixed the data to be merged with, must be an array or object implementing Traversable
 210       * @throws TInvalidDataTypeException If data is neither an array nor an iterator.
 211       */
 212  	public function mergeWith($data)
 213      {
 214          if(is_array($data) || $data instanceof Traversable)
 215          {
 216              foreach($data as $key=>$value)
 217                  $this->add($key,$value);
 218          }
 219          else if($data!==null)
 220              throw new TInvalidDataTypeException('map_data_not_iterable');
 221      }
 222  
 223      /**
 224       * Returns whether there is an element at the specified offset.
 225       * This method is required by the interface ArrayAccess.
 226       * @param mixed the offset to check on
 227       * @return boolean
 228       */
 229  	public function offsetExists($offset)
 230      {
 231          return $this->contains($offset);
 232      }
 233  
 234      /**
 235       * Returns the element at the specified offset.
 236       * This method is required by the interface ArrayAccess.
 237       * @param integer the offset to retrieve element.
 238       * @return mixed the element at the offset, null if no element is found at the offset
 239       */
 240  	public function offsetGet($offset)
 241      {
 242          return $this->itemAt($offset);
 243      }
 244  
 245      /**
 246       * Sets the element at the specified offset.
 247       * This method is required by the interface ArrayAccess.
 248       * @param integer the offset to set element
 249       * @param mixed the element value
 250       */
 251  	public function offsetSet($offset,$item)
 252      {
 253          $this->add($offset,$item);
 254      }
 255  
 256      /**
 257       * Unsets the element at the specified offset.
 258       * This method is required by the interface ArrayAccess.
 259       * @param mixed the offset to unset element
 260       */
 261  	public function offsetUnset($offset)
 262      {
 263          $this->remove($offset);
 264      }
 265  }
 266  
 267  /**
 268   * TMapIterator class
 269   *
 270   * TMapIterator implements Iterator interface.
 271   *
 272   * TMapIterator is used by TMap. It allows TMap to return a new iterator
 273   * for traversing the items in the map.
 274   *
 275   * @author Qiang Xue <qiang.xue@gmail.com>
 276   * @version $Id: TMap.php 1397 2006-09-07 07:55:53Z wei $
 277   * @package System.Collections
 278   * @since 3.0
 279   */
 280  class TMapIterator implements Iterator
 281  {
 282      /**
 283       * @var array the data to be iterated through
 284       */
 285      private $_d;
 286      /**
 287       * @var array list of keys in the map
 288       */
 289      private $_keys;
 290      /**
 291       * @var mixed current key
 292       */
 293      private $_key;
 294  
 295      /**
 296       * Constructor.
 297       * @param array the data to be iterated through
 298       */
 299  	public function __construct(&$data)
 300      {
 301          $this->_d=&$data;
 302          $this->_keys=array_keys($data);
 303      }
 304  
 305      /**
 306       * Rewinds internal array pointer.
 307       * This method is required by the interface Iterator.
 308       */
 309  	public function rewind()
 310      {
 311          $this->_key=reset($this->_keys);
 312      }
 313  
 314      /**
 315       * Returns the key of the current array element.
 316       * This method is required by the interface Iterator.
 317       * @return mixed the key of the current array element
 318       */
 319  	public function key()
 320      {
 321          return $this->_key;
 322      }
 323  
 324      /**
 325       * Returns the current array element.
 326       * This method is required by the interface Iterator.
 327       * @return mixed the current array element
 328       */
 329  	public function current()
 330      {
 331          return $this->_d[$this->_key];
 332      }
 333  
 334      /**
 335       * Moves the internal pointer to the next array element.
 336       * This method is required by the interface Iterator.
 337       */
 338  	public function next()
 339      {
 340          $this->_key=next($this->_keys);
 341      }
 342  
 343      /**
 344       * Returns whether there is an element at current position.
 345       * This method is required by the interface Iterator.
 346       * @return boolean
 347       */
 348  	public function valid()
 349      {
 350          return $this->_key!==false;
 351      }
 352  }
 353  ?>