3 namespace Org\Mxchange\CoreFramework\Iterator\File;
5 // Import framework stuff
6 use Org\Mxchange\CoreFramework\Filesystem\File\BinaryFile;
7 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
8 use Org\Mxchange\CoreFramework\Iterator\BaseIterator;
9 use Org\Mxchange\CoreFramework\Traits\File\BinaryFileTrait;
12 use \BadMethodCallException;
13 use \InvalidArgumentException;
14 use \OutOfBoundsException;
15 use \SeekableIterator;
20 * @author Roland Haeder <webmaster@ship-simu.org>
22 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
23 * @license GNU GPL 3.0 or any newer version
24 * @link http://www.ship-simu.org
26 * This program is free software: you can redistribute it and/or modify
27 * it under the terms of the GNU General Public License as published by
28 * the Free Software Foundation, either version 3 of the License, or
29 * (at your option) any later version.
31 * This program is distributed in the hope that it will be useful,
32 * but WITHOUT ANY WARRANTY; without even the implied warranty of
33 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
34 * GNU General Public License for more details.
36 * You should have received a copy of the GNU General Public License
37 * along with this program. If not, see <http://www.gnu.org/licenses/>.
39 class FileIterator extends BaseIterator implements SeekableIterator {
44 * Protected constructor
48 private function __construct () {
49 // Call parent constructor
50 parent::__construct(__CLASS__);
54 * Creates an instance of this class
56 * @param $binaryFileInstance An instance of a BinaryFile class
57 * @return $iteratorInstance An instance of a Iterator class
59 public final static function createFileIterator (BinaryFile $binaryFileInstance) {
61 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: binaryFileInstance=%s - CALLED!', $binaryFileInstance->__toString()));
62 $iteratorInstance = new FileIterator();
64 // Set the instance here
65 $iteratorInstance->setBinaryFileInstance($binaryFileInstance);
67 // Return the prepared instance
68 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
69 return $iteratorInstance;
73 * Gets currently read data
75 * @return $current Currently read data
76 * @throws BadMethodCallException If valid() is FALSE
78 public function current () {
79 // Is condition given?
80 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
81 if (!$this->valid()) {
83 throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
87 $current = $this->getBinaryFileInstance()->current();
90 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: current[]=%s - EXIT!', gettype($current)));
95 * Gets current seek position ("key").
97 * @return $key Current key in iteration
98 * @throws BadMethodCallException If valid() is FALSE
100 public function key () {
101 // Is condition given?
102 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
103 if (!$this->valid()) {
105 throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
108 // Get key from file instance
109 $key = $this->getBinaryFileInstance()->determineSeekPosition();
112 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: key[%s]=%s - EXIT!', gettype($key), $key));
117 * Advances to next "file" of bytes
121 public function next () {
122 // Call file instance
123 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
124 $this->getBinaryFileInstance()->next();
127 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
131 * Rewinds to the beginning of the file
133 * @return $status Status of this operation
135 public function rewind () {
136 // Call file instance
137 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
138 $this->getBinaryFileInstance()->rewind();
141 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
145 * Checks wether the current entry is valid (not at the end of the file).
146 * This method will return true if an emptied (nulled) entry has been found.
148 * @return $isValid Whether the next entry is valid
150 public function valid () {
151 // Call file instance
152 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
153 $isValid = $this->getBinaryFileInstance()->valid();
156 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isValid=%d - EXIT!', intval($isValid)));
161 * Seeks to given position
163 * @param $seekPosition Seek position in file
165 * @throws OutOfBoundsException If the position is not seekable
167 public function seek (int $seekPosition) {
168 // Validate parameter
169 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence));
170 if ($seekPosition < 0) {
172 throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
175 // Call file instance
176 $this->getBinaryFileInstance()->seek($seekPosition);
179 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');