1: <?php
  2: /**
  3:  * This file contains classes implementing the stack 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:  * CStack implements a stack.
 13:  *
 14:  * The typical stack operations are implemented, which include
 15:  * {@link push()}, {@link pop()} and {@link peek()}. In addition,
 16:  * {@link contains()} can be used to check if an item is contained
 17:  * in the stack. To obtain the number of the items in the stack,
 18:  * check the {@link getCount Count} property.
 19:  *
 20:  * Items in the stack may be traversed using foreach as follows,
 21:  * <pre>
 22:  * foreach($stack as $item) ...
 23:  * </pre>
 24:  *
 25:  * @property Iterator $iterator An iterator for traversing the items in the stack.
 26:  * @property integer $count The number of items in the stack.
 27:  *
 28:  * @author Qiang Xue <qiang.xue@gmail.com>
 29:  * @package system.collections
 30:  * @since 1.0
 31:  */
 32: class CStack 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 stack 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 stack
 59:      */
 60:     public function toArray()
 61:     {
 62:         return $this->_d;
 63:     }
 64: 
 65:     /**
 66:      * Copies iterable data into the stack.
 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','Stack data must be an array or an object implementing Traversable.'));
 84:     }
 85: 
 86:     /**
 87:      * Removes all items in the stack.
 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 stack 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 stack.
106:      * Unlike {@link pop()}, this method does not remove the item from the stack.
107:      * @return mixed item at the top of the stack
108:      * @throws CException if the stack is empty
109:      */
110:     public function peek()
111:     {
112:         if($this->_c)
113:             return $this->_d[$this->_c-1];
114:         else
115:             throw new CException(Yii::t('yii','The stack is empty.'));
116:     }
117: 
118:     /**
119:      * Pops up the item at the top of the stack.
120:      * @return mixed the item at the top of the stack
121:      * @throws CException if the stack is empty
122:      */
123:     public function pop()
124:     {
125:         if($this->_c)
126:         {
127:             --$this->_c;
128:             return array_pop($this->_d);
129:         }
130:         else
131:             throw new CException(Yii::t('yii','The stack is empty.'));
132:     }
133: 
134:     /**
135:      * Pushes an item into the stack.
136:      * @param mixed $item the item to be pushed into the stack
137:      */
138:     public function push($item)
139:     {
140:         ++$this->_c;
141:         $this->_d[]=$item;
142:     }
143: 
144:     /**
145:      * Returns an iterator for traversing the items in the stack.
146:      * This method is required by the interface IteratorAggregate.
147:      * @return Iterator an iterator for traversing the items in the stack.
148:      */
149:     public function getIterator()
150:     {
151:         return new CStackIterator($this->_d);
152:     }
153: 
154:     /**
155:      * Returns the number of items in the stack.
156:      * @return integer the number of items in the stack
157:      */
158:     public function getCount()
159:     {
160:         return $this->_c;
161:     }
162: 
163:     /**
164:      * Returns the number of items in the stack.
165:      * This method is required by Countable interface.
166:      * @return integer number of items in the stack.
167:      */
168:     public function count()
169:     {
170:         return $this->getCount();
171:     }
172: }
173: