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 - 2022 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 }