<?php

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

/**
 * @brief   Abstract filter for iterators
 * @author  Marcus Boerger
 * @version 1.1
 * @since PHP 5.0
 *
 * Instances of this class act as a filter around iterators. In other words 
 * you can put an iterator into the constructor and the instance will only 
 * return selected (accepted) elements.
 *
 * The only thing that needs to be done to make this work is implementing 
 * method accept(). Typically this invloves reading the current element or 
 * key of the inner Iterator and checking whether it is acceptable.
 */
abstract class FilterIterator implements OuterIterator
{
    private $it;

    /**
     * Constructs a filter around another iterator.
     *
     * @param it     Iterator to filter
     */
    function __construct(Iterator $it) {
        $this->it = $it;
    }

    /**
     * Rewind the inner iterator.
     */
    function rewind() {    
        $this->it->rewind();
        $this->fetch();
    }

    /**
     * Accept function to decide whether an element of the inner iterator
     * should be accessible through the Filteriterator.
     *
     * @return whether or not to expose the current element of the inner
     *         iterator.
     */
    abstract function accept();

    /**
     * Fetch next element and store it.
     *
     * @return void
     */
    protected function fetch() {
        while ($this->it->valid()) {
            if ($this->accept()) {
                return;
            }
            $this->it->next();
        };
    }

    /**
     * Move to next element
     *
     * @return void
     */
    function next() {
        $this->it->next();
        $this->fetch();
    }
    
    /**
     * @return Whether more elements are available
     */
    function valid() {
        return $this->it->valid();
    }
    
    /**
     * @return The current key
     */
    function key() {
        return $this->it->key();
    }
    
    /**
     * @return The current value
     */
    function current() {
        return $this->it->current();
    }
    
    /**
     * hidden __clone
     */
    protected function __clone() {
        // disallow clone 
    }

    /**
     * @return The inner iterator
     */    
    function getInnerIterator()
    {
        return $this->it;
    }

    /** Aggregate the inner iterator
     *
     * @param func    Name of method to invoke
     * @param params  Array of parameters to pass to method
     */
    function __call($func, $params)
    {
        return call_user_func_array(array($this->it, $func), $params);
    }
}

?>