From 64adf2e0b8dc0f38717df467fe7a64c2ed39f32c Mon Sep 17 00:00:00 2001
From: =?utf8?q?Roland=20H=C3=A4der?= <roland@mxchange.org>
Date: Wed, 9 Dec 2020 02:41:22 +0100
Subject: [PATCH] Continued: - renamed ambicious methods key/valid/... as they
 are iterator-only methods - also got rid of key() as determineSeekPosition()
 and getSeekPosition() are   there already
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Signed-off-by: Roland Häder <roland@mxchange.org>
---
 .../binary/class_BaseBinaryFile.php           | 238 +++++++++---------
 1 file changed, 117 insertions(+), 121 deletions(-)

diff --git a/framework/main/classes/file_directories/binary/class_BaseBinaryFile.php b/framework/main/classes/file_directories/binary/class_BaseBinaryFile.php
index 4ed66c22..35beea36 100644
--- a/framework/main/classes/file_directories/binary/class_BaseBinaryFile.php
+++ b/framework/main/classes/file_directories/binary/class_BaseBinaryFile.php
@@ -180,7 +180,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 * @return	void
 	 */
 	private function setBackBuffer (string $backBuffer) {
-		// ... and set it
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Setting backBuffer(%d)=%s - CALLED!', strlen($backBuffer), $backBuffer));
 		$this->backBuffer = $backBuffer;
 	}
 
@@ -190,17 +190,18 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 * @return	$backBuffer		Characters "stored" in back-buffer
 	 */
 	private function getBackBuffer () {
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Getting this->backBuffer(%d)=%s - CALLED!', strlen($this->backBuffer), $this->backBuffer));
 		return $this->backBuffer;
 	}
 
 	/**
-	 * Setter for currentBlock field
+	 * Setter for current field
 	 *
-	 * @param	$currentBlock	Characters to set a currently loaded block
+	 * @param	$current	Characters to set a currently loaded block
 	 * @return	void
 	 */
 	private function setCurrentBlock (string $currentBlock) {
-		// ... and set it
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Setting currentBlock(%d)=%s - CALLED!', strlen($currentBlock), $currentBlock));
 		$this->currentBlock = $currentBlock;
 	}
 
@@ -210,7 +211,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 * @return	$current	Currently read data
 	 */
 	public function getCurrentBlock () {
-		// Return it
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Getting this->currentBlock(%d)=%s - CALLED!', strlen($this->currentBlock), $this->currentBlock));
 		return $this->currentBlock;
 	}
 
@@ -286,14 +287,14 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	private function markFileGapsOnly (string $type, int $minimumBlockLength) {
 		// Very simple to do ...
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: type=%s,minimumBlockLength=%d - CALLED!', $type, $minimumBlockLength));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: type=%s,minimumBlockLength=%d - CALLED!', $type, $minimumBlockLength));
 		for ($idx = 0; $idx < FrameworkBootstrap::getConfigurationInstance()->getConfigEntry($type . '_pre_allocate_count'); $idx++) {
 			// Mark start and end position as gap
 			$this->addGap($idx * $minimumBlockLength, $idx * $minimumBlockLength + $minimumBlockLength);
 		}
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -304,24 +305,24 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	private function isFileGapsOnly () {
 		// Count every gap
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$gapsSize = 0;
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: this->gaps()=%d', count($this->gaps)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: this->gaps()=%d', count($this->gaps)));
 		foreach ($this->gaps as $gap) {
 			// Calculate size of found gap: end-start including both
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: gap[%s]=%d,ga[%s]=%d', self::GAPS_INDEX_START, $gap[self::GAPS_INDEX_START], self::GAPS_INDEX_END, $gap[self::GAPS_INDEX_END]));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: gap[%s]=%d,ga[%s]=%d', self::GAPS_INDEX_START, $gap[self::GAPS_INDEX_START], self::GAPS_INDEX_END, $gap[self::GAPS_INDEX_END]));
 			$gapsSize += ($gap[self::GAPS_INDEX_END] - $gap[self::GAPS_INDEX_START]);
 
 			// Debug message
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: gapsSize=%d', $gapsSize));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: gapsSize=%d', $gapsSize));
 		}
 
 		// Total gap size + header size must be same as file size
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: gapsSize=%d,this->fileSize=%d', $gapsSize, $this->getFileSize()));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: gapsSize=%d,this->fileSize=%d', $gapsSize, $this->getFileSize()));
 		$isGapsOnly = ($gapsSize + 1 == $this->getFileSize());
 
 		// Return status
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isGapsOnly=%d - EXIT!', intval($isGapsOnly)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isGapsOnly=%d - EXIT!', intval($isGapsOnly)));
 		return $isGapsOnly;
 	}
 
@@ -334,14 +335,14 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	private function addGap(int $startPosition, int $endPosition) {
 		// Push to gaps array
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: startPosition=%d,endPosition=%d - CALLED!', $startPosition, $endPosition));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: startPosition=%d,endPosition=%d - CALLED!', $startPosition, $endPosition));
 		array_push($this->gaps, [
 			self::GAPS_INDEX_START  => $startPosition,
 			self::GAPS_INDEX_END    => $endPosition,
 		]);
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -351,11 +352,11 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	private function initBackBuffer () {
 		// Simply call the setter
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$this->setBackBuffer('');
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -367,22 +368,22 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	protected function rewindUpdateSeekPosition (bool $flushHeader = false) {
 		// Seek to beginning of file
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: flushHeader=%d - CALLED!', intval($flushHeader)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: flushHeader=%d - CALLED!', intval($flushHeader)));
 		$this->rewind();
 
 		// And update seek position ...
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->updateSeekPosition() ...');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->updateSeekPosition() ...');
 		$this->updateSeekPosition();
 
 		// Flush headers?
 		if ($flushHeader) {
 			// ... to write it back into the file
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->flushFileHeader() ...');
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->flushFileHeader() ...');
 			$this->flushFileHeader();
 		}
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -392,11 +393,11 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	protected function seekToOldPosition () {
 		// Seek to currently ("old") saved position
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
-		$this->seek($this->getSeekPosition());
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		$this->seek($this->determineSeekPosition());
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -407,15 +408,15 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	protected function initFile (SplFileInfo $fileInfoInstance) {
 		// Get a file i/o pointer instance
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: fileInfoInstance[%s]=%s - CALLED!', get_class($fileInfoInstance), $fileInfoInstance));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: fileInfoInstance[%s]=%s - CALLED!', get_class($fileInfoInstance), $fileInfoInstance));
 		$pointerInstance = ObjectFactory::createObjectByConfiguredName('file_raw_input_output_class', array($fileInfoInstance));
 
 		// ... and set it here
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Setting pointerInstance=%s ...', $pointerInstance->__toString()));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Setting pointerInstance=%s ...', $pointerInstance->__toString()));
 		$this->setPointerInstance($pointerInstance);
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -427,21 +428,21 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	protected function markCurrentBlockAsEmpty (int $length) {
 		// Validate parameter
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: length=%d - CALLED!', $length));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: length=%d - CALLED!', $length));
 		if ($length < 1) {
 			// Length cannot below one
 			throw new InvalidArgumentException(sprintf('length=%d is not valid', $length));
 		}
 
 		// Get current seek position
-		$currentPosition = $this->key();
+		$currentPosition = $this->determineSeekPosition();
 
 		// Now add it as gap entry
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: currentPosition=%d', $currentPosition));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: currentPosition=%d', $currentPosition));
 		$this->addGap(($currentPosition - $length), $currentPosition);
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -454,7 +455,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public function initCountersGapsArray () {
 		// Init counter and seek position to header size
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$this->setCounter(0);
 		$this->setSeekPosition($this->getHeaderSize());
 
@@ -463,7 +464,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		$this->damagedEntries = [];
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -473,15 +474,15 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public function updateSeekPosition () {
 		// Get key (= seek position)
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
-		$seekPosition = $this->key();
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		$seekPosition = $this->determineSeekPosition();
 
 		// And set it here
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: seekPosition=%d', $seekPosition));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: seekPosition=%d', $seekPosition));
 		$this->setSeekPosition($seekPosition);
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -493,7 +494,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public static function isBlockSeparatorFound (string $str) {
 		// Validate parameter
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: str=%s - CALLED!', $str));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: str=%s - CALLED!', $str));
 		if (empty($str)) {
 			// Throw IAE
 			throw new InvalidArgumentException('Parameter "str" is empty');
@@ -503,7 +504,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		$isFound = (strpos($str, chr(self::SEPARATOR_ENTRIES)) !== false);
 
 		// Return result
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isFound=%d - EXIT!', intval($isFound)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isFound=%d - EXIT!', intval($isFound)));
 		return $isFound;
 	}
 
