<?php

/** @file appenditerator.inc
 * @ingroup SPL
 * @brief class AppendIterator
 * @author  Marcus Boerger
 * @date    2003 - 2009
 *
 * SPL - Standard PHP Library
 */

/** @ingroup SPL
 * @brief   Iterator that iterates over several iterators one after the other
 * @author  Marcus Boerger
 * @version 1.0
 * @since PHP 5.1
 */
class AppendIterator implements OuterIterator
{
	/** @internal array of inner iterators */
	private $iterators;

	/** Construct an empty AppendIterator
	 */
	function __construct()
	{
		$this->iterators = new ArrayIterator();
	}

	/** Append an Iterator
	 * @param $it Iterator to append
	 *
	 * If the current state is invalid but the appended iterator is valid
	 * the AppendIterator itself becomes valid. However there will be no
	 * call to $it->rewind(). Also if the current state is invalid the inner
	 * ArrayIterator will be rewound und forwarded to the appended element.
	 */	
	function append(Iterator $it)
	{
		$this->iterators->append($it);
	}

	/** @return the current inner Iterator
	 */
	function getInnerIterator()
	{
		return $this->iterators->current();
	}

	/** Rewind to the first element of the first inner Iterator.
	 * @return void
	 */
	function rewind()
	{
		$this->iterators->rewind();
		if ($this->iterators->valid())
		{
			$this->getInnerIterator()->rewind();
		}
	}

	/** @return whether the current element is valid
	  */
	function valid()
	{
		return $this->iterators->valid() && $this->getInnerIterator()->valid();
	}

	/** @return the current value if it is valid or \c NULL
	 */
	function current()
	{
		/* Using $this->valid() would be exactly the same; it would omit
		 * the access to a non valid element in the inner iterator. Since
		 * the user didn't respect the valid() return value false this
		 * must be intended hence we go on. */
		return $this->iterators->valid() ? $this->getInnerIterator()->current() : NULL;
	}

	/** @return the current key if it is valid or \c NULL
	 */
	function key()
	{
		return $this->iterators->valid() ? $this->getInnerIterator()->key() : NULL;
	}

	/** Move to the next element. If this means to another Iterator that 
	 * rewind that Iterator.
	 * @return void
	 */
	function next()
	{
		if (!$this->iterators->valid())
		{
			return; /* done all */
		}
		$this->getInnerIterator()->next();
		if ($this->getInnerIterator()->valid())
		{
			return; /* found valid element in current inner iterator */
		}
		$this->iterators->next();
		while ($this->iterators->valid())
		{
			$this->getInnerIterator()->rewind();
			if ($this->getInnerIterator()->valid())
			{
				return; /* found element as first elemet in another iterator */
			}
			$this->iterators->next();
		}
	}

	/** Aggregates the inner iterator
	 */	
	function __call($func, $params)
	{
		return call_user_func_array(array($this->getInnerIterator(), $func), $params);
	}
}

?>