5 * @author Roland Haeder <webmaster@ship-simu.org>
7 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Core Developer Team
8 * @license GNU GPL 3.0 or any newer version
9 * @link http://www.ship-simu.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 initStacker ($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), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
57 // Initialize the given stack
58 $this->initGenericArray('stacks', $stackerName, 'entries');
62 * Checks whether the given stack is initialized (set in array $stackers)
64 * @param $stackerName Name of the stack
65 * @return $isInitialized Whether the stack is initialized
67 public final function isStackInitialized ($stackerName) {
69 $isInitialized = ($this->isValidGenericArrayKey('stacks', $stackerName, 'entries'));
72 return $isInitialized;
76 * Checks whether the given stack is full
78 * @param $stackerName Name of the stack
79 * @return $isFull Whether the stack is full
80 * @throws NoStackerException If given stack is missing
82 protected final function isStackFull ($stackerName) {
83 // Is the stack not yet initialized?
84 if (!$this->isStackInitialized($stackerName)) {
86 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
89 // So, is the stack full?
90 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
97 * Checks whether the given stack is empty
99 * @param $stackerName Name of the stack
100 * @return $isEmpty Whether the stack is empty
101 * @throws NoStackerException If given stack is missing
103 public final function isStackEmpty ($stackerName) {
104 // Is the stack not yet initialized?
105 if (!$this->isStackInitialized($stackerName)) {
106 // Throw an exception
107 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
110 // So, is the stack empty?
111 $isEmpty = (($this->getStackCount($stackerName)) == 0);
118 * Getter for size of given stack (array count)
120 * @param $stackerName Name of the stack
121 * @return $count Size of stack (array count)
122 * @throws NoStackerException If given stack is missing
124 public final function getStackCount ($stackerName) {
125 // Is the stack not yet initialized?
126 if (!$this->isStackInitialized($stackerName)) {
127 // Throw an exception
128 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
131 // Now, count the array of entries
132 $count = $this->countGenericArrayElements('stacks', $stackerName, 'entries');
139 * Adds a value to given stack
141 * @param $stackerName Name of the stack
142 * @param $value Value to add to this stacker
144 * @throws FullStackerException Thrown if the stack is full
146 protected final function addValue ($stackerName, $value) {
147 // Is the stack not yet initialized or full?
148 if (!$this->isStackInitialized($stackerName)) {
150 $this->initStacker($stackerName);
151 } elseif ($this->isStackFull($stackerName)) {
153 throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
156 // Now add the value to the stack
157 $this->pushValueToGenericArrayElement('stacks', $stackerName, 'entries', $value);
161 * Get last value from named stacker
163 * @param $stackerName Name of the stack
164 * @return $value Value of last added value
165 * @throws NoStackerException If the named stacker was not found
166 * @throws EmptyStackerException If the named stacker is empty
168 protected final function getLastValue ($stackerName) {
169 // Is the stack not yet initialized or full?
170 if (!$this->isStackInitialized($stackerName)) {
171 // Throw an exception
172 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
173 } elseif ($this->isStackEmpty($stackerName)) {
175 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
178 // Now get the last value
179 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', $this->getStackCount($stackerName) - 1);
186 * Get first value from named stacker
188 * @param $stackerName Name of the stack
189 * @return $value Value of last added value
190 * @throws NoStackerException If the named stacker was not found
191 * @throws EmptyStackerException If the named stacker is empty
193 protected final function getFirstValue ($stackerName) {
194 // Is the stack not yet initialized or full?
195 if (!$this->isStackInitialized($stackerName)) {
196 // Throw an exception
197 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
198 } elseif ($this->isStackEmpty($stackerName)) {
200 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
203 // Now get the first value
204 $value = $this->popGenericArrayElement('stacks', $stackerName, 'entries', 0);
211 * "Pops" last entry from stack
213 * @param $stackerName Name of the stack
215 * @throws NoStackerException If the named stacker was not found
216 * @throws EmptyStackerException If the named stacker is empty
218 protected final function popLast ($stackerName) {
219 // Is the stack not yet initialized or full?
220 if (!$this->isStackInitialized($stackerName)) {
221 // Throw an exception
222 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
223 } elseif ($this->isStackEmpty($stackerName)) {
225 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
228 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
229 $this->popGenericArrayElement('stacks', $stackerName, 'entries');
233 * "Pops" first entry from stack
235 * @param $stackerName Name of the stack
237 * @throws NoStackerException If the named stacker was not found
238 * @throws EmptyStackerException If the named stacker is empty
240 protected final function popFirst ($stackerName) {
241 // Is the stack not yet initialized or full?
242 if (!$this->isStackInitialized($stackerName)) {
243 // Throw an exception
244 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
245 } elseif ($this->isStackEmpty($stackerName)) {
247 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
250 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
251 $this->shiftGenericArrayElement('stacks', $stackerName, 'entries');