Fixed more generic array handling, introduced unsetGenericArrayKey()
[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 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);
55                 } // END - if
56
57                 // Initialize the given stack
58                 $this->initGenericArrayKey('stacks', $stackerName, 'entries', $forceReInit);
59         }
60
61         /**
62          * Checks whether the given stack is initialized (set in array $stackers)
63          *
64          * @param       $stackerName    Name of the stack
65          * @return      $isInitialized  Whether the stack is initialized
66          */
67         public final function isStackInitialized ($stackerName) {
68                 // Is is there?
69                 $isInitialized = ($this->isValidGenericArrayKey('stacks', $stackerName, 'entries'));
70
71                 // Return result
72                 return $isInitialized;
73         }
74
75         /**
76          * Checks whether the given stack is full
77          *
78          * @param       $stackerName    Name of the stack
79          * @return      $isFull                 Whether the stack is full
80          * @throws      NoStackerException      If given stack is missing
81          */
82         protected final function isStackFull ($stackerName) {
83                 // Is the stack not yet initialized?
84                 if (!$this->isStackInitialized($stackerName)) {
85                         // Throw an exception
86                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
87                 } // END - if
88
89                 // So, is the stack full?
90                 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
91
92                 // Return result
93                 return $isFull;
94         }
95
96         /**
97          * Checks whether the given stack is empty
98          *
99          * @param       $stackerName            Name of the stack
100          * @return      $isEmpty                        Whether the stack is empty
101          * @throws      NoStackerException      If given stack is missing
102          */
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);
108                 } // END - if
109
110                 // So, is the stack empty?
111                 $isEmpty = (($this->getStackCount($stackerName)) == 0);
112
113                 // Return result
114                 return $isEmpty;
115         }
116
117         /**
118          * Getter for size of given stack (array count)
119          *
120          * @param       $stackerName    Name of the stack
121          * @return      $count                  Size of stack (array count)
122          * @throws      NoStackerException      If given stack is missing
123          */
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);
129                 } // END - if
130
131                 // Now, count the array of entries
132                 $count = $this->countGenericArrayElements('stacks', $stackerName, 'entries');
133
134                 // Return result
135                 return $count;
136         }
137
138         /**
139          * Adds a value to given stack
140          *
141          * @param       $stackerName    Name of the stack
142          * @param       $value                  Value to add to this stacker
143          * @return      void
144          * @throws      FullStackerException    Thrown if the stack is full
145          */
146         protected final function addValue ($stackerName, $value) {
147                 // Is the stack not yet initialized or full?
148                 if (!$this->isStackInitialized($stackerName)) {
149                         // Then do it here
150                         $this->initStacker($stackerName);
151                 } elseif ($this->isStackFull($stackerName)) {
152                         // Stacker is full
153                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
154                 }
155
156                 // Now add the value to the stack
157                 $this->pushValueToGenericArrayElement('stacks', $stackerName, 'entries', $value);
158         }
159
160         /**
161          * Get last value from named stacker
162          *
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
167          */
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)) {
174                         // Throw an exception
175                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
176                 }
177
178                 // Now get the last value
179                 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', $this->getStackCount($stackerName) - 1);
180
181                 // Return it
182                 return $value;
183         }
184
185         /**
186          * Get first value from named stacker
187          *
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
192          */
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)) {
199                         // Throw an exception
200                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
201                 }
202
203                 // Now get the first value
204                 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', 0);
205
206                 // Return it
207                 return $value;
208         }
209
210         /**
211          * "Pops" last entry from stack
212          *
213          * @param       $stackerName    Name of the stack
214          * @return      $value                  Value "poped" from array
215          * @throws      NoStackerException      If the named stacker was not found
216          * @throws      EmptyStackerException   If the named stacker is empty
217          */
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)) {
224                         // Throw an exception
225                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
226                 }
227
228                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
229                 return $this->popGenericArrayElement('stacks', $stackerName, 'entries');
230         }
231
232         /**
233          * "Pops" first entry from stack
234          *
235          * @param       $stackerName    Name of the stack
236          * @return      $value                  Value "shifted" from array
237          * @throws      NoStackerException      If the named stacker was not found
238          * @throws      EmptyStackerException   If the named stacker is empty
239          */
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)) {
246                         // Throw an exception
247                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
248                 }
249
250                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
251                 return $this->shiftGenericArrayElement('stacks', $stackerName, 'entries');
252         }
253 }
254
255 // [EOF]
256 ?>