12cfc03113c0163ad1b7775b9e40c5414ca80145
[core.git] / inc / classes / main / stacker / class_BaseStacker.php
1 <?php
2 /**
3  * A general Stacker
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
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
10  *
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.
15  *
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.
20  *
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/>.
23  */
24 class BaseStacker extends BaseFrameworkSystem {
25         // Exception codes
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;
30
31         /**
32          * Protected constructor
33          *
34          * @param       $className      Name of the class
35          * @return      void
36          */
37         protected function __construct ($className) {
38                 // Call parent constructor
39                 parent::__construct($className);
40         }
41
42         /**
43          * Initializes given stacker
44          *
45          * @param       $stackerName    Name of the stack
46          * @param       $forceReInit    Force re-initialization
47          * @return      void
48          * @throws      AlreadyInitializedStackerException      If the stack is already initialized
49          */
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);
55                 } // END - if
56
57                 // Initialize the given stack
58                 $this->initGenericArrayKey('stacks', $stackerName, 'entries', $forceReInit);
59         }
60
61         /**
62          * Initializes all stacks
63          *
64          * @return      void
65          */
66         public function initStacks (array $stacks, $forceReInit = FALSE) {
67                 // "Walk" through all (more will be added as needed
68                 foreach ($stacks as $stackerName) {
69                         // Init this stack
70                         $this->initStack($stackerName, $forceReInit);
71                 } // END - foreach
72         }
73
74         /**
75          * Checks whether the given stack is initialized (set in array $stackers)
76          *
77          * @param       $stackerName    Name of the stack
78          * @return      $isInitialized  Whether the stack is initialized
79          */
80         public final function isStackInitialized ($stackerName) {
81                 // Is is there?
82                 $isInitialized = ($this->isValidGenericArrayKey('stacks', $stackerName, 'entries'));
83
84                 // Return result
85                 return $isInitialized;
86         }
87
88         /**
89          * Checks whether the given stack is full
90          *
91          * @param       $stackerName    Name of the stack
92          * @return      $isFull                 Whether the stack is full
93          * @throws      NoStackerException      If given stack is missing
94          */
95         protected final function isStackFull ($stackerName) {
96                 // Is the stack not yet initialized?
97                 if (!$this->isStackInitialized($stackerName)) {
98                         // Throw an exception
99                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
100                 } // END - if
101
102                 // So, is the stack full?
103                 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
104
105                 // Return result
106                 return $isFull;
107         }
108
109         /**
110          * Checks whether the given stack is empty
111          *
112          * @param       $stackerName            Name of the stack
113          * @return      $isEmpty                        Whether the stack is empty
114          * @throws      NoStackerException      If given stack is missing
115          */
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);
121                 } // END - if
122
123                 // So, is the stack empty?
124                 $isEmpty = (($this->getStackCount($stackerName)) == 0);
125
126                 // Return result
127                 return $isEmpty;
128         }
129
130         /**
131          * Getter for size of given stack (array count)
132          *
133          * @param       $stackerName    Name of the stack
134          * @return      $count                  Size of stack (array count)
135          * @throws      NoStackerException      If given stack is missing
136          */
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);
142                 } // END - if
143
144                 // Now, count the array of entries
145                 $count = $this->countGenericArrayElements('stacks', $stackerName, 'entries');
146
147                 // Return result
148                 return $count;
149         }
150
151         /**
152          * Adds a value to given stack
153          *
154          * @param       $stackerName    Name of the stack
155          * @param       $value                  Value to add to this stacker
156          * @return      void
157          * @throws      FullStackerException    Thrown if the stack is full
158          */
159         protected final function addValue ($stackerName, $value) {
160                 // Is the stack not yet initialized or full?
161                 if (!$this->isStackInitialized($stackerName)) {
162                         // Then do it here
163                         $this->initStack($stackerName);
164                 } elseif ($this->isStackFull($stackerName)) {
165                         // Stacker is full
166                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
167                 }
168
169                 // Now add the value to the stack
170                 $this->pushValueToGenericArrayKey('stacks', $stackerName, 'entries', $value);
171         }
172
173         /**
174          * Get last value from named stacker
175          *
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
180          */
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);
189                 }
190
191                 // Now get the last value
192                 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', $this->getStackCount($stackerName) - 1);
193
194                 // Return it
195                 return $value;
196         }
197
198         /**
199          * Get first value from named stacker
200          *
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
205          */
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);
214                 }
215
216                 // Now get the first value
217                 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', 0);
218
219                 // Return it
220                 return $value;
221         }
222
223         /**
224          * "Pops" last entry from stack
225          *
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
230          */
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);
239                 }
240
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');
243         }
244
245         /**
246          * "Pops" first entry from stack
247          *
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
252          */
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);
261                 }
262
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');
265         }
266 }
267
268 // [EOF]
269 ?>