3 * A general file-based stack class
5 * @author Roland Haeder <webmaster@ship-simu.org>
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
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 BaseFileStack extends BaseStacker {
26 * Magic for this stack
28 const STACK_MAGIC = 'STACKv0.1';
31 * Separator magic->count
33 const SEPARATOR_MAGIC_COUNT = 0x00;
36 * Separator position->entries
38 const SEPARATOR_SEEK_POS_ENTRIES = 0xff;
41 * Separator hash->name
43 const SEPARATOR_HASH_NAME = 0x01;
46 * Protected constructor
48 * @param $className Name of the class
51 protected function __construct ($className) {
52 // Call parent constructor
53 parent::__construct($className);
57 * Initializes this file-based stack.
59 * @param $fileName File name of this stack
62 protected function initFileStack ($fileName) {
63 // Get a file i/o pointer instance
64 $pointerInstance = ObjectFactory::createObjectByConfiguredName('file_raw_input_output_class', array($fileName));
66 // Get iterator instance
67 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('file_io_iterator_class', array($pointerInstance));
69 // Is the instance implementing the right interface?
70 assert($iteratorInstance instanceof SeekableWritableFileIterator);
73 $this->setIteratorInstance($iteratorInstance);
77 * Initializes given stacker
79 * @param $stackerName Name of the stack
80 * @param $forceReInit Force re-initialization
82 * @throws AlreadyInitializedStackerException If the stack is already initialized
84 public function initStack ($stackerName, $forceReInit = FALSE) {
85 // Is the stack already initialized?
86 if (($forceReInit === FALSE) && ($this->isStackInitialized($stackerName))) {
87 // Then throw the exception
88 throw new AlreadyInitializedStackerException(array($this, $stackerName, $forceReInit), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
91 // Initialize the given stack
92 $this->partialStub('stackerName=' . $stackerName . ',forceReInit=' . intval($forceReInit));
96 * Checks whether the given stack is initialized (set in array $stackers)
98 * @param $stackerName Name of the stack
99 * @return $isInitialized Whether the stack is initialized
101 public function isStackInitialized ($stackerName) {
103 $this->partialStub('stackerName=' . $stackerName);
104 $isInitialized = TRUE;
107 return $isInitialized;
111 * Getter for size of given stack (array count)
113 * @param $stackerName Name of the stack
114 * @return $count Size of stack (array count)
115 * @throws NoStackerException If given stack is missing
117 public function getStackCount ($stackerName) {
118 // Is the stack not yet initialized?
119 if (!$this->isStackInitialized($stackerName)) {
120 // Throw an exception
121 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
124 // Now, count the array of entries
125 $this->partialStub('stackerName=' . $stackerName);
133 * Adds a value to given stack
135 * @param $stackerName Name of the stack
136 * @param $value Value to add to this stacker
138 * @throws FullStackerException Thrown if the stack is full
140 protected function addValue ($stackerName, $value) {
141 // Is the stack not yet initialized or full?
142 if (!$this->isStackInitialized($stackerName)) {
144 $this->initStack($stackerName);
145 } elseif ($this->isStackFull($stackerName)) {
147 throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
150 // Now add the value to the stack
151 $this->partialStub('stackerName=' . $stackerName . ',value[]=' . gettype($value));
155 * Get last value from named stacker
157 * @param $stackerName Name of the stack
158 * @return $value Value of last added value
159 * @throws NoStackerException If the named stacker was not found
160 * @throws EmptyStackerException If the named stacker is empty
162 protected function getLastValue ($stackerName) {
163 // Is the stack not yet initialized or full?
164 if (!$this->isStackInitialized($stackerName)) {
165 // Throw an exception
166 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
167 } elseif ($this->isStackEmpty($stackerName)) {
168 // Throw an exception
169 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
172 // Now get the last value
173 $this->partialStub('stackerName=' . $stackerName);
181 * Get first value from named stacker
183 * @param $stackerName Name of the stack
184 * @return $value Value of last added value
185 * @throws NoStackerException If the named stacker was not found
186 * @throws EmptyStackerException If the named stacker is empty
188 protected function getFirstValue ($stackerName) {
189 // Is the stack not yet initialized or full?
190 if (!$this->isStackInitialized($stackerName)) {
191 // Throw an exception
192 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
193 } elseif ($this->isStackEmpty($stackerName)) {
194 // Throw an exception
195 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
198 // Now get the first value
199 $this->partialStub('stackerName=' . $stackerName);
207 * "Pops" last entry from stack
209 * @param $stackerName Name of the stack
210 * @return $value Value "poped" from array
211 * @throws NoStackerException If the named stacker was not found
212 * @throws EmptyStackerException If the named stacker is empty
214 protected function popLast ($stackerName) {
215 // Is the stack not yet initialized or full?
216 if (!$this->isStackInitialized($stackerName)) {
217 // Throw an exception
218 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
219 } elseif ($this->isStackEmpty($stackerName)) {
220 // Throw an exception
221 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
224 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
225 $this->partialStub('stackerName=' . $stackerName);
230 * "Pops" first entry from stack
232 * @param $stackerName Name of the stack
233 * @return $value Value "shifted" from array
234 * @throws NoStackerException If the named stacker was not found
235 * @throws EmptyStackerException If the named stacker is empty
237 protected function popFirst ($stackerName) {
238 // Is the stack not yet initialized or full?
239 if (!$this->isStackInitialized($stackerName)) {
240 // Throw an exception
241 throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
242 } elseif ($this->isStackEmpty($stackerName)) {
243 // Throw an exception
244 throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
247 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
248 $this->partialStub('stackerName=' . $stackerName);