911b92e5db5c45a145d8898985b88555fc333677
[core.git] / inc / classes / main / stacker / file_stack / class_BaseFileStack.php
1 <?php
2 /**
3  * A general file-based stack class
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
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.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 BaseFileStack extends BaseStacker {
25         /**
26          * Protected constructor
27          *
28          * @param       $className      Name of the class
29          * @return      void
30          */
31         protected function __construct ($className) {
32                 // Call parent constructor
33                 parent::__construct($className);
34         }
35
36         /**
37          * Initializes this file-based stack.
38          *
39          * @param       $fileName       File name of this stack
40          * @return      void
41          */
42         protected function initFileStack ($fileName) {
43                 // Get a file i/o pointer instance
44                 $pointerInstance = ObjectFactory::createObjectByConfiguredName('file_raw_input_output_class', array($fileName));
45
46                 // Get iterator instance
47                 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('file_io_iterator_class', array($pointerInstance));
48
49                 // Is the instance implementing the right interface?
50                 assert($iteratorInstance instanceof SeekableFileIterator);
51
52                 // Set iterator here
53                 $this->setIteratorInstance($iteratorInstance);
54         }
55
56         /**
57          * Initializes given stacker
58          *
59          * @param       $stackerName    Name of the stack
60          * @param       $forceReInit    Force re-initialization
61          * @return      void
62          * @throws      AlreadyInitializedStackerException      If the stack is already initialized
63          */
64         public function initStack ($stackerName, $forceReInit = FALSE) {
65                 // Is the stack already initialized?
66                 if (($forceReInit === FALSE) && ($this->isStackInitialized($stackerName))) {
67                         // Then throw the exception
68                         throw new AlreadyInitializedStackerException(array($this, $stackerName, $forceReInit), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
69                 } // END - if
70
71                 // Initialize the given stack
72                 $this->partialStub('stackerName=' . $stackerName . ',forceReInit=' . intval($forceReInit));
73         }
74
75         /**
76          * Checks whether the given stack is initialized (set in array $stackers)
77          *
78          * @param       $stackerName    Name of the stack
79          * @return      $isInitialized  Whether the stack is initialized
80          */
81         public function isStackInitialized ($stackerName) {
82                 // Is is there?
83                 $this->partialStub('stackerName=' . $stackerName);
84                 $isInitialized = TRUE;
85
86                 // Return result
87                 return $isInitialized;
88         }
89
90         /**
91          * Getter for size of given stack (array count)
92          *
93          * @param       $stackerName    Name of the stack
94          * @return      $count                  Size of stack (array count)
95          * @throws      NoStackerException      If given stack is missing
96          */
97         public function getStackCount ($stackerName) {
98                 // Is the stack not yet initialized?
99                 if (!$this->isStackInitialized($stackerName)) {
100                         // Throw an exception
101                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
102                 } // END - if
103
104                 // Now, count the array of entries
105                 $this->partialStub('stackerName=' . $stackerName);
106                 $count = 0;
107
108                 // Return result
109                 return $count;
110         }
111
112         /**
113          * Adds a value to given stack
114          *
115          * @param       $stackerName    Name of the stack
116          * @param       $value                  Value to add to this stacker
117          * @return      void
118          * @throws      FullStackerException    Thrown if the stack is full
119          */
120         protected function addValue ($stackerName, $value) {
121                 // Is the stack not yet initialized or full?
122                 if (!$this->isStackInitialized($stackerName)) {
123                         // Then do it here
124                         $this->initStack($stackerName);
125                 } elseif ($this->isStackFull($stackerName)) {
126                         // Stacker is full
127                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
128                 }
129
130                 // Now add the value to the stack
131                 $this->partialStub('stackerName=' . $stackerName . ',value[]=' . gettype($value));
132         }
133
134         /**
135          * Get last value from named stacker
136          *
137          * @param       $stackerName    Name of the stack
138          * @return      $value                  Value of last added value
139          * @throws      NoStackerException      If the named stacker was not found
140          * @throws      EmptyStackerException   If the named stacker is empty
141          */
142         protected function getLastValue ($stackerName) {
143                 // Is the stack not yet initialized or full?
144                 if (!$this->isStackInitialized($stackerName)) {
145                         // Throw an exception
146                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
147                 } elseif ($this->isStackEmpty($stackerName)) {
148                         // Throw an exception
149                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
150                 }
151
152                 // Now get the last value
153                 $this->partialStub('stackerName=' . $stackerName);
154                 $value = NULL;
155
156                 // Return it
157                 return $value;
158         }
159
160         /**
161          * Get first 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 function getFirstValue ($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 first value
179                 $this->partialStub('stackerName=' . $stackerName);
180                 $value = NULL;
181
182                 // Return it
183                 return $value;
184         }
185
186         /**
187          * "Pops" last entry from stack
188          *
189          * @param       $stackerName    Name of the stack
190          * @return      $value                  Value "poped" from array
191          * @throws      NoStackerException      If the named stacker was not found
192          * @throws      EmptyStackerException   If the named stacker is empty
193          */
194         protected function popLast ($stackerName) {
195                 // Is the stack not yet initialized or full?
196                 if (!$this->isStackInitialized($stackerName)) {
197                         // Throw an exception
198                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
199                 } elseif ($this->isStackEmpty($stackerName)) {
200                         // Throw an exception
201                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
202                 }
203
204                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
205                 $this->partialStub('stackerName=' . $stackerName);
206                 return NULL;
207         }
208
209         /**
210          * "Pops" first entry from stack
211          *
212          * @param       $stackerName    Name of the stack
213          * @return      $value                  Value "shifted" from array
214          * @throws      NoStackerException      If the named stacker was not found
215          * @throws      EmptyStackerException   If the named stacker is empty
216          */
217         protected function popFirst ($stackerName) {
218                 // Is the stack not yet initialized or full?
219                 if (!$this->isStackInitialized($stackerName)) {
220                         // Throw an exception
221                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
222                 } elseif ($this->isStackEmpty($stackerName)) {
223                         // Throw an exception
224                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
225                 }
226
227                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
228                 $this->partialStub('stackerName=' . $stackerName);
229                 return NULL;
230         }
231 }
232
233 // [EOF]
234 ?>