diff options
Diffstat (limited to 'lib/prado/framework/Collections')
| -rw-r--r-- | lib/prado/framework/Collections/TAttributeCollection.php | 170 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TDummyDataSource.php | 143 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TList.php | 483 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TListItemCollection.php | 162 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TMap.php | 350 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TPagedDataSource.php | 442 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TPagedList.php | 473 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TPriorityList.php | 741 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TPriorityMap.php | 604 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TQueue.php | 263 | ||||
| -rw-r--r-- | lib/prado/framework/Collections/TStack.php | 260 |
11 files changed, 4091 insertions, 0 deletions
diff --git a/lib/prado/framework/Collections/TAttributeCollection.php b/lib/prado/framework/Collections/TAttributeCollection.php new file mode 100644 index 0000000..a0f14ef --- /dev/null +++ b/lib/prado/framework/Collections/TAttributeCollection.php @@ -0,0 +1,170 @@ +<?php +/** + * TAttributeCollection classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * Includes TMap class + */ +Prado::using('System.Collections.TMap'); + +/** + * TAttributeCollection class + * + * TAttributeCollection implements a collection for storing attribute names and values. + * + * Besides all functionalities provided by {@link TMap}, TAttributeCollection + * allows you to get and set attribute values like getting and setting + * properties. For example, the following usages are all valid for a + * TAttributeCollection object: + * <code> + * $collection->Text='text'; + * echo $collection->Text; + * </code> + * They are equivalent to the following: + * <code> + * $collection->add('Text','text'); + * echo $collection->itemAt('Text'); + * </code> + * + * Note, attribute names are case-insensitive. They are converted to lower-case + * in the collection storage. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TAttributeCollection extends TMap +{ + private $_caseSensitive=false; + + /** + * Returns a property value or an event handler list by property or event name. + * This method overrides the parent implementation by returning + * a key value if the key exists in the collection. + * @param string the property name or the event name + * @return mixed the property value or the event handler list + * @throws TInvalidOperationException if the property/event is not defined. + */ + public function __get($name) + { + return $this->contains($name)?$this->itemAt($name):parent::__get($name); + } + + /** + * Sets value of a component property. + * This method overrides the parent implementation by adding a new key value + * to the collection. + * @param string the property name or event name + * @param mixed the property value or event handler + * @throws TInvalidOperationException If the property is not defined or read-only. + */ + public function __set($name,$value) + { + $this->add($name,$value); + } + + /** + * @return boolean whether the keys are case-sensitive. Defaults to false. + */ + public function getCaseSensitive() + { + return $this->_caseSensitive; + } + + /** + * @param boolean whether the keys are case-sensitive. + */ + public function setCaseSensitive($value) + { + $this->_caseSensitive=TPropertyValue::ensureBoolean($value); + } + + /** + * Returns the item with the specified key. + * This overrides the parent implementation by converting the key to lower case first if CaseSensitive is false. + * @param mixed the key + * @return mixed the element at the offset, null if no element is found at the offset + */ + public function itemAt($key) + { + return parent::itemAt($this->_caseSensitive?$key:strtolower($key)); + } + + + /** + * Adds an item into the map. + * This overrides the parent implementation by converting the key to lower case first if CaseSensitive is false. + * @param mixed key + * @param mixed value + */ + public function add($key,$value) + { + parent::add($this->_caseSensitive?$key:strtolower($key),$value); + } + + /** + * Removes an item from the map by its key. + * This overrides the parent implementation by converting the key to lower case first if CaseSensitive is false. + * @param mixed the key of the item to be removed + * @return mixed the removed value, null if no such key exists. + */ + public function remove($key) + { + return parent::remove($this->_caseSensitive?$key:strtolower($key)); + } + + /** + * Returns whether the specified is in the map. + * This overrides the parent implementation by converting the key to lower case first if CaseSensitive is false. + * @param mixed the key + * @return boolean whether the map contains an item with the specified key + */ + public function contains($key) + { + return parent::contains($this->_caseSensitive?$key:strtolower($key)); + } + + /** + * Determines whether a property is defined. + * This method overrides parent implementation by returning true + * if the collection contains the named key. + * @param string the property name + * @return boolean whether the property is defined + */ + public function hasProperty($name) + { + return $this->contains($name) || parent::canGetProperty($name) || parent::canSetProperty($name); + } + + /** + * Determines whether a property can be read. + * This method overrides parent implementation by returning true + * if the collection contains the named key. + * @param string the property name + * @return boolean whether the property can be read + */ + public function canGetProperty($name) + { + return $this->contains($name) || parent::canGetProperty($name); + } + + /** + * Determines whether a property can be set. + * This method overrides parent implementation by always returning true + * because you can always add a new value to the collection. + * @param string the property name + * @return boolean true + */ + public function canSetProperty($name) + { + return true; + } +} + diff --git a/lib/prado/framework/Collections/TDummyDataSource.php b/lib/prado/framework/Collections/TDummyDataSource.php new file mode 100644 index 0000000..6aaaeaa --- /dev/null +++ b/lib/prado/framework/Collections/TDummyDataSource.php @@ -0,0 +1,143 @@ +<?php +/** + * TDummyDataSource, TDummyDataSourceIterator classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TDummyDataSource class + * + * TDummyDataSource implements a dummy data collection with a specified number + * of dummy data items. The number of virtual items can be set via + * {@link setCount Count} property. You can traverse it using <b>foreach</b> + * PHP statement like the following, + * <code> + * foreach($dummyDataSource as $dataItem) + * </code> + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TDummyDataSource extends TComponent implements IteratorAggregate, Countable +{ + private $_count; + + /** + * Constructor. + * @param integer number of (virtual) items in the data source. + */ + public function __construct($count) + { + $this->_count=$count; + } + + /** + * @return integer number of (virtual) items in the data source. + */ + public function getCount() + { + return $this->_count; + } + + /** + * @return Iterator iterator + */ + public function getIterator() + { + return new TDummyDataSourceIterator($this->_count); + } + + /** + * Returns the number of (virtual) items in the data source. + * This method is required by Countable interface. + * @return integer number of (virtual) items in the data source. + */ + public function count() + { + return $this->getCount(); + } +} + +/** + * TDummyDataSourceIterator class + * + * TDummyDataSourceIterator implements Iterator interface. + * + * TDummyDataSourceIterator is used by {@link TDummyDataSource}. + * It allows TDummyDataSource to return a new iterator + * for traversing its dummy items. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TDummyDataSourceIterator implements Iterator +{ + private $_index; + private $_count; + + /** + * Constructor. + * @param integer number of (virtual) items in the data source. + */ + public function __construct($count) + { + $this->_count=$count; + $this->_index=0; + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_index=0; + } + + /** + * Returns the key of the current array item. + * This method is required by the interface Iterator. + * @return integer the key of the current array item + */ + public function key() + { + return $this->_index; + } + + /** + * Returns the current array item. + * This method is required by the interface Iterator. + * @return mixed the current array item + */ + public function current() + { + return null; + } + + /** + * Moves the internal pointer to the next array item. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_index++; + } + + /** + * Returns whether there is an item at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_index<$this->_count; + } +} + diff --git a/lib/prado/framework/Collections/TList.php b/lib/prado/framework/Collections/TList.php new file mode 100644 index 0000000..bba0dae --- /dev/null +++ b/lib/prado/framework/Collections/TList.php @@ -0,0 +1,483 @@ +<?php +/** + * TList, TListIterator classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TList class + * + * TList implements an integer-indexed collection class. + * + * You can access, append, insert, remove an item by using + * {@link itemAt}, {@link add}, {@link insertAt}, {@link remove}, and {@link removeAt}. + * To get the number of the items in the list, use {@link getCount}. + * TList can also be used like a regular array as follows, + * <code> + * $list[]=$item; // append at the end + * $list[$index]=$item; // $index must be between 0 and $list->Count + * unset($list[$index]); // remove the item at $index + * if(isset($list[$index])) // if the list has an item at $index + * foreach($list as $index=>$item) // traverse each item in the list + * $n=count($list); // returns the number of items in the list + * </code> + * + * To extend TList by doing additional operations with each addition or removal + * operation, override {@link insertAt()}, and {@link removeAt()}. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TList extends TComponent implements IteratorAggregate,ArrayAccess,Countable +{ + /** + * internal data storage + * @var array + */ + private $_d=array(); + /** + * number of items + * @var integer + */ + private $_c=0; + /** + * @var boolean whether this list is read-only + */ + private $_r=false; + + /** + * Constructor. + * Initializes the list with an array or an iterable object. + * @param array|Iterator the initial data. Default is null, meaning no initialization. + * @param boolean whether the list is read-only + * @throws TInvalidDataTypeException If data is not null and neither an array nor an iterator. + */ + public function __construct($data=null,$readOnly=false) + { + if($data!==null) + $this->copyFrom($data); + $this->setReadOnly($readOnly); + } + + /** + * @return boolean whether this list is read-only or not. Defaults to false. + */ + public function getReadOnly() + { + return $this->_r; + } + + /** + * @param boolean whether this list is read-only or not + */ + protected function setReadOnly($value) + { + $this->_r=TPropertyValue::ensureBoolean($value); + } + + /** + * Returns an iterator for traversing the items in the list. + * This method is required by the interface IteratorAggregate. + * @return Iterator an iterator for traversing the items in the list. + */ + public function getIterator() + { + return new ArrayIterator( $this->_d ); + } + + /** + * Returns the number of items in the list. + * This method is required by Countable interface. + * @return integer number of items in the list. + */ + public function count() + { + return $this->getCount(); + } + + /** + * @return integer the number of items in the list + */ + public function getCount() + { + return $this->_c; + } + + /** + * Returns the item at the specified offset. + * This method is exactly the same as {@link offsetGet}. + * @param integer the index of the item + * @return mixed the item at the index + * @throws TInvalidDataValueException if the index is out of the range + */ + public function itemAt($index) + { + if($index>=0 && $index<$this->_c) + return $this->_d[$index]; + else + throw new TInvalidDataValueException('list_index_invalid',$index); + } + + /** + * Appends an item at the end of the list. + * @param mixed new item + * @return integer the zero-based index at which the item is added + * @throws TInvalidOperationException if the list is read-only + */ + public function add($item) + { + $this->insertAt($this->_c,$item); + return $this->_c-1; + } + + /** + * Inserts an item at the specified position. + * Original item at the position and the next items + * will be moved one step towards the end. + * @param integer the specified position. + * @param mixed new item + * @throws TInvalidDataValueException If the index specified exceeds the bound + * @throws TInvalidOperationException if the list is read-only + */ + public function insertAt($index,$item) + { + if(!$this->_r) + { + if($index===$this->_c) + $this->_d[$this->_c++]=$item; + else if($index>=0 && $index<$this->_c) + { + array_splice($this->_d,$index,0,array($item)); + $this->_c++; + } + else + throw new TInvalidDataValueException('list_index_invalid',$index); + } + else + throw new TInvalidOperationException('list_readonly',get_class($this)); + } + + /** + * Removes an item from the list. + * The list will first search for the item. + * The first item found will be removed from the list. + * @param mixed the item to be removed. + * @return integer the index at which the item is being removed + * @throws TInvalidDataValueException If the item does not exist + * @throws TInvalidOperationException if the list is read-only + */ + public function remove($item) + { + if(!$this->_r) + { + if(($index=$this->indexOf($item))>=0) + { + $this->removeAt($index); + return $index; + } + else + throw new TInvalidDataValueException('list_item_inexistent'); + } + else + throw new TInvalidOperationException('list_readonly',get_class($this)); + } + + /** + * Removes an item at the specified position. + * @param integer the index of the item to be removed. + * @return mixed the removed item. + * @throws TInvalidDataValueException If the index specified exceeds the bound + * @throws TInvalidOperationException if the list is read-only + */ + public function removeAt($index) + { + if(!$this->_r) + { + if($index>=0 && $index<$this->_c) + { + $this->_c--; + if($index===$this->_c) + return array_pop($this->_d); + else + { + $item=$this->_d[$index]; + array_splice($this->_d,$index,1); + return $item; + } + } + else + throw new TInvalidDataValueException('list_index_invalid',$index); + } + else + throw new TInvalidOperationException('list_readonly',get_class($this)); + } + + /** + * Removes all items in the list. + * @throws TInvalidOperationException if the list is read-only + */ + public function clear() + { + for($i=$this->_c-1;$i>=0;--$i) + $this->removeAt($i); + } + + /** + * @param mixed the item + * @return boolean whether the list contains the item + */ + public function contains($item) + { + return $this->indexOf($item)>=0; + } + + /** + * @param mixed the item + * @return integer the index of the item in the list (0 based), -1 if not found. + */ + public function indexOf($item) + { + if(($index=array_search($item,$this->_d,true))===false) + return -1; + else + return $index; + } + + /** + * Finds the base item. If found, the item is inserted before it. + * @param mixed the base item which will be pushed back by the second parameter + * @param mixed the item + * @return int the index where the item is inserted + * @throws TInvalidDataValueException if the base item is not within this list + * @throws TInvalidOperationException if the list is read-only + * @since 3.2a + */ + public function insertBefore($baseitem, $item) + { + if(!$this->_r) + { + if(($index = $this->indexOf($baseitem)) == -1) + throw new TInvalidDataValueException('list_item_inexistent'); + + $this->insertAt($index, $item); + + return $index; + } + else + throw new TInvalidOperationException('list_readonly',get_class($this)); + } + + /** + * Finds the base item. If found, the item is inserted after it. + * @param mixed the base item which comes before the second parameter when added to the list + * @param mixed the item + * @return int the index where the item is inserted + * @throws TInvalidDataValueException if the base item is not within this list + * @throws TInvalidOperationException if the list is read-only + * @since 3.2a + */ + public function insertAfter($baseitem, $item) + { + if(!$this->_r) + { + if(($index = $this->indexOf($baseitem)) == -1) + throw new TInvalidDataValueException('list_item_inexistent'); + + $this->insertAt($index + 1, $item); + + return $index + 1; + } + else + throw new TInvalidOperationException('list_readonly',get_class($this)); + } + + /** + * @return array the list of items in array + */ + public function toArray() + { + return $this->_d; + } + + /** + * Copies iterable data into the list. + * Note, existing data in the list will be cleared first. + * @param mixed the data to be copied from, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor a Traversable. + */ + public function copyFrom($data) + { + if(is_array($data) || ($data instanceof Traversable)) + { + if($this->_c>0) + $this->clear(); + foreach($data as $item) + $this->add($item); + } + else if($data!==null) + throw new TInvalidDataTypeException('list_data_not_iterable'); + } + + /** + * Merges iterable data into the map. + * New data will be appended to the end of the existing data. + * @param mixed the data to be merged with, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function mergeWith($data) + { + if(is_array($data) || ($data instanceof Traversable)) + { + foreach($data as $item) + $this->add($item); + } + else if($data!==null) + throw new TInvalidDataTypeException('list_data_not_iterable'); + } + + /** + * Returns whether there is an item at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer the offset to check on + * @return boolean + */ + public function offsetExists($offset) + { + return ($offset>=0 && $offset<$this->_c); + } + + /** + * Returns the item at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer the offset to retrieve item. + * @return mixed the item at the offset + * @throws TInvalidDataValueException if the offset is invalid + */ + public function offsetGet($offset) + { + return $this->itemAt($offset); + } + + /** + * Sets the item at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer the offset to set item + * @param mixed the item value + */ + public function offsetSet($offset,$item) + { + if($offset===null || $offset===$this->_c) + $this->insertAt($this->_c,$item); + else + { + $this->removeAt($offset); + $this->insertAt($offset,$item); + } + } + + /** + * Unsets the item at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer the offset to unset item + */ + public function offsetUnset($offset) + { + $this->removeAt($offset); + } +} + + +/** + * TListIterator class + * + * TListIterator implements Iterator interface. + * + * TListIterator is used by TList. It allows TList to return a new iterator + * for traversing the items in the list. + * + * @deprecated Issue 264 : ArrayIterator should be used instead + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TListIterator implements Iterator +{ + /** + * @var array the data to be iterated through + */ + private $_d; + /** + * @var integer index of the current item + */ + private $_i; + /** + * @var integer count of the data items + */ + private $_c; + + /** + * Constructor. + * @param array the data to be iterated through + */ + public function __construct(&$data) + { + $this->_d=&$data; + $this->_i=0; + $this->_c=count($this->_d); + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_i=0; + } + + /** + * Returns the key of the current array item. + * This method is required by the interface Iterator. + * @return integer the key of the current array item + */ + public function key() + { + return $this->_i; + } + + /** + * Returns the current array item. + * This method is required by the interface Iterator. + * @return mixed the current array item + */ + public function current() + { + return $this->_d[$this->_i]; + } + + /** + * Moves the internal pointer to the next array item. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_i++; + } + + /** + * Returns whether there is an item at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_i<$this->_c; + } +} + diff --git a/lib/prado/framework/Collections/TListItemCollection.php b/lib/prado/framework/Collections/TListItemCollection.php new file mode 100644 index 0000000..ed00146 --- /dev/null +++ b/lib/prado/framework/Collections/TListItemCollection.php @@ -0,0 +1,162 @@ +<?php + +/** + * TListItemCollection class file + * + * @author Robin J. Rogge <rojaro@gmail.com> + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * Includes the supporting classes + */ +Prado::using('System.Collections.TList'); +Prado::using('System.Web.UI.WebControls.TListItem'); + +/** + * TListItemCollection class. + * + * TListItemCollection maintains a list of {@link TListItem} for {@link TListControl}. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TListItemCollection extends TList +{ + /** + * Creates a list item object. + * This method may be overriden to provide a customized list item object. + * @param integer index where the newly created item is to be inserted at. + * If -1, the item will be appended to the end. + * @return TListItem list item object + */ + public function createListItem($index=-1) + { + $item=$this->createNewListItem(); + if($index<0) + $this->add($item); + else + $this->insertAt($index,$item); + return $item; + } + + /** + * @return TListItem new item. + */ + protected function createNewListItem($text=null) + { + $item = new TListItem; + if($text!==null) + $item->setText($text); + return $item; + } + + /** + * Inserts an item into the collection. + * @param integer the location where the item will be inserted. + * The current item at the place and the following ones will be moved backward. + * @param TListItem the item to be inserted. + * @throws TInvalidDataTypeException if the item being inserted is neither a string nor TListItem + */ + public function insertAt($index,$item) + { + if(is_string($item)) + $item = $this->createNewListItem($item); + if(!($item instanceof TListItem)) + throw new TInvalidDataTypeException('listitemcollection_item_invalid',get_class($this)); + parent::insertAt($index,$item); + } + + /** + * Finds the lowest cardinal index of the item whose value is the one being looked for. + * @param string the value to be looked for + * @param boolean whether to look for disabled items also + * @return integer the index of the item found, -1 if not found. + */ + public function findIndexByValue($value,$includeDisabled=true) + { + $value=TPropertyValue::ensureString($value); + $index=0; + foreach($this as $item) + { + if($item->getValue()===$value && ($includeDisabled || $item->getEnabled())) + return $index; + $index++; + } + return -1; + } + + /** + * Finds the lowest cardinal index of the item whose text is the one being looked for. + * @param string the text to be looked for + * @param boolean whether to look for disabled items also + * @return integer the index of the item found, -1 if not found. + */ + public function findIndexByText($text,$includeDisabled=true) + { + $text=TPropertyValue::ensureString($text); + $index=0; + foreach($this as $item) + { + if($item->getText()===$text && ($includeDisabled || $item->getEnabled())) + return $index; + $index++; + } + return -1; + } + + /** + * Finds the item whose value is the one being looked for. + * @param string the value to be looked for + * @param boolean whether to look for disabled items also + * @return TListItem the item found, null if not found. + */ + public function findItemByValue($value,$includeDisabled=true) + { + if(($index=$this->findIndexByValue($value,$includeDisabled))>=0) + return $this->itemAt($index); + else + return null; + } + + /** + * Finds the item whose text is the one being looked for. + * @param string the text to be looked for + * @param boolean whether to look for disabled items also + * @return TListItem the item found, null if not found. + */ + public function findItemByText($text,$includeDisabled=true) + { + if(($index=$this->findIndexByText($text,$includeDisabled))>=0) + return $this->itemAt($index); + else + return null; + } + + /** + * Loads state into every item in the collection. + * This method should only be used by framework and control developers. + * @param array|null state to be loaded. + */ + public function loadState($state) + { + $this->clear(); + if($state!==null) + $this->copyFrom($state); + } + + /** + * Saves state of items. + * This method should only be used by framework and control developers. + * @return array|null the saved state + */ + public function saveState() + { + return ($this->getCount()>0) ? $this->toArray() : null; + } +} diff --git a/lib/prado/framework/Collections/TMap.php b/lib/prado/framework/Collections/TMap.php new file mode 100644 index 0000000..d610dce --- /dev/null +++ b/lib/prado/framework/Collections/TMap.php @@ -0,0 +1,350 @@ +<?php +/** + * TMap, TMapIterator classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TMap class + * + * TMap implements a collection that takes key-value pairs. + * + * You can access, add or remove an item with a key by using + * {@link itemAt}, {@link add}, and {@link remove}. + * To get the number of the items in the map, use {@link getCount}. + * TMap can also be used like a regular array as follows, + * <code> + * $map[$key]=$value; // add a key-value pair + * unset($map[$key]); // remove the value with the specified key + * if(isset($map[$key])) // if the map contains the key + * foreach($map as $key=>$value) // traverse the items in the map + * $n=count($map); // returns the number of items in the map + * </code> + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TMap extends TComponent implements IteratorAggregate,ArrayAccess,Countable +{ + /** + * @var array internal data storage + */ + private $_d=array(); + /** + * @var boolean whether this list is read-only + */ + private $_r=false; + + /** + * Constructor. + * Initializes the list with an array or an iterable object. + * @param array|Iterator the intial data. Default is null, meaning no initialization. + * @param boolean whether the list is read-only + * @throws TInvalidDataTypeException If data is not null and neither an array nor an iterator. + */ + public function __construct($data=null,$readOnly=false) + { + if($data!==null) + $this->copyFrom($data); + $this->setReadOnly($readOnly); + } + + /** + * @return boolean whether this map is read-only or not. Defaults to false. + */ + public function getReadOnly() + { + return $this->_r; + } + + /** + * @param boolean whether this list is read-only or not + */ + protected function setReadOnly($value) + { + $this->_r=TPropertyValue::ensureBoolean($value); + } + + /** + * Returns an iterator for traversing the items in the list. + * This method is required by the interface IteratorAggregate. + * @return Iterator an iterator for traversing the items in the list. + */ + public function getIterator() + { + return new ArrayIterator( $this->_d ); + } + + /** + * Returns the number of items in the map. + * This method is required by Countable interface. + * @return integer number of items in the map. + */ + public function count() + { + return $this->getCount(); + } + + /** + * @return integer the number of items in the map + */ + public function getCount() + { + return count($this->_d); + } + + /** + * @return array the key list + */ + public function getKeys() + { + return array_keys($this->_d); + } + + /** + * Returns the item with the specified key. + * This method is exactly the same as {@link offsetGet}. + * @param mixed the key + * @return mixed the element at the offset, null if no element is found at the offset + */ + public function itemAt($key) + { + return isset($this->_d[$key]) ? $this->_d[$key] : null; + } + + /** + * Adds an item into the map. + * Note, if the specified key already exists, the old value will be overwritten. + * @param mixed key + * @param mixed value + * @throws TInvalidOperationException if the map is read-only + */ + public function add($key,$value) + { + if(!$this->_r) + $this->_d[$key]=$value; + else + throw new TInvalidOperationException('map_readonly',get_class($this)); + } + + /** + * Removes an item from the map by its key. + * @param mixed the key of the item to be removed + * @return mixed the removed value, null if no such key exists. + * @throws TInvalidOperationException if the map is read-only + */ + public function remove($key) + { + if(!$this->_r) + { + if(isset($this->_d[$key]) || array_key_exists($key,$this->_d)) + { + $value=$this->_d[$key]; + unset($this->_d[$key]); + return $value; + } + else + return null; + } + else + throw new TInvalidOperationException('map_readonly',get_class($this)); + } + + /** + * Removes all items in the map. + */ + public function clear() + { + foreach(array_keys($this->_d) as $key) + $this->remove($key); + } + + /** + * @param mixed the key + * @return boolean whether the map contains an item with the specified key + */ + public function contains($key) + { + return isset($this->_d[$key]) || array_key_exists($key,$this->_d); + } + + /** + * @return array the list of items in array + */ + public function toArray() + { + return $this->_d; + } + + /** + * Copies iterable data into the map. + * Note, existing data in the map will be cleared first. + * @param mixed the data to be copied from, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function copyFrom($data) + { + if(is_array($data) || $data instanceof Traversable) + { + if($this->getCount()>0) + $this->clear(); + foreach($data as $key=>$value) + $this->add($key,$value); + } + else if($data!==null) + throw new TInvalidDataTypeException('map_data_not_iterable'); + } + + /** + * Merges iterable data into the map. + * Existing data in the map will be kept and overwritten if the keys are the same. + * @param mixed the data to be merged with, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function mergeWith($data) + { + if(is_array($data) || $data instanceof Traversable) + { + foreach($data as $key=>$value) + $this->add($key,$value); + } + else if($data!==null) + throw new TInvalidDataTypeException('map_data_not_iterable'); + } + + /** + * Returns whether there is an element at the specified offset. + * This method is required by the interface ArrayAccess. + * @param mixed 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 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 the offset to set element + * @param mixed 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 the offset to unset element + */ + public function offsetUnset($offset) + { + $this->remove($offset); + } +} + +/** + * TMapIterator class + * + * TMapIterator implements Iterator interface. + * + * TMapIterator is used by TMap. It allows TMap to return a new iterator + * for traversing the items in the map. + * + * @deprecated Issue 264 : ArrayIterator should be used instead + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TMapIterator implements Iterator +{ + /** + * @var array the data to be iterated through + */ + private $_d; + /** + * @var array list of keys in the map + */ + private $_keys; + /** + * @var mixed current key + */ + private $_key; + + /** + * Constructor. + * @param array the data to be iterated through + */ + public function __construct(&$data) + { + $this->_d=&$data; + $this->_keys=array_keys($data); + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_key=reset($this->_keys); + } + + /** + * Returns the key of the current array element. + * This method is required by the interface Iterator. + * @return mixed the key of the current array element + */ + public function key() + { + return $this->_key; + } + + /** + * Returns the current array element. + * This method is required by the interface Iterator. + * @return mixed the current array element + */ + public function current() + { + return $this->_d[$this->_key]; + } + + /** + * Moves the internal pointer to the next array element. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_key=next($this->_keys); + } + + /** + * Returns whether there is an element at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_key!==false; + } +} diff --git a/lib/prado/framework/Collections/TPagedDataSource.php b/lib/prado/framework/Collections/TPagedDataSource.php new file mode 100644 index 0000000..ec0b895 --- /dev/null +++ b/lib/prado/framework/Collections/TPagedDataSource.php @@ -0,0 +1,442 @@ +<?php +/** + * TPagedDataSource, TPagedListIterator, TPagedMapIterator classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TPagedDataSource class + * + * TPagedDataSource implements an integer-indexed collection class with paging functionality. + * + * Data items in TPagedDataSource can be traversed using <b>foreach</b> + * PHP statement like the following, + * <code> + * foreach($pagedDataSource as $dataItem) + * </code> + * The data are fetched from {@link setDataSource DataSource}. Only the items + * within the specified page will be returned and traversed. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TPagedDataSource extends TComponent implements IteratorAggregate,Countable +{ + /** + * @var mixed original data source + */ + private $_dataSource=null; + /** + * @var integer number of items in each page + */ + private $_pageSize=10; + /** + * @var integer current page index + */ + private $_currentPageIndex=0; + /** + * @var boolean whether to allow paging + */ + private $_allowPaging=false; + /** + * @var boolean whether to allow custom paging + */ + private $_allowCustomPaging=false; + /** + * @var integer user-assigned number of items in data source + */ + private $_virtualCount=0; + + /** + * @return mixed original data source. Defaults to null. + */ + public function getDataSource() + { + return $this->_dataSource; + } + + /** + * @param mixed original data source + */ + public function setDataSource($value) + { + if(!($value instanceof TMap) && !($value instanceof TList)) + { + if(is_array($value)) + $value=new TMap($value); + else if($value instanceof Traversable) + $value=new TList($value); + else if($value!==null) + throw new TInvalidDataTypeException('pageddatasource_datasource_invalid'); + } + $this->_dataSource=$value; + } + + /** + * @return integer number of items in each page. Defaults to 10. + */ + public function getPageSize() + { + return $this->_pageSize; + } + + /** + * @param integer number of items in each page + */ + public function setPageSize($value) + { + if(($value=TPropertyValue::ensureInteger($value))>0) + $this->_pageSize=$value; + else + throw new TInvalidDataValueException('pageddatasource_pagesize_invalid'); + } + + /** + * @return integer current page index. Defaults to 0. + */ + public function getCurrentPageIndex() + { + return $this->_currentPageIndex; + } + + /** + * @param integer current page index + */ + public function setCurrentPageIndex($value) + { + if(($value=TPropertyValue::ensureInteger($value))<0) + $value=0; + $this->_currentPageIndex=$value; + } + + /** + * @return boolean whether to allow paging. Defaults to false. + */ + public function getAllowPaging() + { + return $this->_allowPaging; + } + + /** + * @param boolean whether to allow paging + */ + public function setAllowPaging($value) + { + $this->_allowPaging=TPropertyValue::ensureBoolean($value); + } + + /** + * @return boolean whether to allow custom paging. Defaults to false. + */ + public function getAllowCustomPaging() + { + return $this->_allowCustomPaging; + } + + /** + * @param boolean whether to allow custom paging + */ + public function setAllowCustomPaging($value) + { + $this->_allowCustomPaging=TPropertyValue::ensureBoolean($value); + } + + /** + * @return integer user-assigned number of items in data source Defaults to 0. + */ + public function getVirtualItemCount() + { + return $this->_virtualCount; + } + + /** + * @param integer user-assigned number of items in data source + */ + public function setVirtualItemCount($value) + { + if(($value=TPropertyValue::ensureInteger($value))>=0) + $this->_virtualCount=$value; + else + throw new TInvalidDataValueException('pageddatasource_virtualitemcount_invalid'); + } + + /** + * @return integer number of items in current page + */ + public function getCount() + { + if($this->_dataSource===null) + return 0; + if(!$this->_allowPaging) + return $this->getDataSourceCount(); + if(!$this->_allowCustomPaging && $this->getIsLastPage()) + return $this->getDataSourceCount()-$this->getFirstIndexInPage(); + return $this->_pageSize; + } + + /** + * Returns the number of items in the current page. + * This method is required by Countable interface. + * @return integer number of items in the current page. + */ + public function count() + { + return $this->getCount(); + } + + /** + * @return integer number of pages + */ + public function getPageCount() + { + if($this->_dataSource===null) + return 0; + $count=$this->getDataSourceCount(); + if(!$this->_allowPaging || $count<=0) + return 1; + return (int)(($count+$this->_pageSize-1)/$this->_pageSize); + } + + /** + * @return boolean whether the current page is the first page Defaults to false. + */ + public function getIsFirstPage() + { + if($this->_allowPaging) + return $this->_currentPageIndex===0; + else + return true; + } + + /** + * @return boolean whether the current page is the last page + */ + public function getIsLastPage() + { + if($this->_allowPaging) + return $this->_currentPageIndex===$this->getPageCount()-1; + else + return true; + } + + /** + * @return integer the index of the item in data source, where the item is the first in + * current page + */ + public function getFirstIndexInPage() + { + if($this->_dataSource!==null && $this->_allowPaging && !$this->_allowCustomPaging) + return $this->_currentPageIndex*$this->_pageSize; + else + return 0; + } + + /** + * @return integer number of items in data source, if available + */ + public function getDataSourceCount() + { + if($this->_dataSource===null) + return 0; + else if($this->_allowCustomPaging) + return $this->_virtualCount; + else + return $this->_dataSource->getCount(); + } + + /** + * @return Iterator iterator + */ + public function getIterator() + { + if($this->_dataSource instanceof TList) + return new TPagedListIterator($this->_dataSource,$this->getFirstIndexInPage(),$this->getCount()); + else if($this->_dataSource instanceof TMap) + return new TPagedMapIterator($this->_dataSource,$this->getFirstIndexInPage(),$this->getCount()); + else + return null; + } +} + + + +/** + * TPagedListIterator class + * + * TPagedListIterator implements Iterator interface. + * + * TPagedListIterator is used by {@link TPagedDataSource}. It allows TPagedDataSource + * to return a new iterator for traversing the items in a {@link TList} object. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TPagedListIterator implements Iterator +{ + private $_list; + private $_startIndex; + private $_count; + private $_index; + + /** + * Constructor. + * @param TList the data to be iterated through + * @param integer start index + * @param integer number of items to be iterated through + */ + public function __construct(TList $list,$startIndex,$count) + { + $this->_list=$list; + $this->_index=0; + $this->_startIndex=$startIndex; + if($startIndex+$count>$list->getCount()) + $this->_count=$list->getCount()-$startIndex; + else + $this->_count=$count; + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_index=0; + } + + /** + * Returns the key of the current array item. + * This method is required by the interface Iterator. + * @return integer the key of the current array item + */ + public function key() + { + return $this->_index; + } + + /** + * Returns the current array item. + * This method is required by the interface Iterator. + * @return mixed the current array item + */ + public function current() + { + return $this->_list->itemAt($this->_startIndex+$this->_index); + } + + /** + * Moves the internal pointer to the next array item. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_index++; + } + + /** + * Returns whether there is an item at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_index<$this->_count; + } +} + +/** + * TPagedMapIterator class + * + * TPagedMapIterator implements Iterator interface. + * + * TPagedMapIterator is used by {@link TPagedDataSource}. It allows TPagedDataSource + * to return a new iterator for traversing the items in a {@link TMap} object. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TPagedMapIterator implements Iterator +{ + private $_map; + private $_startIndex; + private $_count; + private $_index; + private $_iterator; + + /** + * Constructor. + * @param array the data to be iterated through + */ + public function __construct(TMap $map,$startIndex,$count) + { + $this->_map=$map; + $this->_index=0; + $this->_startIndex=$startIndex; + if($startIndex+$count>$map->getCount()) + $this->_count=$map->getCount()-$startIndex; + else + $this->_count=$count; + $this->_iterator=$map->getIterator(); + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_iterator->rewind(); + for($i=0;$i<$this->_startIndex;++$i) + $this->_iterator->next(); + $this->_index=0; + } + + /** + * Returns the key of the current array item. + * This method is required by the interface Iterator. + * @return integer the key of the current array item + */ + public function key() + { + return $this->_iterator->key(); + } + + /** + * Returns the current array item. + * This method is required by the interface Iterator. + * @return mixed the current array item + */ + public function current() + { + return $this->_iterator->current(); + } + + /** + * Moves the internal pointer to the next array item. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_index++; + $this->_iterator->next(); + } + + /** + * Returns whether there is an item at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_index<$this->_count; + } +} + diff --git a/lib/prado/framework/Collections/TPagedList.php b/lib/prado/framework/Collections/TPagedList.php new file mode 100644 index 0000000..118bba1 --- /dev/null +++ b/lib/prado/framework/Collections/TPagedList.php @@ -0,0 +1,473 @@ +<?php +/** + * TPagedList, TPagedListFetchDataEventParameter, TPagedListPageChangedEventParameter class file + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TPagedList class + * + * TPagedList implements a list with paging functionality. + * + * TPagedList works in one of two modes, managed paging or customized paging, + * specified by {@link setCustomPaging CustomPaging}. + * - Managed paging ({@link setCustomPaging CustomPaging}=false) : + * the list is assumed to contain all data and it will manage which page + * of data are available to user. + * - Customized paging ({@link setCustomPaging CustomPaging}=true) : + * the list is assumed to contain only one page of data. An {@link onFetchData OnFetchData} + * event will be raised if the list changes to a different page. + * Developers can attach a handler to the event and supply the needed data. + * The event handler can be written as follows, + * <code> + * public function fetchData($sender,$param) + * { + * $offset=$param->Offset; // beginning index of the data needed + * $limit=$param->Limit; // maximum number of data items needed + * // get data according to the above two parameters + * $param->Data=$data; + * } + * </code> + * + * Data in TPagedList can be accessed like an integer-indexed array and can + * be traversed using foreach. For example, + * <code> + * $count=$list->Count; + * for($index=0;$index<$count;++$index) + * echo $list[$index]; + * foreach($list as $index=>$item) // traverse each item in the list + * </code> + * + * The {@link setPageSize PageSize} property specifies the number of items in each page. + * To access different page of data in the list, set {@link setCurrentPageIndex CurrentPageIndex} + * or call {@link nextPage()}, {@link previousPage()}, or {@link gotoPage()}. + * The total number of pages can be obtained by {@link getPageCount() PageCount}. + * + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TPagedList extends TList +{ + /** + * @var boolean whether to allow custom paging + */ + private $_customPaging=false; + /** + * @var integer number of items in each page + */ + private $_pageSize=10; + /** + * @var integer current page index + */ + private $_currentPageIndex=-1; + /** + * @var integer user-assigned number of items in data source + */ + private $_virtualCount=-1; + + /** + * Constructor. + * @param array|Iterator the initial data. Default is null, meaning no initialization. + * @param boolean whether the list is read-only. Always true for paged list. + */ + public function __construct($data=null,$readOnly=false) + { + parent::__construct($data,true); + } + + /** + * @return boolean whether to use custom paging. Defaults to false. + */ + public function getCustomPaging() + { + return $this->_customPaging; + } + + /** + * @param boolean whether to allow custom paging + */ + public function setCustomPaging($value) + { + $this->_customPaging=TPropertyValue::ensureBoolean($value); + } + + /** + * @return integer number of items in each page. Defaults to 10. + */ + public function getPageSize() + { + return $this->_pageSize; + } + + /** + * @param integer number of items in each page + */ + public function setPageSize($value) + { + if(($value=TPropertyValue::ensureInteger($value))>0) + $this->_pageSize=$value; + else + throw new TInvalidDataValueException('pagedlist_pagesize_invalid'); + } + + /** + * @return integer current page index. Defaults to 0. + */ + public function getCurrentPageIndex() + { + return $this->_currentPageIndex; + } + + /** + * @param integer current page index + * @throws TInvalidDataValueException if the page index is out of range + */ + public function setCurrentPageIndex($value) + { + if($this->gotoPage($value=TPropertyValue::ensureInteger($value))===false) + throw new TInvalidDataValueException('pagedlist_currentpageindex_invalid'); + } + + /** + * Raises <b>OnPageIndexChanged</b> event. + * This event is raised each time when the list changes to a different page. + * @param TPagedListPageChangedEventParameter event parameter + */ + public function onPageIndexChanged($param) + { + $this->raiseEvent('OnPageIndexChanged',$this,$param); + } + + /** + * Raises <b>OnFetchData</b> event. + * This event is raised each time when the list changes to a different page + * and needs the new page of data. This event can only be raised when + * {@link setCustomPaging CustomPaging} is true. + * @param TPagedListFetchDataEventParameter event parameter + */ + public function onFetchData($param) + { + $this->raiseEvent('OnFetchData',$this,$param); + } + + /** + * Changes to a page with the specified page index. + * @param integer page index + * @return integer|boolean the new page index, false if page index is out of range. + */ + public function gotoPage($pageIndex) + { + if($pageIndex===$this->_currentPageIndex) + return $pageIndex; + if($this->_customPaging) + { + if($pageIndex>=0 && ($this->_virtualCount<0 || $pageIndex<$this->getPageCount())) + { + $param=new TPagedListFetchDataEventParameter($pageIndex,$this->_pageSize*$pageIndex,$this->_pageSize); + $this->onFetchData($param); + if(($data=$param->getData())!==null) + { + $this->setReadOnly(false); + $this->copyFrom($data); + $this->setReadOnly(true); + $oldPage=$this->_currentPageIndex; + $this->_currentPageIndex=$pageIndex; + $this->onPageIndexChanged(new TPagedListPageChangedEventParameter($oldPage)); + return $pageIndex; + } + else + return false; + } + else + return false; + } + else + { + if($pageIndex>=0 && $pageIndex<$this->getPageCount()) + { + $this->_currentPageIndex=$pageIndex; + $this->onPageIndexChanged(null); + return $pageIndex; + } + else + return false; + } + } + + /** + * Switches to the next page. + * @return integer|boolean the new page index, false if next page is not available. + */ + public function nextPage() + { + return $this->gotoPage($this->_currentPageIndex+1); + } + + /** + * Switches to the previous page. + * @return integer|boolean the new page index, false if previous page is not available. + */ + public function previousPage() + { + return $this->gotoPage($this->_currentPageIndex-1); + } + + /** + * @return integer user-assigned number of items in data source. Defaults to 0. + */ + public function getVirtualCount() + { + return $this->_virtualCount; + } + + /** + * @param integer user-assigned number of items in data source + */ + public function setVirtualCount($value) + { + if(($value=TPropertyValue::ensureInteger($value))<0) + $value=-1; + $this->_virtualCount=$value; + } + + /** + * @return integer number of pages, -1 if under custom paging mode and {@link setVirtualCount VirtualCount} is not set. + */ + public function getPageCount() + { + if($this->_customPaging) + { + if($this->_virtualCount>=0) + return (int)(($this->_virtualCount+$this->_pageSize-1)/$this->_pageSize); + else + return -1; + } + else + return (int)((parent::getCount()+$this->_pageSize-1)/$this->_pageSize); + } + + /** + * @return boolean whether the current page is the first page + */ + public function getIsFirstPage() + { + return $this->_currentPageIndex===0; + } + + /** + * @return boolean whether the current page is the last page + */ + public function getIsLastPage() + { + return $this->_currentPageIndex===$this->getPageCount()-1; + } + + /** + * @return integer the number of items in current page + */ + public function getCount() + { + if($this->_customPaging) + return parent::getCount(); + else + { + if($this->_currentPageIndex===$this->getPageCount()-1) + return parent::getCount()-$this->_pageSize*$this->_currentPageIndex; + else + return $this->_pageSize; + } + } + + /** + * @return Iterator iterator + */ + public function getIterator() + { + if($this->_customPaging) + return parent::getIterator(); + else + { + $data=$this->toArray(); + return new TListIterator($data); + } + } + + /** + * Returns the item at the specified offset. + * This method is exactly the same as {@link offsetGet}. + * @param integer the index of the item + * @return mixed the item at the index + * @throws TInvalidDataValueException if the index is out of the range + */ + public function itemAt($index) + { + if($this->_customPaging) + return parent::itemAt($index); + else + return parent::itemAt($this->_pageSize*$this->_currentPageIndex+$index); + } + + /** + * @param mixed the item + * @return integer the index of the item in the list (0 based), -1 if not found. + */ + public function indexOf($item) + { + $c=$this->getCount(); + for($i=0;$i<$c;++$i) + if($this->itemAt($i)===$item) + return $i; + return -1; + } + + /** + * Returns whether there is an item at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer the offset to check on + * @return boolean + */ + public function offsetExists($offset) + { + return ($offset>=0 && $offset<$this->getCount()); + } + + /** + * Returns the item at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer the offset to retrieve item. + * @return mixed the item at the offset + * @throws TInvalidDataValueException if the offset is invalid + */ + public function offsetGet($offset) + { + return $this->itemAt($offset); + } + + /** + * @return array the list of items in array + */ + public function toArray() + { + $c=$this->getCount(); + $array=array(); + for($i=0;$i<$c;++$i) + $array[$i]=$this->itemAt($i); + return $array; + } +} + +/** + * TPagedListPageChangedEventParameter class. + * TPagedListPageChangedEventParameter is used as the parameter for + * {@link TPagedList::onPageChanged OnPageChanged} event. + * To obtain the page index before it was changed, use {@link getOldPageIndex OldPageIndex}. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TPagedListPageChangedEventParameter extends TEventParameter +{ + private $_oldPage; + + /** + * Constructor. + * @param integer old page index + */ + public function __construct($oldPage) + { + $this->_oldPage=$oldPage; + } + + /** + * @return integer the index of the page before the list changed to the new page + */ + public function getOldPageIndex() + { + return $this->_oldPage; + } +} + +/** + * TPagedListFetchDataEventParameter class. + * + * TPagedListFetchDataEventParameter is used as the parameter for + * {@link TPagedList::onFetchData OnFetchData} event. + * To obtain the new page index, use {@link getNewPageIndex NewPageIndex}. + * The {@link getOffset Offset} property refers to the index + * of the first item in the new page, while {@link getLimit Limit} + * specifies how many items are requested for the page. + * Newly fetched data should be saved in {@link setData Data} property. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TPagedListFetchDataEventParameter extends TEventParameter +{ + private $_pageIndex; + private $_offset; + private $_limit; + private $_data=null; + + /** + * Constructor. + * @param integer new page index + * @param integer offset of the first item in the new page + * @param integer number of items in the new page desired + */ + public function __construct($pageIndex,$offset,$limit) + { + $this->_pageIndex=$pageIndex; + $this->_offset=$offset; + $this->_limit=$limit; + } + + /** + * @return integer the zero-based index of the new page + */ + public function getNewPageIndex() + { + return $this->_pageIndex; + } + + /** + * @return integer offset of the first item in the new page + */ + public function getOffset() + { + return $this->_offset; + } + + /** + * @return integer number of items in the new page + */ + public function getLimit() + { + return $this->_limit; + } + + /** + * @return mixed new page data + */ + public function getData() + { + return $this->_data; + } + + /** + * @param mixed new page data + */ + public function setData($value) + { + $this->_data=$value; + } +} + diff --git a/lib/prado/framework/Collections/TPriorityList.php b/lib/prado/framework/Collections/TPriorityList.php new file mode 100644 index 0000000..ad548dc --- /dev/null +++ b/lib/prado/framework/Collections/TPriorityList.php @@ -0,0 +1,741 @@ +<?php +/** + * TPriorityList, TPriorityListIterator classes + * + * @author Brad Anderson <javalizard@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TPriorityList class + * + * TPriorityList implements a priority ordered list collection class. It allows you to specify + * any numeric for priorities down to a specific precision. The lower the numeric, the high the priority of the item in the + * list. Thus -10 has a higher priority than -5, 0, 10 (the default), 18, 10005, etc. Per {@link round}, precision may be negative and + * thus rounding can go by 10, 100, 1000, etc, instead of just .1, .01, .001, etc. The default precision allows for 8 decimal + * places. There is also a default priority of 10, if no different default priority is specified or no item specific priority is indicated. + * If you replace TList with this class it will work exactly the same with items inserted set to the default priority, until you start + * using different priorities than the default priority. + * + * As you access the PHP array features of this class, it flattens and caches the results. If at all possible, this + * will keep the cache fresh even when manipulated. If this is not possible the cache is cleared. + * When an array of items are needed and the cache is outdated, the cache is recreated from the items and their priorities + * + * You can access, append, insert, remove an item by using + * {@link itemAt}, {@link add}, {@link insertAt}, and {@link remove}. + * To get the number of the items in the list, use {@link getCount}. + * TPriorityList can also be used like a regular array as follows, + * <code> + * $list[]=$item; // append with the default priority. It may not be the last item if other items in the list are prioritized after the default priority + * $list[$index]=$item; // $index must be between 0 and $list->Count-1. This sets the element regardless of priority. Priority stays the same. + * $list[$index]=$item; // $index is $list->Count. This appends the item to the end of the list with the same priority as the last item in the list. + * unset($list[$index]); // remove the item at $index + * if(isset($list[$index])) // if the list has an item at $index + * foreach($list as $index=>$item) // traverse each item in the list in proper priority order and add/insert order + * $n=count($list); // returns the number of items in the list + * </code> + * + * To extend TPriorityList for doing your own operations with each addition or removal, + * override {@link insertAtIndexInPriority()} and {@link removeAtIndexInPriority()} and then call the parent. + * + * @author Brad Anderson <javalizard@gmail.com> + * @package System.Collections + * @since 3.2a + */ +class TPriorityList extends TList +{ + /** + * @var array internal data storage + */ + private $_d=array(); + /** + * @var boolean indicates if the _d is currently ordered. + */ + private $_o=false; + /** + * @var array cached flattened internal data storage + */ + private $_fd=null; + /** + * @var integer number of items contain within the list + */ + private $_c=0; + /** + * @var numeric the default priority of items without specified priorities + */ + private $_dp=10; + /** + * @var integer the precision of the numeric priorities within this priority list. + */ + private $_p=8; + + /** + * Constructor. + * Initializes the list with an array or an iterable object. + * @param array|Iterator the intial data. Default is null, meaning no initial data. + * @param boolean whether the list is read-only + * @param numeric the default priority of items without specified priorities. + * @param integer the precision of the numeric priorities + * @throws TInvalidDataTypeException If data is not null and is neither an array nor an iterator. + */ + public function __construct($data=null,$readOnly=false,$defaultPriority=10,$precision=8) + { + parent::__construct(); + if($data!==null) + $this->copyFrom($data); + $this->setReadOnly($readOnly); + $this->setPrecision($precision); + $this->setDefaultPriority($defaultPriority); + } + + /** + * Returns the number of items in the list. + * This method is required by Countable interface. + * @return integer number of items in the list. + */ + public function count() + { + return $this->getCount(); + } + + /** + * Returns the total number of items in the list + * @return integer the number of items in the list + */ + public function getCount() + { + return $this->_c; + } + + /** + * Gets the number of items at a priority within the list + * @param numeric optional priority at which to count items. if no parameter, it will be set to the default {@link getDefaultPriority} + * @return integer the number of items in the list at the specified priority + */ + public function getPriorityCount($priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + if(!isset($this->_d[$priority]) || !is_array($this->_d[$priority])) + return false; + return count($this->_d[$priority]); + } + + /** + * @return numeric gets the default priority of inserted items without a specified priority + */ + public function getDefaultPriority() + { + return $this->_dp; + } + + /** + * This must be called internally or when instantiated. + * @param numeric sets the default priority of inserted items without a specified priority + */ + protected function setDefaultPriority($value) + { + $this->_dp=(string)round(TPropertyValue::ensureFloat($value),$this->_p); + } + + /** + * @return integer The precision of numeric priorities, defaults to 8 + */ + public function getPrecision() + { + return $this->_p; + } + + /** + * This must be called internally or when instantiated. + * @param integer The precision of numeric priorities. + */ + protected function setPrecision($value) + { + $this->_p=TPropertyValue::ensureInteger($value); + } + + /** + * Returns an iterator for traversing the items in the list. + * This method is required by the interface IteratorAggregate. + * @return Iterator an iterator for traversing the items in the list. + */ + public function getIterator() + { + return new ArrayIterator($this->flattenPriorities()); + } + + /** + * This returns a list of the priorities within this list, ordered lowest to highest. + * @return array the array of priority numerics in decreasing priority order + */ + public function getPriorities() + { + $this->sortPriorities(); + return array_keys($this->_d); + } + + + /** + * This orders the priority list internally. + */ + protected function sortPriorities() { + if(!$this->_o) { + ksort($this->_d,SORT_NUMERIC); + $this->_o=true; + } + } + + /** + * This flattens the priority list into a flat array [0,...,n-1] + * @return array array of items in the list in priority and index order + */ + protected function flattenPriorities() { + if(is_array($this->_fd)) + return $this->_fd; + + $this->sortPriorities(); + $this->_fd=array(); + foreach($this->_d as $priority => $itemsatpriority) + $this->_fd=array_merge($this->_fd,$itemsatpriority); + return $this->_fd; + } + + + /** + * Returns the item at the index of a flattened priority list. + * {@link offsetGet} calls this method. + * @param integer the index of the item to get + * @return mixed the element at the offset + * @throws TInvalidDataValueException Issued when the index is invalid + */ + public function itemAt($index) + { + if($index>=0&&$index<$this->getCount()) { + $arr=$this->flattenPriorities(); + return $arr[$index]; + } else + throw new TInvalidDataValueException('list_index_invalid',$index); + } + + /** + * Gets all the items at a specific priority. + * @param numeric priority of the items to get. Defaults to null, filled in with the default priority, if left blank. + * @return array all items at priority in index order, null if there are no items at that priority + */ + public function itemsAtPriority($priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + return isset($this->_d[$priority])?$this->_d[$priority]:null; + } + + /** + * Returns the item at an index within a priority + * @param integer the index into the list of items at priority + * @param numeric the priority which to index. no parameter or null will result in the default priority + * @return mixed the element at the offset, false if no element is found at the offset + */ + public function itemAtIndexInPriority($index,$priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority), $this->_p); + + return !isset($this->_d[$priority])?false:( + isset($this->_d[$priority][$index])?$this->_d[$priority][$index]:false + ); + } + + /** + * Appends an item into the list at the end of the specified priority. The position of the added item may + * not be at the end of the list. + * @param mixed item to add into the list at priority + * @param numeric priority blank or null for the default priority + * @return int the index within the flattened array + * @throws TInvalidOperationException if the map is read-only + */ + public function add($item,$priority=null) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + return $this->insertAtIndexInPriority($item,false,$priority,true); + } + + /** + * Inserts an item at an index. It reads the priority of the item at index within the flattened list + * and then inserts the item at that priority-index. + * @param integer the specified position in the flattened list. + * @param mixed new item to add + * @throws TInvalidDataValueException If the index specified exceeds the bound + * @throws TInvalidOperationException if the list is read-only + */ + public function insertAt($index,$item) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if(($priority=$this->priorityAt($index,true))!==false) + $this->insertAtIndexInPriority($item,$priority[1],$priority[0]); + else + throw new TInvalidDataValueException('list_index_invalid',$index); + } + + /** + * Inserts an item at the specified index within a priority. Override and call this method to + * insert your own functionality. + * @param mixed item to add within the list. + * @param integer index within the priority to add the item, defaults to false which appends the item at the priority + * @param numeric priority priority of the item. defaults to null, which sets it to the default priority + * @param boolean preserveCache specifies if this is a special quick function or not. This defaults to false. + * @throws TInvalidDataValueException If the index specified exceeds the bound + * @throws TInvalidOperationException if the list is read-only + */ + public function insertAtIndexInPriority($item,$index=false,$priority=null,$preserveCache=false) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority), $this->_p); + + if($preserveCache) { + $this->sortPriorities(); + $cc=0; + foreach($this->_d as $prioritykey=>$items) + if($prioritykey>=$priority) + break; + else + $cc+=count($items); + + if($index===false&&isset($this->_d[$priority])) { + $c=count($this->_d[$priority]); + $c+=$cc; + $this->_d[$priority][]=$item; + } else if(isset($this->_d[$priority])) { + $c=$index+$cc; + array_splice($this->_d[$priority],$index,0,array($item)); + } else { + $c = $cc; + $this->_o = false; + $this->_d[$priority]=array($item); + } + + if($this->_fd&&is_array($this->_fd)) // if there is a flattened array cache + array_splice($this->_fd,$c,0,array($item)); + } else { + $c=null; + if($index===false&&isset($this->_d[$priority])) { + $cc=count($this->_d[$priority]); + $this->_d[$priority][]=$item; + } else if(isset($this->_d[$priority])) { + $cc=$index; + array_splice($this->_d[$priority],$index,0,array($item)); + } else { + $cc=0; + $this->_o=false; + $this->_d[$priority]=array($item); + } + if($this->_fd&&is_array($this->_fd)&&count($this->_d)==1) + array_splice($this->_fd,$cc,0,array($item)); + else + $this->_fd=null; + } + + $this->_c++; + + return $c; + + } + + + /** + * Removes an item from the priority list. + * The list will search for the item. The first matching item found will be removed from the list. + * @param mixed item the item to be removed. + * @param numeric priority of item to remove. without this parameter it defaults to false. + * A value of false means any priority. null will be filled in with the default priority. + * @return integer index within the flattened list at which the item is being removed + * @throws TInvalidDataValueException If the item does not exist + */ + public function remove($item,$priority=false) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if(($p=$this->priorityOf($item,true))!==false) + { + if($priority!==false) { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + if($p[0]!=$priority) + throw new TInvalidDataValueException('list_item_inexistent'); + } + $this->removeAtIndexInPriority($p[1],$p[0]); + return $p[2]; + } + else + throw new TInvalidDataValueException('list_item_inexistent'); + } + + /** + * Removes an item at the specified index in the flattened list. + * @param integer index of the item to be removed. + * @return mixed the removed item. + * @throws TInvalidDataValueException If the index specified exceeds the bound + * @throws TInvalidOperationException if the list is read-only + */ + public function removeAt($index) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if(($priority=$this->priorityAt($index, true))!==false) + return $this->removeAtIndexInPriority($priority[1],$priority[0]); + throw new TInvalidDataValueException('list_index_invalid',$index); + } + + /** + * Removes the item at a specific index within a priority. Override + * and call this method to insert your own functionality. + * @param integer index of item to remove within the priority. + * @param numeric priority of the item to remove, defaults to null, or left blank, it is then set to the default priority + * @return mixed the removed item. + * @throws TInvalidDataValueException If the item does not exist + */ + public function removeAtIndexInPriority($index, $priority=null) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + if(!isset($this->_d[$priority])||$index<0||$index>=count($this->_d[$priority])) + throw new TInvalidDataValueException('list_item_inexistent'); + + // $value is an array of elements removed, only one + $value=array_splice($this->_d[$priority],$index,1); + $value=$value[0]; + + if(!count($this->_d[$priority])) + unset($this->_d[$priority]); + + $this->_c--; + $this->_fd=null; + return $value; + } + + /** + * Removes all items in the priority list by calling removeAtIndexInPriority from the last item to the first. + */ + public function clear() + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + $d=array_reverse($this->_d,true); + foreach($this->_d as $priority=>$items) { + for($index=count($items)-1;$index>=0;$index--) + $this->removeAtIndexInPriority($index,$priority); + unset($this->_d[$priority]); + } + } + + /** + * @param mixed item + * @return boolean whether the list contains the item + */ + public function contains($item) + { + return $this->indexOf($item)>=0; + } + + /** + * @param mixed item + * @return integer the index of the item in the flattened list (0 based), -1 if not found. + */ + public function indexOf($item) + { + if(($index=array_search($item,$this->flattenPriorities(),true))===false) + return -1; + else + return $index; + } + + /** + * Returns the priority of a particular item + * @param mixed the item to look for within the list + * @param boolean withindex this specifies if the full positional data of the item within the list is returned. + * This defaults to false, if no parameter is provided, so only provides the priority number of the item by default. + * @return numeric|array the priority of the item in the list, false if not found. + * if withindex is true, an array is returned of [0 => $priority, 1 => $priorityIndex, 2 => flattenedIndex, + * 'priority' => $priority, 'index' => $priorityIndex, 'absindex' => flattenedIndex] + */ + public function priorityOf($item,$withindex = false) + { + $this->sortPriorities(); + + $absindex = 0; + foreach($this->_d as $priority=>$items) { + if(($index=array_search($item,$items,true))!==false) { + $absindex+=$index; + return $withindex?array($priority,$index,$absindex, + 'priority'=>$priority,'index'=>$index,'absindex'=>$absindex):$priority; + } else + $absindex+=count($items); + } + + return false; + } + + /** + * Retutrns the priority of an item at a particular flattened index. + * @param integer index of the item within the list + * @param boolean withindex this specifies if the full positional data of the item within the list is returned. + * This defaults to false, if no parameter is provided, so only provides the priority number of the item by default. + * @return numeric|array the priority of the item in the list, false if not found. + * if withindex is true, an array is returned of [0 => $priority, 1 => $priorityIndex, 2 => flattenedIndex, + * 'priority' => $priority, 'index' => $priorityIndex, 'absindex' => flattenedIndex] + */ + public function priorityAt($index,$withindex = false) + { + if($index<0||$index>=$this->getCount()) + throw new TInvalidDataValueException('list_index_invalid',$index); + + $absindex=$index; + $this->sortPriorities(); + foreach($this->_d as $priority=>$items) { + if($index>=($c=count($items))) + $index-=$c; + else + return $withindex?array($priority,$index,$absindex, + 'priority'=>$priority,'index'=>$index,'absindex'=>$absindex):$priority; + } + return false; + } + + /** + * This inserts an item before another item within the list. It uses the same priority as the + * found index item and places the new item before it. + * @param mixed indexitem the item to index + * @param mixed the item to add before indexitem + * @return integer where the item has been inserted in the flattened list + * @throws TInvalidDataValueException If the item does not exist + */ + public function insertBefore($indexitem, $item) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if(($priority=$this->priorityOf($indexitem,true))===false) + throw new TInvalidDataValueException('list_item_inexistent'); + + $this->insertAtIndexInPriority($item,$priority[1],$priority[0]); + + return $priority[2]; + } + + /** + * This inserts an item after another item within the list. It uses the same priority as the + * found index item and places the new item after it. + * @param mixed indexitem the item to index + * @param mixed the item to add after indexitem + * @return integer where the item has been inserted in the flattened list + * @throws TInvalidDataValueException If the item does not exist + */ + public function insertAfter($indexitem, $item) + { + if($this->getReadOnly()) + throw new TInvalidOperationException('list_readonly',get_class($this)); + + if(($priority=$this->priorityOf($indexitem,true))===false) + throw new TInvalidDataValueException('list_item_inexistent'); + + $this->insertAtIndexInPriority($item,$priority[1]+1,$priority[0]); + + return $priority[2]+1; + } + + /** + * @return array the priority list of items in array + */ + public function toArray() + { + return $this->flattenPriorities(); + } + + /** + * @return array the array of priorities keys with values of arrays of items. The priorities are sorted so important priorities, lower numerics, are first. + */ + public function toPriorityArray() + { + $this->sortPriorities(); + return $this->_d; + } + + /** + * Combines the map elements which have a priority below the parameter value + * @param numeric the cut-off priority. All items of priority less than this are returned. + * @param boolean whether or not the input cut-off priority is inclusive. Default: false, not inclusive. + * @return array the array of priorities keys with values of arrays of items that are below a specified priority. + * The priorities are sorted so important priorities, lower numerics, are first. + */ + public function toArrayBelowPriority($priority,$inclusive=false) + { + $this->sortPriorities(); + $items=array(); + foreach($this->_d as $itemspriority=>$itemsatpriority) + { + if((!$inclusive&&$itemspriority>=$priority)||$itemspriority>$priority) + break; + $items=array_merge($items,$itemsatpriority); + } + return $items; + } + + /** + * Combines the map elements which have a priority above the parameter value + * @param numeric the cut-off priority. All items of priority greater than this are returned. + * @param boolean whether or not the input cut-off priority is inclusive. Default: true, inclusive. + * @return array the array of priorities keys with values of arrays of items that are above a specified priority. + * The priorities are sorted so important priorities, lower numerics, are first. + */ + public function toArrayAbovePriority($priority,$inclusive=true) + { + $this->sortPriorities(); + $items=array(); + foreach($this->_d as $itemspriority=>$itemsatpriority) + { + if((!$inclusive&&$itemspriority<=$priority)||$itemspriority<$priority) + continue; + $items=array_merge($items,$itemsatpriority); + } + return $items; + } + + + /** + * Copies iterable data into the priority list. + * Note, existing data in the map will be cleared first. + * @param mixed the data to be copied from, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function copyFrom($data) + { + if($data instanceof TPriorityList) + { + if($this->getCount()>0) + $this->clear(); + foreach($data->getPriorities() as $priority) + { + foreach($data->itemsAtPriority($priority) as $index=>$item) + $this->insertAtIndexInPriority($item,$index,$priority); + } + } else if(is_array($data)||$data instanceof Traversable) { + if($this->getCount()>0) + $this->clear(); + foreach($data as $key=>$item) + $this->add($item); + } else if($data!==null) + throw new TInvalidDataTypeException('map_data_not_iterable'); + } + + /** + * Merges iterable data into the priority list. + * New data will be appended to the end of the existing data. If another TPriorityList is merged, + * the incoming parameter items will be appended at the priorities they are present. These items will be added + * to the end of the existing items with equal priorities, if there are any. + * @param mixed the data to be merged with, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function mergeWith($data) + { + if($data instanceof TPriorityList) + { + foreach($data->getPriorities() as $priority) + { + foreach($data->itemsAtPriority($priority) as $index=>$item) + $this->insertAtIndexInPriority($item,false,$priority); + } + } + else if(is_array($data)||$data instanceof Traversable) + { + foreach($data as $priority=>$item) + $this->add($item); + + } + else if($data!==null) + throw new TInvalidDataTypeException('map_data_not_iterable'); + } + + /** + * Returns whether there is an element at the specified offset. + * This method is required by the interface ArrayAccess. + * @param mixed the offset to check on + * @return boolean + */ + public function offsetExists($offset) + { + return ($offset>=0&&$offset<$this->getCount()); + } + + /** + * Returns the element at the specified offset. + * This method is required by the interface ArrayAccess. + * @param integer 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. + * Setting elements in a priority list is not straight forword when appending and setting at the + * end boundary. When appending without an offset (a null offset), the item will be added at + * the default priority. The item may not be the last item in the list. When appending with an + * offset equal to the count of the list, the item will get be appended with the last items priority. + * + * All together, when setting the location of an item, the item stays in that location, but appending + * an item into a priority list doesn't mean the item is at the end of the list. + * @param integer the offset to set element + * @param mixed the element value + */ + public function offsetSet($offset,$item) + { + if($offset===null) + return $this->add($item); + if($offset===$this->getCount()) { + $priority=$this->priorityAt($offset-1,true); + $priority[1]++; + } else { + $priority=$this->priorityAt($offset,true); + $this->removeAtIndexInPriority($priority[1],$priority[0]); + } + $this->insertAtIndexInPriority($item,$priority[1],$priority[0]); + } + + /** + * Unsets the element at the specified offset. + * This method is required by the interface ArrayAccess. + * @param mixed the offset to unset element + */ + public function offsetUnset($offset) + { + $this->removeAt($offset); + } +} diff --git a/lib/prado/framework/Collections/TPriorityMap.php b/lib/prado/framework/Collections/TPriorityMap.php new file mode 100644 index 0000000..9af10da --- /dev/null +++ b/lib/prado/framework/Collections/TPriorityMap.php @@ -0,0 +1,604 @@ +<?php +/** + * TPriorityMap, TPriorityMapIterator classes + * + * @author Brad Anderson <javalizard@mac.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TPriorityMap class + * + * TPriorityMap implements a collection that takes key-value pairs with + * a priority to allow key-value pairs to be ordered. This ordering is + * important when flattening the map. When flattening the map, if some + * key-value pairs are required to be before or after others, use this + * class to keep order to your map. + * + * You can access, add or remove an item with a key by using + * {@link itemAt}, {@link add}, and {@link remove}. These functions + * can optionally take a priority parameter to allow access to specific + * priorities. TPriorityMap is functionally backward compatible + * with {@link TMap}. + * + * To get the number of the items in the map, use {@link getCount}. + * TPriorityMap can also be used like a regular array as follows, + * <code> + * $map[$key]=$value; // add a key-value pair + * unset($map[$key]); // remove the value with the specified key + * if(isset($map[$key])) // if the map contains the key + * foreach($map as $key=>$value) // traverse the items in the map + * $n=count($map); // returns the number of items in the map + * </code> + * Using standard array access method like these will always use + * the default priority. + * + * An item that doesn't specify a priority will receive the default + * priority. The default priority is set during the instantiation + * of a new TPriorityMap. If no custom default priority is specified, + * the standard default priority of 10 is used. + * + * Priorities with significant digits below precision will be rounded. + * + * A priority may also be a numeric with decimals. This is set + * during the instantiation of a new TPriorityMap. + * The default is 8 decimal places for a priority. If a negative number + * is used, rounding occurs into the integer space rather than in + * the decimal space. See {@link round}. + * + * @author Brad Anderson <javalizard@mac.com> + * @package System.Collections + * @since 3.2a + */ +Prado::using('System.Collections.TMap'); + +class TPriorityMap extends TMap +{ + /** + * @var array internal data storage + */ + private $_d=array(); + /** + * @var boolean whether this list is read-only + */ + private $_r=false; + /** + * @var boolean indicates if the _d is currently ordered. + */ + private $_o=false; + /** + * @var array cached flattened internal data storage + */ + private $_fd=null; + /** + * @var integer number of items contain within the map + */ + private $_c=0; + /** + * @var numeric the default priority of items without specified priorities + */ + private $_dp=10; + /** + * @var integer the precision of the numeric priorities within this priority list. + */ + private $_p=8; + + /** + * Constructor. + * Initializes the array with an array or an iterable object. + * @param map|array|Iterator|TPriorityMap the intial data. Default is null, meaning no initialization. + * @param boolean whether the list is read-only + * @param numeric the default priority of items without specified priorities. + * @param integer the precision of the numeric priorities + * @throws TInvalidDataTypeException If data is not null and neither an array nor an iterator. + */ + public function __construct($data=null,$readOnly=false,$defaultPriority=10,$precision=8) + { + if($data!==null) + $this->copyFrom($data); + $this->setReadOnly($readOnly); + $this->setPrecision($precision); + $this->setDefaultPriority($defaultPriority); + } + + /** + * @return boolean whether this map is read-only or not. Defaults to false. + */ + public function getReadOnly() + { + return $this->_r; + } + + /** + * @param boolean whether this list is read-only or not + */ + protected function setReadOnly($value) + { + $this->_r=TPropertyValue::ensureBoolean($value); + } + + /** + * @return numeric gets the default priority of inserted items without a specified priority + */ + public function getDefaultPriority() + { + return $this->_dp; + } + + /** + * This must be called internally or when instantiated. + * @param numeric sets the default priority of inserted items without a specified priority + */ + protected function setDefaultPriority($value) + { + $this->_dp = (string)round(TPropertyValue::ensureFloat($value), $this->_p); + } + + /** + * @return integer The precision of numeric priorities, defaults to 8 + */ + public function getPrecision() + { + return $this->_p; + } + + /** + * This must be called internally or when instantiated. + * @param integer The precision of numeric priorities. + */ + protected function setPrecision($value) + { + $this->_p=TPropertyValue::ensureInteger($value); + } + + /** + * Returns an iterator for traversing the items in the map. + * This method is required by the interface IteratorAggregate. + * @return Iterator an iterator for traversing the items in the map. + */ + public function getIterator() + { + return new ArrayIterator($this->flattenPriorities()); + } + + + /** + * Orders the priority list internally. + */ + protected function sortPriorities() { + if(!$this->_o) { + ksort($this->_d, SORT_NUMERIC); + $this->_o=true; + } + } + + /** + * This flattens the priority map into a flat array [0,...,n-1] + * @return array array of items in the list in priority and index order + */ + protected function flattenPriorities() { + if(is_array($this->_fd)) + return $this->_fd; + + $this->sortPriorities(); + $this->_fd = array(); + foreach($this->_d as $priority => $itemsatpriority) + $this->_fd = array_merge($this->_fd, $itemsatpriority); + return $this->_fd; + } + + /** + * Returns the number of items in the map. + * This method is required by Countable interface. + * @return integer number of items in the map. + */ + public function count() + { + return $this->getCount(); + } + + /** + * @return integer the number of items in the map + */ + public function getCount() + { + return $this->_c; + } + + /** + * Gets the number of items at a priority within the map. + * @param numeric optional priority at which to count items. if no parameter, + * it will be set to the default {@link getDefaultPriority} + * @return integer the number of items in the map at the specified priority + */ + public function getPriorityCount($priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + if(!isset($this->_d[$priority])||!is_array($this->_d[$priority])) + return false; + return count($this->_d[$priority]); + } + + /** + * This returns a list of the priorities within this map, ordered lowest to highest. + * @return array the array of priority numerics in decreasing priority order + */ + public function getPriorities() + { + $this->sortPriorities(); + return array_keys($this->_d); + } + + /** + * Returns the keys within the map ordered through the priority of each key-value pair + * @return array the key list + */ + public function getKeys() + { + return array_keys($this->flattenPriorities()); + } + + /** + * Returns the item with the specified key. If a priority is specified, only items + * within that specific priority will be selected + * @param mixed the key + * @param mixed the priority. null is the default priority, false is any priority, + * and numeric is a specific priority. default: false, any priority. + * @return mixed the element at the offset, null if no element is found at the offset + */ + public function itemAt($key,$priority=false) + { + if($priority===false){ + $map=$this->flattenPriorities(); + return isset($map[$key])?$map[$key]:null; + } else { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + return (isset($this->_d[$priority])&&isset($this->_d[$priority][$key]))?$this->_d[$priority][$key]:null; + } + } + + /** + * This changes an item's priority. Specify the item and the new priority. + * This method is exactly the same as {@link offsetGet}. + * @param mixed the key + * @param numeric|null the priority. default: null, filled in with the default priority numeric. + * @return numeric old priority of the item + */ + public function setPriorityAt($key,$priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + $oldpriority=$this->priorityAt($key); + if($oldpriority!==false&&$oldpriority!=$priority) { + $value=$this->remove($key,$oldpriority); + $this->add($key,$value,$priority); + } + return $oldpriority; + } + + /** + * Gets all the items at a specific priority. + * @param numeric priority of the items to get. Defaults to null, filled in with the default priority, if left blank. + * @return array all items at priority in index order, null if there are no items at that priority + */ + public function itemsAtPriority($priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + return isset($this->_d[$priority])?$this->_d[$priority]:null; + } + + /** + * Returns the priority of a particular item within the map. This searches the map for the item. + * @param mixed item to look for within the map + * @return numeric priority of the item in the map + */ + public function priorityOf($item) + { + $this->sortPriorities(); + foreach($this->_d as $priority=>$items) + if(($index=array_search($item,$items,true))!==false) + return $priority; + return false; + } + + /** + * Retutrns the priority of an item at a particular flattened index. + * @param integer index of the item within the map + * @return numeric priority of the item in the map + */ + public function priorityAt($key) + { + $this->sortPriorities(); + foreach($this->_d as $priority=>$items) + if(array_key_exists($key,$items)) + return $priority; + return false; + } + + /** + * Adds an item into the map. A third parameter may be used to set the priority + * of the item within the map. Priority is primarily used during when flattening + * the map into an array where order may be and important factor of the key-value + * pairs within the array. + * Note, if the specified key already exists, the old value will be overwritten. + * No duplicate keys are allowed regardless of priority. + * @param mixed key + * @param mixed value + * @param numeric|null priority, default: null, filled in with default priority + * @return numeric priority at which the pair was added + * @throws TInvalidOperationException if the map is read-only + */ + public function add($key,$value,$priority=null) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + + if(!$this->_r) + { + foreach($this->_d as $innerpriority=>$items) + if(array_key_exists($key,$items)) + { + unset($this->_d[$innerpriority][$key]); + $this->_c--; + if(count($this->_d[$innerpriority])===0) + unset($this->_d[$innerpriority]); + } + if(!isset($this->_d[$priority])) { + $this->_d[$priority]=array($key=>$value); + $this->_o=false; + } + else + $this->_d[$priority][$key]=$value; + $this->_c++; + $this->_fd=null; + } + else + throw new TInvalidOperationException('map_readonly',get_class($this)); + return $priority; + } + + /** + * Removes an item from the map by its key. If no priority, or false, is specified + * then priority is irrelevant. If null is used as a parameter for priority, then + * the priority will be the default priority. If a priority is specified, or + * the default priority is specified, only key-value pairs in that priority + * will be affected. + * @param mixed the key of the item to be removed + * @param numeric|false|null priority. False is any priority, null is the + * default priority, and numeric is a specific priority + * @return mixed the removed value, null if no such key exists. + * @throws TInvalidOperationException if the map is read-only + */ + public function remove($key,$priority=false) + { + if(!$this->_r) + { + if($priority===null) + $priority=$this->getDefaultPriority(); + + if($priority===false) + { + $this->sortPriorities(); + foreach($this->_d as $priority=>$items) + if(array_key_exists($key,$items)) + { + $value=$this->_d[$priority][$key]; + unset($this->_d[$priority][$key]); + $this->_c--; + if(count($this->_d[$priority])===0) + { + unset($this->_d[$priority]); + $this->_o=false; + } + $this->_fd=null; + return $value; + } + return null; + } + else + { + $priority=(string)round(TPropertyValue::ensureFloat($priority),$this->_p); + if(isset($this->_d[$priority])&&(isset($this->_d[$priority][$key])||array_key_exists($key,$this->_d[$priority]))) + { + $value=$this->_d[$priority][$key]; + unset($this->_d[$priority][$key]); + $this->_c--; + if(count($this->_d[$priority])===0) { + unset($this->_d[$priority]); + $this->_o=false; + } + $this->_fd=null; + return $value; + } + else + return null; + } + } + else + throw new TInvalidOperationException('map_readonly',get_class($this)); + } + + /** + * Removes all items in the map. {@link remove} is called on all items. + */ + public function clear() + { + foreach($this->_d as $priority=>$items) + foreach(array_keys($items) as $key) + $this->remove($key); + } + + /** + * @param mixed the key + * @return boolean whether the map contains an item with the specified key + */ + public function contains($key) + { + $map=$this->flattenPriorities(); + return isset($map[$key])||array_key_exists($key,$map); + } + + /** + * When the map is flattened into an array, the priorities are taken into + * account and elements of the map are ordered in the array according to + * their priority. + * @return array the list of items in array + */ + public function toArray() + { + return $this->flattenPriorities(); + } + + /** + * Combines the map elements which have a priority below the parameter value + * @param numeric the cut-off priority. All items of priority less than this are returned. + * @param boolean whether or not the input cut-off priority is inclusive. Default: false, not inclusive. + * @return array the array of priorities keys with values of arrays of items that are below a specified priority. + * The priorities are sorted so important priorities, lower numerics, are first. + */ + public function toArrayBelowPriority($priority,$inclusive=false) + { + $this->sortPriorities(); + $items=array(); + foreach($this->_d as $itemspriority=>$itemsatpriority) + { + if((!$inclusive&&$itemspriority>=$priority)||$itemspriority>$priority) + break; + $items=array_merge($items,$itemsatpriority); + } + return $items; + } + + /** + * Combines the map elements which have a priority above the parameter value + * @param numeric the cut-off priority. All items of priority greater than this are returned. + * @param boolean whether or not the input cut-off priority is inclusive. Default: true, inclusive. + * @return array the array of priorities keys with values of arrays of items that are above a specified priority. + * The priorities are sorted so important priorities, lower numerics, are first. + */ + public function toArrayAbovePriority($priority,$inclusive=true) + { + $this->sortPriorities(); + $items=array(); + foreach($this->_d as $itemspriority=>$itemsatpriority) + { + if((!$inclusive&&$itemspriority<=$priority)||$itemspriority<$priority) + continue; + $items=array_merge($items,$itemsatpriority); + } + return $items; + } + + /** + * Copies iterable data into the map. + * Note, existing data in the map will be cleared first. + * @param mixed the data to be copied from, must be an array, object implementing + * Traversable, or a TPriorityMap + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function copyFrom($data) + { + if($data instanceof TPriorityMap) + { + if($this->getCount()>0) + $this->clear(); + foreach($data->getPriorities() as $priority) { + foreach($data->itemsAtPriority($priority) as $key => $value) { + $this->add($key,$value,$priority); + } + } + } + else if(is_array($data)||$data instanceof Traversable) + { + if($this->getCount()>0) + $this->clear(); + foreach($data as $key=>$value) + $this->add($key,$value); + } + else if($data!==null) + throw new TInvalidDataTypeException('map_data_not_iterable'); + } + + /** + * Merges iterable data into the map. + * Existing data in the map will be kept and overwritten if the keys are the same. + * @param mixed the data to be merged with, must be an array, object implementing + * Traversable, or a TPriorityMap + * @throws TInvalidDataTypeException If data is neither an array nor an iterator. + */ + public function mergeWith($data) + { + if($data instanceof TPriorityMap) + { + foreach($data->getPriorities() as $priority) + { + foreach($data->itemsAtPriority($priority) as $key => $value) + $this->add($key,$value,$priority); + } + } + else if(is_array($data)||$data instanceof Traversable) + { + foreach($data as $key=>$value) + $this->add($key,$value); + } + else if($data!==null) + throw new TInvalidDataTypeException('map_data_not_iterable'); + } + + /** + * Returns whether there is an element at the specified offset. + * This method is required by the interface ArrayAccess. + * @param mixed 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 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 the offset to set element + * @param mixed 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 the offset to unset element + */ + public function offsetUnset($offset) + { + $this->remove($offset); + } +}
\ No newline at end of file diff --git a/lib/prado/framework/Collections/TQueue.php b/lib/prado/framework/Collections/TQueue.php new file mode 100644 index 0000000..6c989e2 --- /dev/null +++ b/lib/prado/framework/Collections/TQueue.php @@ -0,0 +1,263 @@ +<?php +/** + * TQueue, TQueueIterator classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @version $Id$ + * @package System.Collections + */ + +/** + * TQueue class + * + * TQueue implements a queue. + * + * The typical queue operations are implemented, which include + * {@link enqueue()}, {@link dequeue()} and {@link peek()}. In addition, + * {@link contains()} can be used to check if an item is contained + * in the queue. To obtain the number of the items in the queue, + * check the {@link getCount Count} property. + * + * Items in the queue may be traversed using foreach as follows, + * <code> + * foreach($queue as $item) ... + * </code> + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @author Knut Urdalen <knut.urdalen@gmail.com> + * @version $Id$ + * @package System.Collections + * @since 3.1 + */ +class TQueue extends TComponent implements IteratorAggregate,Countable +{ + /** + * internal data storage + * @var array + */ + private $_d=array(); + /** + * number of items + * @var integer + */ + private $_c=0; + + /** + * Constructor. + * Initializes the queue with an array or an iterable object. + * @param array|Iterator the intial data. Default is null, meaning no initialization. + * @throws TInvalidDataTypeException If data is not null and neither an array nor an iterator. + */ + public function __construct($data=null) + { + if($data!==null) + $this->copyFrom($data); + } + + /** + * @return array the list of items in queue + */ + public function toArray() + { + return $this->_d; + } + + /** + * Copies iterable data into the queue. + * Note, existing data in the list will be cleared first. + * @param mixed the data to be copied from, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor a Traversable. + */ + public function copyFrom($data) + { + if(is_array($data) || ($data instanceof Traversable)) + { + $this->clear(); + foreach($data as $item) + { + $this->_d[]=$item; + ++$this->_c; + } + } + else if($data!==null) + throw new TInvalidDataTypeException('queue_data_not_iterable'); + } + + /** + * Removes all items in the queue. + */ + public function clear() + { + $this->_c=0; + $this->_d=array(); + } + + /** + * @param mixed the item + * @return boolean whether the queue contains the item + */ + public function contains($item) + { + return array_search($item,$this->_d,true)!==false; + } + + /** + * Returns the first item at the front of the queue. + * Unlike {@link dequeue()}, this method does not remove the item from the queue. + * @return mixed item at the top of the queue + * @throws TInvalidOperationException if the queue is empty + */ + public function peek() + { + if($this->_c===0) + throw new TInvalidOperationException('queue_empty'); + else + return $this->_d[0]; + } + + /** + * Removes and returns the object at the beginning of the queue. + * @return mixed the item at the beginning of the queue + * @throws TInvalidOperationException if the queue is empty + */ + public function dequeue() + { + if($this->_c===0) + throw new TInvalidOperationException('queue_empty'); + else + { + --$this->_c; + return array_shift($this->_d); + } + } + + /** + * Adds an object to the end of the queue. + * @param mixed the item to be appended into the queue + */ + public function enqueue($item) + { + ++$this->_c; + $this->_d[] = $item; + } + + /** + * Returns an iterator for traversing the items in the queue. + * This method is required by the interface IteratorAggregate. + * @return Iterator an iterator for traversing the items in the queue. + */ + public function getIterator() + { + return new ArrayIterator( $this->_d ); + } + + /** + * @return integer the number of items in the queue + */ + public function getCount() + { + return $this->_c; + } + + /** + * Returns the number of items in the queue. + * This method is required by Countable interface. + * @return integer number of items in the queue. + */ + public function count() + { + return $this->getCount(); + } +} + +/** + * TQueueIterator class + * + * TQueueIterator implements Iterator interface. + * + * TQueueIterator is used by TQueue. It allows TQueue to return a new iterator + * for traversing the items in the queue. + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @version $Id$ + * @package System.Collections + * @since 3.1 + */ +class TQueueIterator implements Iterator +{ + /** + * @var array the data to be iterated through + */ + private $_d; + /** + * @var integer index of the current item + */ + private $_i; + /** + * @var integer count of the data items + */ + private $_c; + + /** + * Constructor. + * @param array the data to be iterated through + */ + public function __construct(&$data) + { + $this->_d=&$data; + $this->_i=0; + $this->_c=count($this->_d); + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_i=0; + } + + /** + * Returns the key of the current array item. + * This method is required by the interface Iterator. + * @return integer the key of the current array item + */ + public function key() + { + return $this->_i; + } + + /** + * Returns the current array item. + * This method is required by the interface Iterator. + * @return mixed the current array item + */ + public function current() + { + return $this->_d[$this->_i]; + } + + /** + * Moves the internal pointer to the next array item. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_i++; + } + + /** + * Returns whether there is an item at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_i<$this->_c; + } +} + diff --git a/lib/prado/framework/Collections/TStack.php b/lib/prado/framework/Collections/TStack.php new file mode 100644 index 0000000..de78527 --- /dev/null +++ b/lib/prado/framework/Collections/TStack.php @@ -0,0 +1,260 @@ +<?php +/** + * TStack, TStackIterator classes + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @link https://github.com/pradosoft/prado + * @copyright Copyright © 2005-2015 The PRADO Group + * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT + * @package System.Collections + */ + +/** + * TStack class + * + * TStack implements a stack. + * + * The typical stack operations are implemented, which include + * {@link push()}, {@link pop()} and {@link peek()}. In addition, + * {@link contains()} can be used to check if an item is contained + * in the stack. To obtain the number of the items in the stack, + * check the {@link getCount Count} property. + * + * Items in the stack may be traversed using foreach as follows, + * <code> + * foreach($stack as $item) ... + * </code> + * + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TStack extends TComponent implements IteratorAggregate,Countable +{ + /** + * internal data storage + * @var array + */ + private $_d=array(); + /** + * number of items + * @var integer + */ + private $_c=0; + + /** + * Constructor. + * Initializes the stack with an array or an iterable object. + * @param array|Iterator the initial data. Default is null, meaning no initialization. + * @throws TInvalidDataTypeException If data is not null and neither an array nor an iterator. + */ + public function __construct($data=null) + { + if($data!==null) + $this->copyFrom($data); + } + + /** + * @return array the list of items in stack + */ + public function toArray() + { + return $this->_d; + } + + /** + * Copies iterable data into the stack. + * Note, existing data in the list will be cleared first. + * @param mixed the data to be copied from, must be an array or object implementing Traversable + * @throws TInvalidDataTypeException If data is neither an array nor a Traversable. + */ + public function copyFrom($data) + { + if(is_array($data) || ($data instanceof Traversable)) + { + $this->clear(); + foreach($data as $item) + { + $this->_d[]=$item; + ++$this->_c; + } + } + else if($data!==null) + throw new TInvalidDataTypeException('stack_data_not_iterable'); + } + + /** + * Removes all items in the stack. + */ + public function clear() + { + $this->_c=0; + $this->_d=array(); + } + + /** + * @param mixed the item + * @return boolean whether the stack contains the item + */ + public function contains($item) + { + return array_search($item,$this->_d,true)!==false; + } + + /** + * Returns the item at the top of the stack. + * Unlike {@link pop()}, this method does not remove the item from the stack. + * @return mixed item at the top of the stack + * @throws TInvalidOperationException if the stack is empty + */ + public function peek() + { + if($this->_c===0) + throw new TInvalidOperationException('stack_empty'); + else + return $this->_d[$this->_c-1]; + } + + /** + * Pops up the item at the top of the stack. + * @return mixed the item at the top of the stack + * @throws TInvalidOperationException if the stack is empty + */ + public function pop() + { + if($this->_c===0) + throw new TInvalidOperationException('stack_empty'); + else + { + --$this->_c; + return array_pop($this->_d); + } + } + + /** + * Pushes an item into the stack. + * @param mixed the item to be pushed into the stack + */ + public function push($item) + { + ++$this->_c; + $this->_d[] = $item; + } + + /** + * Returns an iterator for traversing the items in the stack. + * This method is required by the interface IteratorAggregate. + * @return Iterator an iterator for traversing the items in the stack. + */ + public function getIterator() + { + return new ArrayIterator( $this->_d ); + } + + /** + * @return integer the number of items in the stack + */ + public function getCount() + { + return $this->_c; + } + + /** + * Returns the number of items in the stack. + * This method is required by Countable interface. + * @return integer number of items in the stack. + */ + public function count() + { + return $this->getCount(); + } +} + +/** + * TStackIterator class + * + * TStackIterator implements Iterator interface. + * + * TStackIterator is used by TStack. It allows TStack to return a new iterator + * for traversing the items in the list. + * + * @deprecated Issue 264 : ArrayIterator should be used instead + * @author Qiang Xue <qiang.xue@gmail.com> + * @package System.Collections + * @since 3.0 + */ +class TStackIterator implements Iterator +{ + /** + * @var array the data to be iterated through + */ + private $_d; + /** + * @var integer index of the current item + */ + private $_i; + /** + * @var integer count of the data items + */ + private $_c; + + /** + * Constructor. + * @param array the data to be iterated through + */ + public function __construct(&$data) + { + $this->_d=&$data; + $this->_i=0; + $this->_c=count($this->_d); + } + + /** + * Rewinds internal array pointer. + * This method is required by the interface Iterator. + */ + public function rewind() + { + $this->_i=0; + } + + /** + * Returns the key of the current array item. + * This method is required by the interface Iterator. + * @return integer the key of the current array item + */ + public function key() + { + return $this->_i; + } + + /** + * Returns the current array item. + * This method is required by the interface Iterator. + * @return mixed the current array item + */ + public function current() + { + return $this->_d[$this->_i]; + } + + /** + * Moves the internal pointer to the next array item. + * This method is required by the interface Iterator. + */ + public function next() + { + $this->_i++; + } + + /** + * Returns whether there is an item at current position. + * This method is required by the interface Iterator. + * @return boolean + */ + public function valid() + { + return $this->_i<$this->_c; + } +} + |