@@ -590,7 +591,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public function isFileHeaderInitialized () {
 		// Default is not initialized
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$isInitialized = false;
 
 		// Is the file initialized?
@@ -599,19 +600,19 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 			$this->rewind();
 
 			// Read file header
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->readFileHeader() ...');
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->readFileHeader() ...');
 			$this->readFileHeader();
 
 			// Get header count
 			$headerCount = count($this->getHeader());
 
 			// The above method does already check the header
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: headerCount=%d', $headerCount));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: headerCount=%d', $headerCount));
 			$isInitialized = ($headerCount > 0);
 		}
 
 		// Return result
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isInitialized=%d - EXIT!', intval($isInitialized)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isInitialized=%d - EXIT!', intval($isInitialized)));
 		return $isInitialized;
 	}
 
@@ -619,24 +620,28 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 * Checks whether the assigned file has been initialized
 	 *
 	 * @return	$isInitialized		Whether the file's size is zero
+	 * @throws	UnexpectedValueException	If an unexpected value was returned
 	 */
 	public function isFileInitialized () {
 		// Get it from iterator which holds the pointer instance. If false is returned
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$fileSize = $this->size();
 
 		/*
 		 * The returned file size should not be false or NULL as this means
 		 * that the pointer class does not work correctly.
 		 */
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: fileSize[%s]=%d', gettype($fileSize), $fileSize));
-		assert(is_int($fileSize));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: fileSize[%s]=%d', gettype($fileSize), $fileSize));
+		if (!is_int($fileSize)) {
+			// Bad file?
+			throw new UnexpectedValueException(sprintf('fileSize[]=%s is unexpected', gettype($fileSize)));
+		}
 
 		// Is more than 0 returned?
 		$isInitialized = ($fileSize > 0);
 
 		// Return result
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isInitialized=%d - EXIT!', intval($isInitialized)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: isInitialized=%d - EXIT!', intval($isInitialized)));
 		return $isInitialized;
 	}
 
@@ -648,7 +653,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public function createFileHeader () {
 		// The file's header should not be initialized here
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		if ($this->isFileHeaderInitialized()) {
 			// Bad method call
 			//* DEBUG-DIE: */ die(sprintf('[%s:%d]: this=%s', __METHOD__, __LINE__, print_r($this, TRUE)));
@@ -656,15 +661,15 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		}
 
 		// Simple flush file header which will create it.
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->flushFileHeader() ...');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->flushFileHeader() ...');
 		$this->flushFileHeader();
 
 		// Rewind seek position (to beginning of file) and update/flush file header
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->rewindUpdateSeekPosition() ...');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->rewindUpdateSeekPosition() ...');
 		$this->rewindUpdateSeekPosition();
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -676,7 +681,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public function preAllocateFile (string $type) {
 		// Is it enabled?
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: type=%s - CALLED!', $type));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: type=%s - CALLED!', $type));
 		if (empty($type)) {
 			// Empty type
 			throw new InvalidArgumentException('Parameter "type" is empty');
@@ -694,30 +699,31 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		$fileSize = $this->getFileSize();
 
 		// Calulcate seek position
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: minimumBlockLength=%d,fileSize=%d', $minimumBlockLength, $fileSize));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: minimumBlockLength=%d,fileSize=%d', $minimumBlockLength, $fileSize));
 		$seekPosition = $minimumBlockLength * FrameworkBootstrap::getConfigurationInstance()->getConfigEntry($type . '_pre_allocate_count') + $fileSize ;
 
 		// Now simply write a NUL there. This will pre-allocate the file.
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->writeAtPosition(%d,NUL) ...', $seekPosition));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->writeAtPosition(%d,NUL) ...', $seekPosition));
 		$this->writeAtPosition($seekPosition, chr(0));
 
 		// Is the seek position zero?
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: fileSize=%d', $fileSize));
 		if ($fileSize == 0) {
 			// Mark file as gaps-only
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->markGapsOnly(%s) ...', $type));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->markGapsOnly(%s,%d) ...', $type, $minimumBlockLength));
 			$this->markFileGapsOnly($type, $minimumBlockLength);
 		} else {
 			// Analyze file structure
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->analyzeFileStructure() ...');
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->analyzeFileStructure() ...');
 			$this->analyzeFileStructure();
 		}
 
 		// Rewind seek position
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->rewind() ...');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->rewind() ...');
 		$this->rewind();
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -727,11 +733,11 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 */
 	public function determineSeekPosition () {
 		// Call pointer instance
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$seekPosition = $this->getPointerInstance()->determineSeekPosition();
 
 		// Return position
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: seekPosition=%d - EXIT!', $seekPosition));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: seekPosition=%d - EXIT!', $seekPosition));
 		return $seekPosition;
 	}
 
@@ -813,45 +819,52 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		}
 
 		// Init counters and gaps array
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->initCounterGapsArrays() ...');
 		$this->initCountersGapsArray();
 
 		// Output message (as this may take some time)
 		self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('Analyzing file structure ... (this may take some time)'));
 
 		// First rewind to the begining
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->rewind() ...');
 		$this->rewind();
 
 		// Then try to load all entries
-		while ($this->valid()) {
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Looping through file');
+		while ($this->isValid()) {
 			// Get current entry
 			$current = $this->getCurrentBlock();
 
+			// Go to next entry
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->readNextBlock() ...');
+			$this->readNextBlock();
+
 			/*
 			 * If the block is empty, maybe the whole file is? This could mean
 			 * that the file has been pre-allocated.
 			 */
-			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: current[]=%s', gettype($current)));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: current(%d)[]=%s', strlen($current), gettype($current)));
 			if (empty($current)) {
 				// Then skip this part
 				//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: current[]=%s is empty - CONTINUE!', gettype($current)));
 				continue;
 			}
 
-			// Go to next entry
-			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: current()=%d', strlen($current)));
-			$this->next();
+			// Handle current record
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: current(%d)[]=%s', strlen($current), gettype($current)));
 		}
 
 		// If the last read block is empty, check gaps
 		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: current()=%d', strlen($current)));
 		if (empty($current)) {
 			// Output message
-			self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('Found a total of %d gaps.', count($this->gaps)));
+			self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Found a total of %d gaps.', count($this->gaps)));
 
 			// Check gaps, if the whole file is empty.
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->isFileGapsOnly() ...');
 			if ($this->isFileGapsOnly()) {
 				// Only gaps, so don't continue here.
-				/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: File is gaps-only - EXIT!');
+				//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: File is gaps-only - EXIT!');
 				return;
 			}
 
@@ -861,8 +874,10 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 			 * defragmentation is to far in the past, or if a "hard" limit has
 			 * reached, run defragmentation.
 			 */
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->isDefragmentationNeeded() ...');
 			if ($this->isDefragmentationNeeded()) {
 				// Run "defragmentation"
+				//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Calling this->doRunDefragmentation() ...');
 				$this->doRunDefragmentation();
 			}
 		}
@@ -872,23 +887,23 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	}
 
 	/**
-	 * Advances to next "block" of bytes
+	 * Reads next "block" of bytes into $currentBlock field
 	 *
 	 * @return	void
-	 * @throws	UnexpectedValueException	If some unexpected value was found
+	 * @throws	BadMethodCallException	If this method was called without prior valid() call
 	 */
-	public function next () {
+	public function readNextBlock () {
 		// Is there nothing to read?
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
-		if (!$this->valid()) {
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
+		if (!$this->isValid()) {
 			// Nothing to read
-			return;
+			throw new BadMethodCallException('next() invoked but no valid current block (EOF?)');
 		}
 
 		// First calculate minimum block length
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: key()=%d', $this->key()));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: this->seekPosition=%d', $this->determineSeekPosition()));
 		$length = $this->getBlockInstance()->calculateMinimumBlockLength();
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: length=%d', $length));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: length=%d', $length));
 
 		// Read possibly back-buffered bytes from previous call of next().
 		$data = $this->getBackBuffer();
