Registry rewritten, exception added #2
[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, 2010 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          * An array holding all stacks
33          */
34         private $stacks = array();
35
36         /**
37          * Protected constructor
38          *
39          * @param       $className      Name of the class
40          * @return      void
41          */
42         protected function __construct ($className) {
43                 // Call parent constructor
44                 parent::__construct($className);
45         }
46
47         /**
48          * Initializes given stacker
49          *
50          * @param       $stackerName    Name of the stack
51          * @return      void
52          * @throws      AlreadyInitializedStackerException      If the stack is already initialized
53          */
54         protected final function initStacker ($stackerName) {
55                 // Is the stack already initialized?
56                 if ($this->isStackInitialized($stackerName)) {
57                         // Then throw the exception
58                         throw new AlreadyInitializedStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
59                 } // END - if
60
61                 // Initialize the given stack
62                 $this->stacks[$stackerName] = array(
63                         'max_size' => $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'),
64                         'entries'  => array()
65                 );
66         }
67
68         /**
69          * Checks wether the given stack is initialized (set in array $stackers)
70          *
71          * @param       $stackerName    Name of the stack
72          * @return      $isInitialized  Wether the stack is initialized
73          */
74         public final function isStackInitialized ($stackerName) {
75                 // Is is there?
76                 $isInitialized = ((isset($this->stacks[$stackerName])) && (is_array($this->stacks[$stackerName])));
77
78                 // Return result
79                 return $isInitialized;
80         }
81
82         /**
83          * Checks wether the given stack is full
84          *
85          * @param       $stackerName    Name of the stack
86          * @return      $isFull                 Wether the stack is full
87          * @throws      NoStackerException      If given stack is missing
88          */
89         protected final function isStackFull ($stackerName) {
90                 // Is the stack not yet initialized?
91                 if (!$this->isStackInitialized($stackerName)) {
92                         // Throw an exception
93                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
94                 } // END - if
95
96                 // So, is the stack full?
97                 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
98
99                 // Return result
100                 return $isFull;
101         }
102
103         /**
104          * Checks wether the given stack is empty
105          *
106          * @param       $stackerName    Name of the stack
107          * @return      $isEmpty                        Wether the stack is empty
108          * @throws      NoStackerException      If given stack is missing
109          */
110         public final function isStackEmpty ($stackerName) {
111                 // Is the stack not yet initialized?
112                 if (!$this->isStackInitialized($stackerName)) {
113                         // Throw an exception
114                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
115                 } // END - if
116
117                 // So, is the stack full?
118                 $isFull = (($this->getStackCount($stackerName)) == 0);
119
120                 // Return result
121                 return $isFull;
122         }
123
124         /**
125          * Getter for size of given stack (array count)
126          *
127          * @param       $stackerName    Name of the stack
128          * @return      $count                  Size of stack (array count)
129          * @throws      NoStackerException      If given stack is missing
130          */
131         protected final function getStackCount ($stackerName) {
132                 // Is the stack not yet initialized?
133                 if (!$this->isStackInitialized($stackerName)) {
134                         // Throw an exception
135                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
136                 } // END - if
137
138                 // Now, count the array of entries
139                 $count = count($this->stacks[$stackerName]['entries']);
140
141                 // Return result
142                 return $count;
143         }
144
145         /**
146          * Adds a value to given stack
147          *
148          * @param       $stackerName    Name of the stack
149          * @param       $value                  Value to add to this stacker
150          * @return      void
151          * @throws      FullStackerException    Thrown if the stack is full
152          */
153         protected final function addValue ($stackerName, $value) {
154                 // Is the stack not yet initialized or full?
155                 if (!$this->isStackInitialized($stackerName)) {
156                         // Then do it here
157                         $this->initStacker($stackerName);
158                 } elseif ($this->isStackFull($stackerName)) {
159                         // Stacker is full
160                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
161                 }
162
163                 // Now add the value to the stack
164                 array_push($this->stacks[$stackerName]['entries'], $value);
165         }
166
167         /**
168          * Get last value from named stacker
169          *
170          * @param       $stackerName    Name of the stack
171          * @return      $value                  Value of last added value
172          * @throws      NoStackerException      If the named stacker was not found
173          * @throws      EmptyStackerException   If the named stacker is empty
174          */
175         protected final function getLastValue ($stackerName) {
176                 // Is the stack not yet initialized or full?
177                 if (!$this->isStackInitialized($stackerName)) {
178                         // Throw an exception
179                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
180                 } elseif ($this->isStackEmpty($stackerName)) {
181                         //Throw an exception
182                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
183                 }
184
185                 // Now get the last value
186                 $value = $this->stacks[$stackerName]['entries'][$this->getStackCount($stackerName) - 1];
187
188                 // Return it
189                 return $value;
190         }
191
192         /**
193          * Get first value from named stacker
194          *
195          * @param       $stackerName    Name of the stack
196          * @return      $value                  Value of last added value
197          * @throws      NoStackerException      If the named stacker was not found
198          * @throws      EmptyStackerException   If the named stacker is empty
199          */
200         protected final function getFirstValue ($stackerName) {
201                 // Is the stack not yet initialized or full?
202                 if (!$this->isStackInitialized($stackerName)) {
203                         // Throw an exception
204                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
205                 } elseif ($this->isStackEmpty($stackerName)) {
206                         //Throw an exception
207                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
208                 }
209
210                 // Now get the last value
211                 $value = $this->stacks[$stackerName]['entries'][0];
212
213                 // Return it
214                 return $value;
215         }
216
217         /**
218          * "Pops" last entry from stack
219          *
220          * @param       $stackerName    Name of the stack
221          * @return      void
222          * @throws      NoStackerException      If the named stacker was not found
223          * @throws      EmptyStackerException   If the named stacker is empty
224          */
225         protected final function popLast ($stackerName) {
226                 // Is the stack not yet initialized or full?
227                 if (!$this->isStackInitialized($stackerName)) {
228                         // Throw an exception
229                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
230                 } elseif ($this->isStackEmpty($stackerName)) {
231                         //Throw an exception
232                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
233                 }
234
235                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
236                 array_pop($this->stacks[$stackerName]['entries']);
237         }
238
239         /**
240          * "Pops" first entry from stack
241          *
242          * @param       $stackerName    Name of the stack
243          * @return      void
244          * @throws      NoStackerException      If the named stacker was not found
245          * @throws      EmptyStackerException   If the named stacker is empty
246          */
247         protected final function popFirst ($stackerName) {
248                 // Is the stack not yet initialized or full?
249                 if (!$this->isStackInitialized($stackerName)) {
250                         // Throw an exception
251                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
252                 } elseif ($this->isStackEmpty($stackerName)) {
253                         //Throw an exception
254                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
255                 }
256
257                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
258                 array_shift($this->stacks[$stackerName]['entries']);
259         }
260 }
261
262 // [EOF]
263 ?>