From 903ae8a581fac1e6917fc3e31d2ad8fb91df80c3 Mon Sep 17 00:00:00 2001 From: ctrlaltca <> Date: Thu, 12 Jul 2012 11:21:01 +0000 Subject: standardize the use of unix eol; use svn properties to enforce native eol --- framework/Collections/TAttributeCollection.php | 342 +++--- framework/Collections/TDummyDataSource.php | 290 ++--- framework/Collections/TList.php | 972 ++++++++-------- framework/Collections/TListItemCollection.php | 328 +++--- framework/Collections/TMap.php | 704 +++++------ framework/Collections/TPagedDataSource.php | 890 +++++++------- framework/Collections/TPagedList.php | 952 +++++++-------- framework/Collections/TPriorityList.php | 1486 ++++++++++++------------ framework/Collections/TQueue.php | 526 ++++----- framework/Collections/TStack.php | 524 ++++----- 10 files changed, 3507 insertions(+), 3507 deletions(-) (limited to 'framework/Collections') diff --git a/framework/Collections/TAttributeCollection.php b/framework/Collections/TAttributeCollection.php index dd5fa273..85f9b23d 100644 --- a/framework/Collections/TAttributeCollection.php +++ b/framework/Collections/TAttributeCollection.php @@ -1,172 +1,172 @@ - - * @link http://www.pradosoft.com/ + + * @link http://www.pradosoft.com/ * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @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: - * - * $collection->Text='text'; - * echo $collection->Text; - * - * They are equivalent to the following: - * - * $collection->add('Text','text'); - * echo $collection->itemAt('Text'); - * - * - * Note, attribute names are case-insensitive. They are converted to lower-case - * in the collection storage. - * - * @author Qiang Xue - * @version $Id$ - * @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::hasProperty($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; - } -} - + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @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: + * + * $collection->Text='text'; + * echo $collection->Text; + * + * They are equivalent to the following: + * + * $collection->add('Text','text'); + * echo $collection->itemAt('Text'); + * + * + * Note, attribute names are case-insensitive. They are converted to lower-case + * in the collection storage. + * + * @author Qiang Xue + * @version $Id$ + * @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::hasProperty($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/framework/Collections/TDummyDataSource.php b/framework/Collections/TDummyDataSource.php index c63f5d95..c5804b1e 100644 --- a/framework/Collections/TDummyDataSource.php +++ b/framework/Collections/TDummyDataSource.php @@ -1,146 +1,146 @@ - - * @link http://www.pradosoft.com/ + + * @link http://www.pradosoft.com/ * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @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 foreach - * PHP statement like the following, - * - * foreach($dummyDataSource as $dataItem) - * - * - * @author Qiang Xue - * @version $Id$ - * @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 - * @version $Id$ - * @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; - } -} - + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @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 foreach + * PHP statement like the following, + * + * foreach($dummyDataSource as $dataItem) + * + * + * @author Qiang Xue + * @version $Id$ + * @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 + * @version $Id$ + * @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/framework/Collections/TList.php b/framework/Collections/TList.php index 1e4c439c..4ba4fb58 100644 --- a/framework/Collections/TList.php +++ b/framework/Collections/TList.php @@ -1,486 +1,486 @@ - - * @link http://www.pradosoft.com/ - * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @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, - * - * $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 - * - * - * To extend TList by doing additional operations with each addition or removal - * operation, override {@link insertAt()}, and {@link removeAt()}. - * - * @author Qiang Xue - * @version $Id$ - * @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 - * @version $Id$ - * @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; - } -} - + + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2012 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @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, + * + * $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 + * + * + * To extend TList by doing additional operations with each addition or removal + * operation, override {@link insertAt()}, and {@link removeAt()}. + * + * @author Qiang Xue + * @version $Id$ + * @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 + * @version $Id$ + * @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/framework/Collections/TListItemCollection.php b/framework/Collections/TListItemCollection.php index 73158553..13a44bcd 100644 --- a/framework/Collections/TListItemCollection.php +++ b/framework/Collections/TListItemCollection.php @@ -1,164 +1,164 @@ - - * @author Qiang Xue - * @link http://www.pradosoft.com/ - * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id: TListControl.php 2624 2009-03-19 21:20:47Z godzilla80@gmx.net $ - * @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 - * @version $Id: TListControl.php 2624 2009-03-19 21:20:47Z godzilla80@gmx.net $ - * @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; - } -} + + * @author Qiang Xue + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2012 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id: TListControl.php 2624 2009-03-19 21:20:47Z godzilla80@gmx.net $ + * @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 + * @version $Id: TListControl.php 2624 2009-03-19 21:20:47Z godzilla80@gmx.net $ + * @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/framework/Collections/TMap.php b/framework/Collections/TMap.php index 200f9aea..a9e8db9d 100644 --- a/framework/Collections/TMap.php +++ b/framework/Collections/TMap.php @@ -1,353 +1,353 @@ - - * @link http://www.pradosoft.com/ + + * @link http://www.pradosoft.com/ * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @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, - * - * $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 - * - * - * @author Qiang Xue - * @version $Id$ - * @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 - * @version $Id$ - * @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; - } -} + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @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, + * + * $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 + * + * + * @author Qiang Xue + * @version $Id$ + * @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 + * @version $Id$ + * @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/framework/Collections/TPagedDataSource.php b/framework/Collections/TPagedDataSource.php index c0fbbec1..2b5a2909 100644 --- a/framework/Collections/TPagedDataSource.php +++ b/framework/Collections/TPagedDataSource.php @@ -1,446 +1,446 @@ - - * @link http://www.pradosoft.com/ + + * @link http://www.pradosoft.com/ * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @package System.Collections - */ - -/** - * TPagedDataSource class - * - * TPagedDataSource implements an integer-indexed collection class with paging functionality. - * - * Data items in TPagedDataSource can be traversed using foreach - * PHP statement like the following, - * - * foreach($pagedDataSource as $dataItem) - * - * The data are fetched from {@link setDataSource DataSource}. Only the items - * within the specified page will be returned and traversed. - * - * @author Qiang Xue - * @version $Id$ - * @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 - * @version $Id$ - * @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 - * @version $Id$ - * @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; - } -} - + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @package System.Collections + */ + +/** + * TPagedDataSource class + * + * TPagedDataSource implements an integer-indexed collection class with paging functionality. + * + * Data items in TPagedDataSource can be traversed using foreach + * PHP statement like the following, + * + * foreach($pagedDataSource as $dataItem) + * + * The data are fetched from {@link setDataSource DataSource}. Only the items + * within the specified page will be returned and traversed. + * + * @author Qiang Xue + * @version $Id$ + * @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 + * @version $Id$ + * @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 + * @version $Id$ + * @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/framework/Collections/TPagedList.php b/framework/Collections/TPagedList.php index d9590327..15f75c0f 100644 --- a/framework/Collections/TPagedList.php +++ b/framework/Collections/TPagedList.php @@ -1,477 +1,477 @@ - - * @link http://www.pradosoft.com/ + + * @link http://www.pradosoft.com/ * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @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, - * - * 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; - * } - * - * - * Data in TPagedList can be accessed like an integer-indexed array and can - * be traversed using foreach. For example, - * - * $count=$list->Count; - * for($index=0;$index<$count;++$index) - * echo $list[$index]; - * foreach($list as $index=>$item) // traverse each item in the list - * - * - * 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 - * @version $Id$ - * @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 OnPageIndexChanged 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 OnFetchData 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 - * @version $Id$ - * @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 - * @version $Id$ - * @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; - } -} - + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @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, + * + * 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; + * } + * + * + * Data in TPagedList can be accessed like an integer-indexed array and can + * be traversed using foreach. For example, + * + * $count=$list->Count; + * for($index=0;$index<$count;++$index) + * echo $list[$index]; + * foreach($list as $index=>$item) // traverse each item in the list + * + * + * 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 + * @version $Id$ + * @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 OnPageIndexChanged 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 OnFetchData 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 + * @version $Id$ + * @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 + * @version $Id$ + * @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/framework/Collections/TPriorityList.php b/framework/Collections/TPriorityList.php index 5258e802..a174ed13 100644 --- a/framework/Collections/TPriorityList.php +++ b/framework/Collections/TPriorityList.php @@ -1,743 +1,743 @@ - - * @link http://www.pradosoft.com/ - * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id: TPriorityList.php 2541 2008-10-21 15:05:13Z javalizard $ - * @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, - * - * $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 - * - * - * 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 - * @version $Id: TPriorityList.php 2541 2008-10-21 15:05:13Z javalizard $ - * @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); - } -} + + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2012 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id: TPriorityList.php 2541 2008-10-21 15:05:13Z javalizard $ + * @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, + * + * $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 + * + * + * 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 + * @version $Id: TPriorityList.php 2541 2008-10-21 15:05:13Z javalizard $ + * @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/framework/Collections/TQueue.php b/framework/Collections/TQueue.php index 840ec478..d02a7aad 100644 --- a/framework/Collections/TQueue.php +++ b/framework/Collections/TQueue.php @@ -1,263 +1,263 @@ - - * @link http://www.pradosoft.com/ - * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @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, - * - * foreach($queue as $item) ... - * - * - * @author Qiang Xue - * @author Knut Urdalen - * @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 - * @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; - } -} - + + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2012 PradoSoft + * @license http://www.pradosoft.com/license/ + * @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, + * + * foreach($queue as $item) ... + * + * + * @author Qiang Xue + * @author Knut Urdalen + * @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 + * @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/framework/Collections/TStack.php b/framework/Collections/TStack.php index 6f8c21f2..706ca2ed 100644 --- a/framework/Collections/TStack.php +++ b/framework/Collections/TStack.php @@ -1,263 +1,263 @@ - - * @link http://www.pradosoft.com/ + + * @link http://www.pradosoft.com/ * @copyright Copyright © 2005-2012 PradoSoft - * @license http://www.pradosoft.com/license/ - * @version $Id$ - * @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, - * - * foreach($stack as $item) ... - * - * - * @author Qiang Xue - * @version $Id$ - * @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 - * @version $Id$ - * @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; - } -} - + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @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, + * + * foreach($stack as $item) ... + * + * + * @author Qiang Xue + * @version $Id$ + * @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 + * @version $Id$ + * @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; + } +} + -- cgit v1.2.3