]> git.mxchange.org Git - core.git/blob - framework/main/classes/iterator/file/class_FileIterator.php
Continued:
[core.git] / framework / main / classes / iterator / file / class_FileIterator.php
1 <?php
2 // Own namespace
3 namespace Org\Mxchange\CoreFramework\Iterator\File;
4
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;
9
10 // Import SPL stuff
11 use \BadMethodCallException;
12 use \InvalidArgumentException;
13 use \OutOfBoundsException;
14 use \SeekableIterator;
15
16 /**
17  * A file iterator
18  *
19  * @author              Roland Haeder <webmaster@ship-simu.org>
20  * @version             0.0.0
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
24  *
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.
29  *
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.
34  *
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/>.
37  */
38 class FileIterator extends BaseIterator implements SeekableIterator {
39         // Load traits
40         use BinaryFileTrait;
41
42         /**
43          * Protected constructor
44          *
45          * @return      void
46          */
47         private function __construct () {
48                 // Call parent constructor
49                 parent::__construct(__CLASS__);
50         }
51
52         /**
53          * Creates an instance of this class
54          *
55          * @param       $binaryFileInstance     An instance of a BinaryFile class
56          * @return      $iteratorInstance       An instance of a Iterator class
57          */
58         public final static function createFileIterator (BinaryFile $binaryFileInstance) {
59                 // Get new instance
60                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: binaryFileInstance=%s - CALLED!', $binaryFileInstance->__toString()));
61                 $iteratorInstance = new FileIterator();
62
63                 // Set the instance here
64                 $iteratorInstance->setBinaryFileInstance($binaryFileInstance);
65
66                 // Return the prepared instance
67                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
68                 return $iteratorInstance;
69         }
70
71         /**
72          * Gets currently read data
73          *
74          * @return      $current        Currently read data
75          * @throws      BadMethodCallException  If valid() is FALSE
76          */
77         public function current () {
78                 // Is condition given?
79                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
80                 if (!$this->valid()) {
81                         // Throw BMCE
82                         throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
83                 }
84
85                 // Call file instance
86                 $current = $this->getBinaryFileInstance()->current();
87
88                 // Return it
89                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: current[]=%s - EXIT!', gettype($current)));
90                 return $current;
91         }
92
93         /**
94          * Gets current seek position ("key").
95          *
96          * @return      $key    Current key in iteration
97          * @throws      BadMethodCallException  If valid() is FALSE
98          */
99         public function key () {
100                 // Is condition given?
101                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
102                 if (!$this->valid()) {
103                         // Throw BMCE
104                         throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
105                 }
106
107                 // Get key from file instance
108                 $key = $this->getBinaryFileInstance()->determineSeekPosition();
109
110                 // Return key
111                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: key[%s]=%s - EXIT!', gettype($key), $key));
112                 return $key;
113         }
114
115         /**
116          * Advances to next "file" of bytes
117          *
118          * @return      void
119          */
120         public function next () {
121                 // Call file instance
122                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
123                 $this->getBinaryFileInstance()->next();
124
125                 // Trace message
126                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
127         }
128
129         /**
130          * Rewinds to the beginning of the file
131          *
132          * @return      $status         Status of this operation
133          */
134         public function rewind () {
135                 // Call file instance
136                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
137                 $this->getBinaryFileInstance()->rewind();
138
139                 // Trace message
140                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
141         }
142
143         /**
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.
146          *
147          * @return      $isValid        Whether the next entry is valid
148          */
149         public function valid () {
150                 // Call file instance
151                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
152                 $isValid = $this->getBinaryFileInstance()->valid();
153
154                 // Return flag
155                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isValid=%d - EXIT!', intval($isValid)));
156                 return $isValid;
157         }
158
159         /**
160          * Seeks to given position
161          *
162          * @param       $seekPosition   Seek position in file
163          * @return      void
164          * @throws      OutOfBoundsException    If the position is not seekable
165          */
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) {
170                         // Throw IAE
171                         throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
172                 }
173
174                 // Call file instance
175                 $this->getBinaryFileInstance()->seek($seekPosition);
176
177                 // Trace message
178                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
179         }
180
181 }