3 namespace Org\Mxchange\CoreFramework\Iterator\File;
5 // Import framework stuff
6 use Org\Mxchange\CoreFramework\Filesystem\File\BinaryFile;
7 use Org\Mxchange\CoreFramework\Iterator\BaseIterator;
8 use Org\Mxchange\CoreFramework\Traits\File\BinaryFileTrait;
11 use \BadMethodCallException;
12 use \InvalidArgumentException;
13 use \OutOfBoundsException;
14 use \SeekableIterator;
19 * @author Roland Haeder <webmaster@ship-simu.org>
21 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2021 Core Developer Team
22 * @license GNU GPL 3.0 or any newer version
23 * @link http://www.ship-simu.org
25 * This program is free software: you can redistribute it and/or modify
26 * it under the terms of the GNU General Public License as published by
27 * the Free Software Foundation, either version 3 of the License, or
28 * (at your option) any later version.
30 * This program is distributed in the hope that it will be useful,
31 * but WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 * GNU General Public License for more details.
35 * You should have received a copy of the GNU General Public License
36 * along with this program. If not, see <http://www.gnu.org/licenses/>.
38 class FileIterator extends BaseIterator implements SeekableIterator {
43 * Protected constructor
47 private function __construct () {
48 // Call parent constructor
49 parent::__construct(__CLASS__);
53 * Creates an instance of this class
55 * @param $binaryFileInstance An instance of a BinaryFile class
56 * @return $iteratorInstance An instance of a Iterator class
58 public final static function createFileIterator (BinaryFile $binaryFileInstance) {
60 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: binaryFileInstance=%s - CALLED!', $binaryFileInstance->__toString()));
61 $iteratorInstance = new FileIterator();
63 // Set the instance here
64 $iteratorInstance->setBinaryFileInstance($binaryFileInstance);
66 // Return the prepared instance
67 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
68 return $iteratorInstance;
72 * Gets currently read data
74 * @return $current Currently read data
75 * @throws BadMethodCallException If valid() is FALSE
77 public function current () {
78 // Is condition given?
79 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
80 if (!$this->valid()) {
82 throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
86 $current = $this->getBinaryFileInstance()->current();
89 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: current[]=%s - EXIT!', gettype($current)));
94 * Gets current seek position ("key").
96 * @return $key Current key in iteration
97 * @throws BadMethodCallException If valid() is FALSE
99 public function key () {
100 // Is condition given?
101 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
102 if (!$this->valid()) {
104 throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
107 // Get key from file instance
108 $key = $this->getBinaryFileInstance()->determineSeekPosition();
111 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: key[%s]=%s - EXIT!', gettype($key), $key));
116 * Advances to next "file" of bytes
120 public function next () {
121 // Call file instance
122 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
123 $this->getBinaryFileInstance()->next();
126 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
130 * Rewinds to the beginning of the file
132 * @return $status Status of this operation
134 public function rewind () {
135 // Call file instance
136 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
137 $this->getBinaryFileInstance()->rewind();
140 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
144 * Checks wether the current entry is valid (not at the end of the file).
145 * This method will return true if an emptied (nulled) entry has been found.
147 * @return $isValid Whether the next entry is valid
149 public function valid () {
150 // Call file instance
151 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
152 $isValid = $this->getBinaryFileInstance()->valid();
155 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isValid=%d - EXIT!', intval($isValid)));
160 * Seeks to given position
162 * @param $seekPosition Seek position in file
164 * @throws OutOfBoundsException If the position is not seekable
166 public function seek (int $seekPosition) {
167 // Validate parameter
168 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence));
169 if ($seekPosition < 0) {
171 throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
174 // Call file instance
175 $this->getBinaryFileInstance()->seek($seekPosition);
178 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');