@@ -898,40 +913,29 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		 * "block" may not fit, so this loop will continue until the EOB or EOF
 		 * has been reached whatever comes first.
 		 */
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: data()=%d', strlen($data)));
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: data()=%d', strlen($data)));
 		while ((!$this->isEndOfFileReached()) && (empty($data) || !self::isBlockSeparatorFound($data))) {
 			// Then read the next possible block
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->read(%d) ...', $length));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->read(%d) ...', $length));
 			$block = $this->read($length);
 
 			// Is it all empty?
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: block()=%d,length=%s', strlen($block), $length));
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: block()=%d,length=%d', strlen($block), $length));
 			if (strlen(trim($block, chr(0))) == 0) {
 				// Mark this block as empty
-				/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling markCurrentBlockAsEmpty(%d) ...', strlen($block)));
+				//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling this->markCurrentBlockAsEmpty(%d) ...', strlen($block)));
 				$this->markCurrentBlockAsEmpty(strlen($block));
 
-				// Skip to next block
-				/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CONTINUE!');
-				continue;
+				// Exit look
+				//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Empty block found ... - BREAK!');
+				break;
 			}
 
 			// At this block then
 			$data .= $block;
 
 			// A debug message
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: data()=%d', strlen($data)));
-		}
-
-		// EOF reached?
-		if ($this->isEndOfFileReached()) {
-			// Set whole data as current read block
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: Calling setCurrentBlock(%d) ...', strlen($data)));
-			$this->setCurrentBlock($data);
-
-			// Then abort here silently
-			/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EOF reached - EXIT!');
-			return;
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: data(%d)=%s', strlen($data), $data));
 		}
 
 		/*
@@ -940,23 +944,30 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		 */
 		$this->initBackBuffer();
 
+		// Is $data empty?
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: data(%d)=%s', strlen($data), $data));
+		if (empty($data)) {
+			// Yes, maybe whole file was ...
+			//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: Maybe empty file found - EXIT!');
+			return;
+		}
+
 		// Separate data
 		$dataArray = explode(chr(self::SEPARATOR_ENTRIES), $data);
 
-		// This array must contain two elements
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: dataArray()=%d', count($dataArray)));
+		// Left part is the actual block, right one the back-buffer data, if found
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: dataArray()=%d', count($dataArray)));
 		//* PRINTR-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: dataArray=%s', print_r($dataArray, true)));
-		if (count($dataArray) != 2) {
-			// Bad count
-			throw new UnexpectedValueException(sprintf('dataArray()=%d is not expected, want 2', count($dataArray)));
-		}
-
-		// Left part is the actual block, right one the back-buffer data
 		$this->setCurrentBlock($dataArray[0]);
-		$this->setBackBuffer($dataArray[1]);
+
+		// Is back buffere data found?
+		if (isset($dataArray[1])) {
+			// Set back buffer
+			$this->setBackBuffer($dataArray[1]);
+		}
 
 		// Trace message
-		/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
+		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: EXIT!');
 	}
 
 	/**
@@ -966,7 +977,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 	 * @return	$isValid	Whether the next entry is valid
 	 * @throws	UnexpectedValueException	If some value is not expected
 	 */
-	public function valid () {
+	public function isValid () {
 		// First calculate minimum block length
 		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
 		$length = $this->getBlockInstance()->calculateMinimumBlockLength();
@@ -979,7 +990,7 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		}
 
 		// Get current seek position
-		$seekPosition = $this->key();
+		$seekPosition = $this->determineSeekPosition();
 
 		// Then try to read it
 		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: seekPosition=%d', $seekPosition));
@@ -1008,21 +1019,6 @@ abstract class BaseBinaryFile extends BaseAbstractFile {
 		return $isValid;
 	}
 
-	/**
-	 * Gets current seek position ("key").
-	 *
-	 * @return	$key	Current key in iteration
-	 */
-	public function key () {
-		// Call pointer instance
-		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-BINARY-FILE: CALLED!');
-		$key = $this->getPointerInstance()->determineSeekPosition();
-
-		// Return key
-		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-BINARY-FILE: key[%s]=%d - EXIT!', gettype($key), $key));
-		return $key;
-	}
-
 	/**
 	 * Reads the file header
 	 *
-- 
2.39.5