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\Iterator\Filesystem\SeekableWritableFileIterator;
   9 use Org\Mxchange\CoreFramework\Traits\File\BinaryFileTrait;
  10
  11 // Import SPL stuff
  12 use \BadMethodCallException;
  13 use \InvalidArgumentException;
  14
  15 /**
  16  * A file iterator
  17  *
  18  * @author              Roland Haeder <webmaster@ship-simu.org>
  19  * @version             0.0.0
  20  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
  21  * @license             GNU GPL 3.0 or any newer version
  22  * @link                http://www.ship-simu.org
  23  *
  24  * This program is free software: you can redistribute it and/or modify
  25  * it under the terms of the GNU General Public License as published by
  26  * the Free Software Foundation, either version 3 of the License, or
  27  * (at your option) any later version.
  28  *
  29  * This program is distributed in the hope that it will be useful,
  30  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  31  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  32  * GNU General Public License for more details.
  33  *
  34  * You should have received a copy of the GNU General Public License
  35  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  36  */
  37 class FileIterator extends BaseIterator implements SeekableWritableFileIterator {
  38         // Load traits
  39         use BinaryFileTrait;
  40
  41         /**
  42          * Protected constructor
  43          *
  44          * @return      void
  45          */
  46         protected function __construct () {
  47                 // Call parent constructor
  48                 parent::__construct(__CLASS__);
  49         }
  50
  51         /**
  52          * Creates an instance of this class
  53          *
  54          * @param       $binaryFileInstance     An instance of a BinaryFile class
  55          * @return      $iteratorInstance       An instance of a Iterator class
  56          */
  57         public final static function createFileIterator (BinaryFile $binaryFileInstance) {
  58                 // Get new instance
  59                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: binaryFileInstance=%s - CALLED!', $binaryFileInstance->__toString()));
  60                 $iteratorInstance = new FileIterator();
  61
  62                 // Set the instance here
  63                 $iteratorInstance->setBinaryFileInstance($binaryFileInstance);
  64
  65                 // Return the prepared instance
  66                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
  67                 return $iteratorInstance;
  68         }
  69
  70         /**
  71          * Gets currently read data
  72          *
  73          * @return      $current        Currently read data
  74          * @throws      BadMethodCallException  If valid() is FALSE
  75          */
  76         public function current () {
  77                 // Is condition given?
  78                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
  79                 if (!$this->valid()) {
  80                         // Throw BMCE
  81                         throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
  82                 }
  83
  84                 // Call file instance
  85                 $current = $this->getBinaryFileInstance()->current();
  86
  87                 // Return it
  88                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: current[]=%s - EXIT!', gettype($current)));
  89                 return $current;
  90         }
  91
  92         /**
  93          * Gets current seek position ("key").
  94          *
  95          * @return      $key    Current key in iteration
  96          * @throws      BadMethodCallException  If valid() is FALSE
  97          */
  98         public function key () {
  99                 // Is condition given?
 100                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 101                 if (!$this->valid()) {
 102                         // Throw BMCE
 103                         throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
 104                 }
 105
 106                 // Get key from file instance
 107                 $key = $this->getBinaryFileInstance()->determineSeekPosition();
 108
 109                 // Return key
 110                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: key[%s]=%s - EXIT!', gettype($key), $key));
 111                 return $key;
 112         }
 113
 114         /**
 115          * Advances to next "file" of bytes
 116          *
 117          * @return      void
 118          */
 119         public function next () {
 120                 // Call file instance
 121                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 122                 $this->getBinaryFileInstance()->next();
 123
 124                 // Trace message
 125                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 126         }
 127
 128         /**
 129          * Rewinds to the beginning of the file
 130          *
 131          * @return      $status         Status of this operation
 132          */
 133         public function rewind () {
 134                 // Call file instance
 135                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 136                 $this->getBinaryFileInstance()->rewind();
 137
 138                 // Trace message
 139                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 140         }
 141
 142         /**
 143          * Checks wether the current entry is valid (not at the end of the file).
 144          * This method will return true if an emptied (nulled) entry has been found.
 145          *
 146          * @return      $isValid        Whether the next entry is valid
 147          */
 148         public function valid () {
 149                 // Call file instance
 150                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 151                 $isValid = $this->getBinaryFileInstance()->valid();
 152
 153                 // Return flag
 154                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isValid=%d - EXIT!', intval($isValid)));
 155                 return $isValid;
 156         }
 157
 158         /**
 159          * Seeks to given position
 160          *
 161          * @param       $seekPosition   Seek position in file
 162          * @param       $whence                 Added to offset (default: only use offset to seek to)
 163          * @return      $status                 Status of this operation
 164          * @throws      InvalidArgumentException        If a parameter is not valid
 165          */
 166         public function seek (int $seekPosition, int $whence = SEEK_SET) {
 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 InvalidArgumentException(sprintf('seekPosition=%d is not valid', $seekPosition));
 172                 }
 173
 174                 // Call file instance
 175                 $status = $this->getBinaryFileInstance()->seek($seekPosition, $whence);
 176
 177                 // Return status
 178                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: status=%d - EXIT!', intval($status)));
 179                 return $status;
 180         }
 181
 182         /**
 183          * Size of file stack
 184          *
 185          * @return      $size   Size (in bytes) of file
 186          */
 187         public function size () {
 188                 // Call the file object
 189                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 190                 $size = $this->getBinaryFileInstance()->size();
 191
 192                 // Return size
 193                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: size=%d - EXIT!', $size));
 194                 return $size;
 195         }
 196
 197         /**
 198          * Reads given amount of bytes from file.
 199          *
 200          * @param       $bytes  Amount of bytes to read
 201          * @return      $data   Data read from file
 202          */
 203         public function read (int $bytes = 0) {
 204                 // Validate parameter
 205                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: bytes=%d - CALLED!', $bytes));
 206                 if ($bytes < 0) {
 207                         // Throw IAE
 208                         throw new InvalidArgumentException(sprintf('bytes=%d is not valid', $bytes));
 209                 }
 210
 211                 // Call file instance
 212                 $data = $this->getBinaryFileInstance()->read($bytes);
 213
 214                 // Return data
 215                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
 216                 return $data;
 217         }
 218
 219         /**
 220          * Analyzes entries in index file. This will count all found (and valid)
 221          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
 222          * only gaps are found, the file is considered as "virgin" (no entries).
 223          *
 224          * @return      void
 225          */
 226         public function analyzeFileStructure () {
 227                 // Just call the file instance
 228                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 229                 $this->getBinaryFileInstance()->analyzeFileStructure();
 230
 231                 // Trace message
 232                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 233         }
 234
 235         /**
 236          * Checks whether the file header is initialized
 237          *
 238          * @return      $isInitialized  Whether the file header is initialized
 239          */
 240         public function isFileHeaderInitialized () {
 241                 // Just call the file instance
 242                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 243                 $isInitialized = $this->getBinaryFileInstance()->isFileHeaderInitialized();
 244
 245                 // Return flag
 246                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isInitialized=%d - EXIT!', intval($isInitialized)));
 247                 return $isInitialized;
 248         }
 249
 250         /**
 251          * Creates the assigned file
 252          *
 253          * @return      void
 254          */
 255         public function createFileHeader () {
 256                 // Just call the file instance
 257                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 258                 $this->getBinaryFileInstance()->createFileHeader();
 259
 260                 // Trace message
 261                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 262         }
 263
 264         /**
 265          * Pre-allocates file (if enabled) with some space for later faster write access.
 266          *
 267          * @param       $type   Type of the file
 268          * @return      void
 269          * @throws      InvalidArgumentException        If a parameter is not valid
 270          */
 271         public function preAllocateFile (string $type) {
 272                 // Validate parameter
 273                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: type=%s - CALLED!', $type));
 274                 if (empty($type)) {
 275                         // Throw IAE
 276                         throw new InvalidArgumentException('Parameter "type" is empty');
 277                 }
 278
 279                 // Just call the file instance
 280                 $this->getBinaryFileInstance()->preAllocateFile($type);
 281
 282                 // Trace message
 283                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 284         }
 285
 286         /**
 287          * Initializes counter for valid entries, arrays for damaged entries and
 288          * an array for gap seek positions. If you call this method on your own,
 289          * please re-analyze the file structure. So you are better to call
 290          * analyzeFileStructure() instead of this method.
 291          *
 292          * @return      void
 293          */
 294         public function initCountersGapsArray () {
 295                 // Call file instance
 296                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 297                 $this->getBinaryFileInstance()->initCountersGapsArray();
 298
 299                 // Trace message
 300                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 301         }
 302
 303         /**
 304          * Getter for header size
 305          *
 306          * @return      $totalEntries   Size of file header
 307          */
 308         public final function getHeaderSize () {
 309                 // Call file instance
 310                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 311                 $size = $this->getBinaryFileInstance()->getHeaderSize();
 312
 313                 // Return size
 314                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: size=%d - EXIT!', $size));
 315                 return $size;
 316         }
 317
 318         /**
 319          * Setter for header size
 320          *
 321          * @param       $headerSize             Size of file header
 322          * @return      void
 323          */
 324         public final function setHeaderSize (int $headerSize) {
 325                 // Call file instance
 326                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: headerSize=%d - CALLED!', $headerSize));
 327                 $this->getBinaryFileInstance()->setHeaderSize($headerSize);
 328
 329                 // Trace message
 330                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 331         }
 332
 333         /**
 334          * Getter for header array
 335          *
 336          * @return      $header         Header array
 337          */
 338         public final function getHeader () {
 339                 // Call file instance
 340                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 341                 $header = $this->getBinaryFileInstance()->getHeader();
 342
 343                 // Return it
 344                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: header()=%d - EXIT!', count($header)));
 345                 return $header;
 346         }
 347
 348         /**
 349          * Setter for header
 350          *
 351          * @param       $header         Array for a file header
 352          * @return      void
 353          */
 354         public final function setHeader (array $header) {
 355                 // Call file instance
 356                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: header()=%d - CALLED!', count($header)));
 357                 $this->getBinaryFileInstance()->setHeader($header);
 358
 359                 // Trace message
 360                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 361         }
 362
 363         /**
 364          * Updates seekPosition attribute from file to avoid to much access on file.
 365          *
 366          * @return      void
 367          */
 368         public function updateSeekPosition () {
 369                 // Call file instance
 370                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 371                 $this->getBinaryFileInstance()->updateSeekPosition();
 372
 373                 // Trace message
 374                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 375         }
 376
 377         /**
 378          * Getter for total entries
 379          *
 380          * @return      $totalEntries   Total entries in this file
 381          */
 382         public final function getCounter () {
 383                 // Call file instance
 384                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 385                 $counter = $this->getBinaryFileInstance()->getCounter();
 386
 387                 // Return counter
 388                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: counter=%d - EXIT!', $counter));
 389                 return $counter;
 390         }
 391
 392         /**
 393          * "Getter" for file size
 394          *
 395          * @return      $fileSize       Size of currently loaded file
 396          */
 397         public function getFileSize () {
 398                 // Call file instance
 399                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 400                 $size = $this->getBinaryFileInstance()->getFileSize();
 401
 402                 // Return size
 403                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: size=%d - EXIT!', $size));
 404                 return $size;
 405         }
 406
 407         /**
 408          * Writes data at given position
 409          *
 410          * @param       $seekPosition   Seek position
 411          * @param       $data                   Data to be written
 412          * @param       $flushHeader    Whether to flush the header (default: flush)
 413          * @return      void
 414          * @throws      InvalidArgumentException        If a parameter is not valid
 415          */
 416         public function writeData (int $seekPosition, string $data, bool $flushHeader = true) {
 417                 // Validate parameter
 418                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,data(%d)=%s,flushHeader=%d - CALLED!', $seekPosition, strlen($data), $data, intval($flushHeader)));
 419                 if ($seekPosition < 0) {
 420                         // Throw IAE
 421                         throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid', $seekPosition));
 422                 } elseif (empty($data)) {
 423                         // Throw it again
 424                         throw new InvalidArgumentException('Parameter "data" is empty');
 425                 }
 426
 427                 // Call file instance
 428                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: Calling this->binaryFileInstance->writeData(%d,data()=%d,%d) ...', $seekPosition, strlen($data), intval($flushHeader)));
 429                 $this->getBinaryFileInstance()->writeData($seekPosition, $data, $flushHeader);
 430
 431                 // Trace message
 432                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
 433         }
 434
 435         /**
 436          * Writes at given position by seeking to it.
 437          *
 438          * @param       $seekPosition   Seek position in file
 439          * @param       $dataStream             Data to be written
 440          * @return      mixed                   Number of writes bytes or false on error
 441          * @throws      InvalidArgumentException        If a parameter is not valid
 442          */
 443         public function writeAtPosition (int $seekPosition, string $dataStream) {
 444                 // Validate parameter
 445                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,dataStream(%d)=%s - CALLED!', $seekPosition, strlen($dataStream), $dataStream));
 446                 if ($seekPosition < 0) {
 447                         // Invalid seek position
 448                         throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid.', $seekPosition));
 449                 } elseif (empty($dataStream)) {
 450                         // Empty dataStream
 451                         throw new InvalidArgumentException('Parameter "dataStream" is empty');
 452                 }
 453
 454                 // Call iterated object's method
 455                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: Calling this->binaryFileInstance->writeAtPosition(%d, %s) ...', $seekPosition, $dataStream));
 456                 $status = $this->getBinaryFileInstance()->writeAtPosition($seekPosition, $dataStream);
 457
 458                 // Return status
 459                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: status[%s]=%d - EXIT!', gettype($status), $status));
 460                 return $status;
 461         }
 462
 463         /**
 464          * Getter for seek position
 465          *
 466          * @return      $seekPosition   Current seek position (stored here in object)
 467          */
 468         public function getSeekPosition () {
 469                 // Call file instance
 470                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
 471                 $seekPosition = $this->getBinaryFileInstance()->getSeekPosition();
 472
 473                 // Return position
 474                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition[%s]=%d - EXIT!', gettype($seekPosition), $seekPosition));
 475                 return $seekPosition;
 476         }
 477
 478         /**
 479          * Writes given value to the file and returns a hash and gap position for it
 480          *
 481          * @param       $groupId        Group identifier
 482          * @param       $value          Value to be added to the stack
 483          * @return      $data           Hash and gap position
 484          * @throws      InvalidArgumentException        If a parameter is not valid
 485          */
 486         public function writeValueToFile (string $groupId, $value) {
 487                 // Validate parameter
 488                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: groupId=%s,value[]=%s - CALLED!', $groupId, gettype($value)));
 489                 if (empty($groupId)) {
 490                         // Throw IAE
 491                         throw new InvalidArgumentException('Parameter "groupId" is empty');
 492                 } elseif (is_resource($value) || is_object($value)) {
 493                         // Resources and objects are nothing for file-based indexes (mostly)
 494                         throw new InvalidArgumentException(sprintf('value[]=%s is not supported by file-based indexes', gettype($value)));
 495                 }
 496
 497                 // Call file instance
 498                 $data = $this->getBinaryFileInstance()->writeValueToFile($groupId, $value);
 499
 500                 // Return data
 501                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
 502                 return $data;
 503         }
 504
 505         /**
 506          * Writes given raw data to the file and returns a gap position and length
 507          *
 508          * @param       $groupId        Group identifier
 509          * @param       $hash           Hash from encoded value
 510          * @param       $encoded        Encoded value to be written to the file
 511          * @return      $data           Gap position and length of the raw data
 512          */
 513         public function writeDataToFreeGap (string $groupId, string $hash, string $encoded) {
 514                 // Validate parameter
 515                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: groupId=%s,hash=%s,encoded(%d)=%s - CALLED!', $groupId, $hash, strlen($encoded), $encoded));
 516
 517                 // Call file instance
 518                 $data = $this->getBinaryFileInstance()->writeDataToFreeGap($groupId, $hash, $encoded);
 519
 520                 // Return data
 521                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
 522                 return $data;
 523         }
 524
 525         /**
 526          * Searches for next suitable gap the given length of data can fit in
 527          * including padding bytes.
 528          *
 529          * @param       $length                 Length of raw data
 530          * @return      $seekPosition   Found next gap's seek position
 531          * @throws      InvalidArgumentException        If a parameter is invalid
 532          */
 533         public function searchNextGap (int $length) {
 534                 // Validate parameter
 535                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: length=%d - CALLED!', $length));
 536                 if ($length <= 0) {
 537                         // Throw IAE
 538                         throw new InvalidArgumentException(sprintf('length=%d is not valid', $length));
 539                 }
 540
 541                 // Call file instance
 542                 $seekPosition = $this->getBinaryFileInstance()->searchNextGap($length);
 543
 544                 // Return position
 545                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition[%s]=%d - EXIT!', gettype($seekPosition), $seekPosition));
 546                 return $seekPosition;
 547         }
 548
 549 }