<?php
// Own namespace
namespace Org\Mxchange\CoreFramework\Iterator\File;

// Import framework stuff
use Org\Mxchange\CoreFramework\Filesystem\File\BinaryFile;
use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
use Org\Mxchange\CoreFramework\Iterator\BaseIterator;
use Org\Mxchange\CoreFramework\Traits\File\BinaryFileTrait;

// Import SPL stuff
use \BadMethodCallException;
use \InvalidArgumentException;
use \OutOfBoundsException;
use \SeekableIterator;

/**
 * A file iterator
 *
 * @author		Roland Haeder <webmaster@ship-simu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
 * @license		GNU GPL 3.0 or any newer version
 * @link		http://www.ship-simu.org
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
class FileIterator extends BaseIterator implements SeekableIterator {
	// Load traits
	use BinaryFileTrait;

	/**
	 * Protected constructor
	 *
	 * @return	void
	 */
	private function __construct () {
		// Call parent constructor
		parent::__construct(__CLASS__);
	}

	/**
	 * Creates an instance of this class
	 *
	 * @param	$binaryFileInstance	An instance of a BinaryFile class
	 * @return	$iteratorInstance	An instance of a Iterator class
	 */
	public final static function createFileIterator (BinaryFile $binaryFileInstance) {
		// Get new instance
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: binaryFileInstance=%s - CALLED!', $binaryFileInstance->__toString()));
		$iteratorInstance = new FileIterator();

		// Set the instance here
		$iteratorInstance->setBinaryFileInstance($binaryFileInstance);

		// Return the prepared instance
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
		return $iteratorInstance;
	}

	/**
	 * Gets currently read data
	 *
	 * @return	$current	Currently read data
	 * @throws	BadMethodCallException	If valid() is FALSE
	 */
	public function current () {
		// Is condition given?
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
		if (!$this->valid()) {
			// Throw BMCE
			throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
		}

		// Call file instance
		$current = $this->getBinaryFileInstance()->current();

		// Return it
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: current[]=%s - EXIT!', gettype($current)));
		return $current;
	}

	/**
	 * Gets current seek position ("key").
	 *
	 * @return	$key	Current key in iteration
	 * @throws	BadMethodCallException	If valid() is FALSE
	 */
	public function key () {
		// Is condition given?
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
		if (!$this->valid()) {
			// Throw BMCE
			throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
		}

		// Get key from file instance
		$key = $this->getBinaryFileInstance()->determineSeekPosition();

		// Return key
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: key[%s]=%s - EXIT!', gettype($key), $key));
		return $key;
	}

	/**
	 * Advances to next "file" of bytes
	 *
	 * @return	void
	 */
	public function next () {
		// Call file instance
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
		$this->getBinaryFileInstance()->next();

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
	}

	/**
	 * Rewinds to the beginning of the file
	 *
	 * @return	$status		Status of this operation
	 */
	public function rewind () {
		// Call file instance
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
		$this->getBinaryFileInstance()->rewind();

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
	}

	/**
	 * Checks wether the current entry is valid (not at the end of the file).
	 * This method will return true if an emptied (nulled) entry has been found.
	 *
	 * @return	$isValid	Whether the next entry is valid
	 */
	public function valid () {
		// Call file instance
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
		$isValid = $this->getBinaryFileInstance()->valid();

		// Return flag
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isValid=%d - EXIT!', intval($isValid)));
		return $isValid;
	}

	/**
	 * Seeks to given position
	 *
	 * @param	$seekPosition	Seek position in file
	 * @return	void
	 * @throws	OutOfBoundsException	If the position is not seekable
	 */
	public function seek (int $seekPosition) {
		// Validate parameter
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence));
		if ($seekPosition < 0) {
			// Throw IAE
			throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
		}

		// Call file instance
		$this->getBinaryFileInstance()->seek($seekPosition);

		// Trace message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
	}

}