1: <?php
  2: /**
  3:  * This file contains classes implementing the queue feature.
  4:  *
  5:  * @author Qiang Xue <qiang.xue@gmail.com>
  6:  * @link http://www.yiiframework.com/
  7:  * @copyright 2008-2013 Yii Software LLC
  8:  * @license http://www.yiiframework.com/license/
  9:  */
 10: 
 11: /**
 12:  * CQueue implements a queue.
 13:  *
 14:  * The typical queue operations are implemented, which include
 15:  * {@link enqueue()}, {@link dequeue()} and {@link peek()}. In addition,
 16:  * {@link contains()} can be used to check if an item is contained
 17:  * in the queue. To obtain the number of the items in the queue,
 18:  * check the {@link getCount Count} property.
 19:  *
 20:  * Items in the queue may be traversed using foreach as follows,
 21:  * <pre>
 22:  * foreach($queue as $item) ...
 23:  * </pre>
 24:  *
 25:  * @property Iterator $iterator An iterator for traversing the items in the queue.
 26:  * @property integer $count The number of items in the queue.
 27:  *
 28:  * @author Qiang Xue <qiang.xue@gmail.com>
 29:  * @package system.collections
 30:  * @since 1.0
 31:  */
 32: class CQueue extends CComponent implements IteratorAggregate,Countable
 33: {
 34:     /**
 35:      * internal data storage
 36:      * @var array
 37:      */
 38:     private $_d=array();
 39:     /**
 40:      * number of items
 41:      * @var integer
 42:      */
 43:     private $_c=0;
 44: 
 45:     /**
 46:      * Constructor.
 47:      * Initializes the queue with an array or an iterable object.
 48:      * @param array $data the initial data. Default is null, meaning no initialization.
 49:      * @throws CException If data is not null and neither an array nor an iterator.
 50:      */
 51:     public function __construct($data=null)
 52:     {
 53:         if($data!==null)
 54:             $this->copyFrom($data);
 55:     }
 56: 
 57:     /**
 58:      * @return array the list of items in queue
 59:      */
 60:     public function toArray()
 61:     {
 62:         return $this->_d;
 63:     }
 64: 
 65:     /**
 66:      * Copies iterable data into the queue.
 67:      * Note, existing data in the list will be cleared first.
 68:      * @param mixed $data the data to be copied from, must be an array or object implementing Traversable
 69:      * @throws CException If data is neither an array nor a Traversable.
 70:      */
 71:     public function copyFrom($data)
 72:     {
 73:         if(is_array($data) || ($data instanceof Traversable))
 74:         {
 75:             $this->clear();
 76:             foreach($data as $item)
 77:             {
 78:                 $this->_d[]=$item;
 79:                 ++$this->_c;
 80:             }
 81:         }
 82:         elseif($data!==null)
 83:             throw new CException(Yii::t('yii','Queue data must be an array or an object implementing Traversable.'));
 84:     }
 85: 
 86:     /**
 87:      * Removes all items in the queue.
 88:      */
 89:     public function clear()
 90:     {
 91:         $this->_c=0;
 92:         $this->_d=array();
 93:     }
 94: 
 95:     /**
 96:      * @param mixed $item the item
 97:      * @return boolean whether the queue contains the item
 98:      */
 99:     public function contains($item)
100:     {
101:         return array_search($item,$this->_d,true)!==false;
102:     }
103: 
104:     /**
105:      * Returns the item at the top of the queue.
106:      * @return mixed item at the top of the queue
107:      * @throws CException if the queue is empty
108:      */
109:     public function peek()
110:     {
111:         if($this->_c===0)
112:             throw new CException(Yii::t('yii','The queue is empty.'));
113:         else
114:             return $this->_d[0];
115:     }
116: 
117:     /**
118:      * Removes and returns the object at the beginning of the queue.
119:      * @return mixed the item at the beginning of the queue
120:      * @throws CException if the queue is empty
121:      */
122:     public function dequeue()
123:     {
124:         if($this->_c===0)
125:             throw new CException(Yii::t('yii','The queue is empty.'));
126:         else
127:         {
128:             --$this->_c;
129:             return array_shift($this->_d);
130:         }
131:     }
132: 
133:     /**
134:      * Adds an object to the end of the queue.
135:      * @param mixed $item the item to be appended into the queue
136:      */
137:     public function enqueue($item)
138:     {
139:         ++$this->_c;
140:         $this->_d[]=$item;
141:     }
142: 
143:     /**
144:      * Returns an iterator for traversing the items in the queue.
145:      * This method is required by the interface IteratorAggregate.
146:      * @return Iterator an iterator for traversing the items in the queue.
147:      */
148:     public function getIterator()
149:     {
150:         return new CQueueIterator($this->_d);
151:     }
152: 
153:     /**
154:      * Returns the number of items in the queue.
155:      * @return integer the number of items in the queue
156:      */
157:     public function getCount()
158:     {
159:         return $this->_c;
160:     }
161: 
162:     /**
163:      * Returns the number of items in the queue.
164:      * This method is required by Countable interface.
165:      * @return integer number of items in the queue.
166:      */
167:     public function count()
168:     {
169:         return $this->getCount();
170:     }
171: }
172: