<?php
/**
 * A general list class
 *
 * @author		Roland Haeder <webmaster@ship-simu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 Hub 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 BaseList extends BaseHubSystem implements IteratorAggregate {
	// Exception constants
	const EXCEPTION_GROUP_ALREADY_ADDED = 0xf20;
	const EXCEPTION_GROUP_NOT_FOUND     = 0xf21;

	/**
	 * List groups array
	 */
	private $listGroups = array();

	/**
	 * List entries array
	 */
	private $listEntries = array();

	/**
	 * List index array
	 */
	private $listIndex = array();

	/**
	 * Protected constructor
	 *
	 * @param	$className	Name of the class
	 * @return	void
	 */
	protected function __construct ($className) {
		// Call parent constructor
		parent::__construct($className);

		// Remove some attributes
		$this->removeNumberFormaters();
		$this->removeSystemArray();
	}

	/**
	 * Getter for iterator instance from this list
	 *
	 * @return	$iteratorInstance	An instance of a Iterator class
	 */
	public function getIterator () {
		// Prepare a default iterator
		$iteratorInstance = ObjectFactory::createObjectByConfiguredName('default_iterator_class');

		// And return it
		return $iteratorInstance;
	}

	/**
	 * Checks wether the given group is set
	 *
	 * @param	$groupName	Group to check if found in list
	 * @return	$isset		Wether the group is valid
	 */
	public function isGroupSet ($groupName) {
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName);
		return isset($this->listGroups[$groupName]);
	}

	/**
	 * Adds the given group or if already added issues a ListGroupAlreadyAddedException
	 *
	 * @param	$groupName	Group to add
	 * @return	void
	 * @throws	ListGroupAlreadyAddedException	If the given group is already added
	 */
	public function addGroup ($groupName) {
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - START');
		// Is the group already added?
		if ($this->isGroupSet($groupName)) {
			// Throw the exception here
			throw new ListGroupAlreadyAddedException(array($this, $groupName), self::EXCEPTION_GROUP_ALREADY_ADDED);
		} // END - if

		// Add the group which is a simple array
		$this->listGroups[$groupName] = ObjectFactory::createObjectByConfiguredName('list_group_class');
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - FINISHED');
	}

	/**
	 * Adds the given instance to list group and sub group
	 *
	 * @param	$groupName	Group to add instance to
	 * @param	$subGroup	Sub group to add instance to
	 * @param	$instance	An instance of Visitable
	 * @return	void
	 * @throws	NoListGroupException	If the given group is not found
	 */
	public function addInstance ($groupName, $subGroup, Visitable $instance) {
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName  . '/' . $subGroup . ' - START');
		// Is the group there?
		if (!$this->isGroupSet($groupName)) {
			// Throw the exception here
			throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
		} // END - if

		// Is the sub group there?
		if (!$this->listGroups[$groupName]->isGroupSet($subGroup)) {
			// Automatically add it
			$this->listGroups[$groupName]->addGroup($subGroup);
		} // END - if

		// Generate the hash
		$hash = $this->generateHash($groupName, $subGroup, $instance);

		// Now add it to the group list and hash it
		$this->listGroups[$groupName]->addEntry($subGroup, $hash);

		// Add the hash to the index
		$this->listIndex[] = $hash;

		// Add the instance itself to the list
		$this->listEntries[$hash] = $instance;
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName  . '/' . $subGroup . ' - START');
	}

	/**
	 * Adds the given entry to list group
	 *
	 * @param	$groupName	Group to add instance to
	 * @param	$entry		An entry of any type
	 * @return	void
	 * @throws	NoListGroupException	If the given group is not found
	 */
	public function addEntry ($groupName, $entry) {
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - START');
		// Is the group already added?
		if (!$this->isGroupSet($groupName)) {
			// Throw the exception here
			throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
		} // END - if

		// Generate hash
		$hash = $this->generateHash($groupName, $groupName, $entry);

		// Add the hash to the index
		$this->listIndex[] = $hash;

		// Now add the entry to the list
		$this->listEntries[$hash] = $entry;
		//* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - FINISHED');
	}

	/**
	 * Generates a hash from given group, sub group and entry
	 *
	 * @param	$groupName	Group to add instance to
	 * @param	$subGroup	Sub group to add instance to
	 * @param	$entry		An entry of any type
	 * @return	$hash		The generated
	 */
	private function generateHash ($groupName, $subGroup, $entry) {
		// Created entry, 'null' is default
		$entry2 = 'null';

		// Determine type of entry
		if (is_null($entry)) {
			// Ignore this
		} elseif ($entry instanceof FrameworkInterface) {
			// Own instance detected
			$entry2 = $entry->hashCode();
		} elseif (!is_array($entry)) {
			// Non-array found, use it directly with type
			$entry2 = gettype($entry) . ':' . $entry2;
		} else {
			// Arrays are unsupported at the momement
			$this->debugOutut(__METHOD__ . ': entry is an array. UNSUPPORTED!');

			// @TODO Extend this somehow?
			$entry2 = gettype($entry);
		}

		// Construct string which we shall hash
		$hashString = $groupName . ':' . $subGroup . ':' . $entry2;

		// Hash it with fastest hasher
		$hash = crc32($hashString);

		// And return it
		return $hash;
	}
}

//
?>