5 * @author Roland Haeder <webmaster@shipsimu.org>
7 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2013 Core Developer Team
8 * @license GNU GPL 3.0 or any newer version
9 * @link http://www.shipsimu.org
11 * This program is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation, either version 3 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 class BaseStacker extends BaseFrameworkSystem {
26 const EXCEPTION_STACKER_ALREADY_INITIALIZED = 0x050;
27 const EXCEPTION_STACKER_IS_FULL = 0x051;
28 const EXCEPTION_NO_STACKER_FOUND = 0x052;
29 const EXCEPTION_STACKER_IS_EMPTY = 0x053;
32 * Protected constructor
34 * @param $className Name of the class
37 protected function __construct ($className) {
38 // Call parent constructor
39 parent::__construct($className);
43 * Initializes given stacker
45 * @param $stackerName Name of the stack
46 * @param $forceReInit Force re-initialization
48 * @throws AlreadyInitializedStackerException If the stack is already initialized
50 public final function initStack ($stackerName, $forceReInit = FALSE) {
51 // Is the stack already initialized?
52 if (($forceReInit === FALSE) && ($this->isStackInitialized($stackerName))) {
53 // Then throw the exception
54 throw new AlreadyInitializedStackerException(array($this, $stackerName, $forceReInit), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
57 // Initialize the given stack
58 $this->initGenericArrayKey('stacks', $stackerName, 'entries', $forceReInit);
62 * Initializes all stacks
66 public function initStacks (array $stacks, $forceReInit = FALSE) {
67 // "Walk" through all (more will be added as needed
68 foreach ($stacks as $stackerName) {
70 $this->initStack($stackerName, $forceReInit);
75 * Checks whether the given stack is initialized (set in array $stackers)
77 * @param $stackerName Name of the stack
78 * @return $isInitialized Whether the stack is initialized
80 public final function isStackInitialized ($stackerName) {
82 $isInitialized = ($this->isValidGenericArrayKey('stacks', $stackerName, 'entries'));
85 return $isInitialized;
89 * Checks whether the given stack is full
91 * @param $stackerName Name of the stack
92 * @return $isFull Whether the stack is full
93 * @throws NoStackerException If given stack is missing
95 protected final function isStackFull ($stackerName) {
96 // Is the stack not yet initialized?
97 if (!$this->isStackInitialized($stackerName)) {
99 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
102 // So, is the stack full?
103 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
110 * Checks whether the given stack is empty
112 * @param $stackerName Name of the stack
113 * @return $isEmpty Whether the stack is empty
114 * @throws NoStackerException If given stack is missing
116 public final function isStackEmpty ($stackerName) {
117 // Is the stack not yet initialized?
118 if (!$this->isStackInitialized($stackerName)) {
119 // Throw an exception
120 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
123 // So, is the stack empty?
124 $isEmpty = (($this->getStackCount($stackerName)) == 0);
131 * Getter for size of given stack (array count)
133 * @param $stackerName Name of the stack
134 * @return $count Size of stack (array count)
135 * @throws NoStackerException If given stack is missing
137 public final function getStackCount ($stackerName) {
138 // Is the stack not yet initialized?
139 if (!$this->isStackInitialized($stackerName)) {
140 // Throw an exception
141 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
144 // Now, count the array of entries
145 $count = $this->countGenericArrayElements('stacks', $stackerName, 'entries');
152 * Adds a value to given stack
154 * @param $stackerName Name of the stack
155 * @param $value Value to add to this stacker
157 * @throws FullStackerException Thrown if the stack is full
159 protected final function addValue ($stackerName, $value) {
160 // Is the stack not yet initialized or full?
161 if (!$this->isStackInitialized($stackerName)) {
163 $this->initStack($stackerName);
164 } elseif ($this->isStackFull($stackerName)) {
166 throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
169 // Now add the value to the stack
170 $this->pushValueToGenericArrayKey('stacks', $stackerName, 'entries', $value);
174 * Get last value from named stacker
176 * @param $stackerName Name of the stack
177 * @return $value Value of last added value
178 * @throws NoStackerException If the named stacker was not found
179 * @throws EmptyStackerException If the named stacker is empty
181 protected final function getLastValue ($stackerName) {
182 // Is the stack not yet initialized or full?
183 if (!$this->isStackInitialized($stackerName)) {
184 // Throw an exception
185 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
186 } elseif ($this->isStackEmpty($stackerName)) {
187 // Throw an exception
188 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
191 // Now get the last value
192 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', $this->getStackCount($stackerName) - 1);
199 * Get first value from named stacker
201 * @param $stackerName Name of the stack
202 * @return $value Value of last added value
203 * @throws NoStackerException If the named stacker was not found
204 * @throws EmptyStackerException If the named stacker is empty
206 protected final function getFirstValue ($stackerName) {
207 // Is the stack not yet initialized or full?
208 if (!$this->isStackInitialized($stackerName)) {
209 // Throw an exception
210 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
211 } elseif ($this->isStackEmpty($stackerName)) {
212 // Throw an exception
213 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
216 // Now get the first value
217 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', 0);
224 * "Pops" last entry from stack
226 * @param $stackerName Name of the stack
227 * @return $value Value "poped" from array
228 * @throws NoStackerException If the named stacker was not found
229 * @throws EmptyStackerException If the named stacker is empty
231 protected final function popLast ($stackerName) {
232 // Is the stack not yet initialized or full?
233 if (!$this->isStackInitialized($stackerName)) {
234 // Throw an exception
235 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
236 } elseif ($this->isStackEmpty($stackerName)) {
237 // Throw an exception
238 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
241 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
242 return $this->popGenericArrayElement('stacks', $stackerName, 'entries');
246 * "Pops" first entry from stack
248 * @param $stackerName Name of the stack
249 * @return $value Value "shifted" from array
250 * @throws NoStackerException If the named stacker was not found
251 * @throws EmptyStackerException If the named stacker is empty
253 protected final function popFirst ($stackerName) {
254 // Is the stack not yet initialized or full?
255 if (!$this->isStackInitialized($stackerName)) {
256 // Throw an exception
257 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
258 } elseif ($this->isStackEmpty($stackerName)) {
259 // Throw an exception
260 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
263 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
264 return $this->shiftGenericArrayElement('stacks', $stackerName, 'entries');