Class ArraySegment

<?PHP
    /**
     * ILLI
     *
     * @category   ILLI_System
     * @package    ILLI
     * @subpackage System
     * @link       http://illi.be
     * @license    http://l.illi.be
     * @copyright  ILLI Conference
     */
    NAMESPACE ILLI\System;

    /**
     * ILLI System Abstract Prototype ArraySegment
     *
     * Delimits a section of a one-dimensional array.
     *
     * ProtoArraySegment is a wrapper around a ProtoArray that delimits a range of
     * elements in that array. Multiple ProtoArraySegment instances refer to the
     * same original ProtoArray and can overlap.
     *
     * The getReference method returns the entire original ProtoArray Instance,
     * not a copy of the ProtoArray.
     *
     * <code>
     * <?PHP
     * function writeArray(tArray $arrSeg)
     * {
     *  print "===\n";
     *  print "tArray\n";
     *  foreach($arrSeg as $k => $v)
     *      var_dump($k.': '.$v);
     * }
     * function writeSeg(tArraySegment $arrSeg)
     * {
     *  print "===\n";
     *  printf('tArraySegment [start-index: %d|length: %d|last-index: %d]'."\n",
     *      $arrSeg->getStart(),
     *      $arrSeg->getLength(),
     *      $arrSeg->getLast());
     *
     *  foreach($arrSeg as $k => $v)
     *      var_dump($k.': '.$v);
     * }
     *
     * $a = new tArray(["The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog"]);
     *
     * $b = new tArraySegment($a, 6, 5);
     * $c = new tArraySegment($a, NULL, 5);
     * $d = new tArraySegment($a, 2, 5);
     * $e = new tArraySegment($a, 2, NULL);
     *
     * print "Defaults\n";
     * writeArray($a);  //"The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog"
     * writeSeg($b);    //"the", "lazy", "dog"
     * writeSeg($c);    //"The", "quick", "brown", "fox", "jumps"
     * writeSeg($d);    //"brown", "fox", "jumps", "over", "the"
     * writeSeg($e);    //"brown", "fox", "jumps", "over", "the", "lazy", "dog"
     *
     * print "\n\nChanging a value in the tArray\n";
     * $a[6] = 'TREES';
     *
     * writeArray($a);  //"The", "quick", "brown", "fox", "jumps", "over", "TREES", "lazy", "dog"
     * writeSeg($b);    //"TREES", "lazy", "dog"
     * writeSeg($c);    //"The", "quick", "brown", "fox", "jumps"
     * writeSeg($d);    //"brown", "fox", "jumps", "over", "TREES"
     * writeSeg($e);    //"brown", "fox", "jumps", "over", "TREES", "lazy", "dog"
     *
     * print "\n\nChanging a value in a tArraySegment\n";
     * $b[3] = 'LION';
     *
     * writeArray($a);  //"The", "quick", "brown", "LION", "jumps", "over", "TREES", "lazy", "dog"
     * writeSeg($b);    //"TREES", "lazy", "dog"
     * writeSeg($c);    //"The", "quick", "brown", "LION", "jumps"
     * writeSeg($d);    //"brown", "LION", "jumps", "over", "TREES"
     * writeSeg($e);    //"brown", "LION", "jumps", "over", "TREES", "lazy", "dog"
     * ?>
     * </code>
     *
     * The ArrayAccess for the instance of ProtoArraySegment is limited by the
     * initial-values index-start and length.
     *
     * <code>
     * <?PHP
     * $a = new tArray(["The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog"]);
     * $b = new tArraySegment($a, 1, 3);
     *
     * print "Defaults\n";
     * writeArray($a);  //"The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog"
     * writeSeg($b);    //"quick", "brown", "fox"
     *
     * $b[6] = 'BANANAS'; // throws ILLI\System\ArgumentOutOfRangeException
     * ?>
     * </code>
     *
     * @category   ILLI_System
     * @package    ILLI
     * @subpackage System
     * @namespace  ILLI\System
     * @link       http://illi.be
     * @license    http://l.illi.be
     * @copyright  ILLI Conference
     * @since      2.0.0-1
     * @version    2.0.0-1
     * @abstract
     */
    ABSTRACT CLASS ProtoArraySegment EXTENDS Proto IMPLEMENTS iArrayAccess
    {
        private $__REFERENCE    = NULL;

        private $__length   = NULL;
        private $__start    = NULL;
        private $__first    = NULL;
        private $__last     = NULL;

        public function __construct(ProtoArray &$array, $start = NULL, $length = NULL)
        {
            if(NULL === $array)
                throw new ArgumentNullException;

            if(NULL !== $start)
            {
                if(!is_integer($start))
                    throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

                if($start < 0)
                    throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER_NOT_POSITIVE_OR_ZERO,
                        ['value' => $start]);
            }

            if(NULL !== $length)
            {
                if(!is_integer($length))
                    throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

                if($length < 0)
                    throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER_NOT_POSITIVE_OR_ZERO,
                        ['value' => $length]);
            }

            $this->__REFERENCE  =& $array;
            $this->__start      = $start;
            $this->__length     = $length;
            $this->__first      = $start === NULL
                            ? $array->bottom()
                            : $start;
            $this->__last       = $length === NULL
                            ? $array->peek()
                            : $array->peek($start + $length - 1);
        }

        protected function getReference()
        {
            return $this->__REFERENCE;
        }

        public function offsetAccessible($offset)
        {
            return $offset >= $this->getFirst() && $offset <= $this->getLast();
        }

        public function getStart()
        {
            return $this->__start;
        }

        public function getLength()
        {
            return $this->__length;
        }

        public function getFirst()
        {
            return $this->__first;
        }

        public function getLast()
        {
            return $this->__last;
        }

        public function offsetSet($offset, $value)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

            if(!is_scalar($offset))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_SCALAR);

            if(FALSE === $this->offsetAccessible($offset))
                throw new ArgumentOutOfRangeException(E::ARGUMENT_OUT_OF_ARRAY_INDEX,
                    ['key' => $offset]);

            $this->__REFERENCE->offsetSet($offset, $value);
            return $this;
        }

        public function offsetExists($offset)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

            if(!is_scalar($offset))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_SCALAR);

            return $this->__REFERENCE->offsetExists($offset) && $this->offsetAccessible($offset);
        }

        public function offsetUnset($offset)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

            if(!is_scalar($offset))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_SCALAR);

            if(FALSE === $this->offsetAccessible($offset))
                throw new ArgumentOutOfRangeException(E::ARGUMENT_OUT_OF_ARRAY_INDEX,
                    ['key' => $offset]);

            $this->__REFERENCE->offsetUnset($offset);

            return $this;
        }

        public function offsetGet($offset)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

            if(!is_scalar($offset))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_SCALAR);

            if(FALSE === $this->offsetAccessible($offset))
                throw new ArgumentOutOfRangeException(E::ARGUMENT_OUT_OF_ARRAY_INDEX,
                    ['key' => $offset]);

            return $this->__REFERENCE->offsetGet($offset);
        }
    }

<?PHP
    /**
     * ILLI
     *
     * @category   ILLI_System_Collection
     * @package    ILLI
     * @subpackage SystemCollection
     * @link       http://illi.be
     * @license    http://l.illi.be
     * @copyright  ILLI Conference
     */
    NAMESPACE ILLI\System\Collection;
    USE ILLI\System as System;

    /**
     * ILLI System Collection Datatype ArraySegment
     *
     * @category   ILLI_System_Collection
     * @package    ILLI
     * @subpackage SystemCollection
     * @namespace  ILLI\System\Collection
     * @link       http://illi.be
     * @license    http://l.illi.be
     * @copyright  ILLI Conference
     * @since      2.0.0-1
     * @version    2.0.0-1
     * @abstract
     */
    CLASS TArraySegment EXTENDS System\ProtoArraySegment IMPLEMENTS System\iIterator
    {
        const ITERATE_MODE_FIFO = 0x00000000;
        const ITERATE_MODE_LIFO = 0x00000001;

        private $__itMode   = 0;
        private $__index    = 0;

        public function __construct(TArray &$array, $start = NULL, $length = NULL)
        {
            if(NULL !== $start)
            {
                if(!is_integer($start))
                    throw new System\ArgumentException(System\E::ARGUMENT_EXPECTED_INTEGER);

                if($start < 0)
                    throw new System\ArgumentException(System\E::ARGUMENT_EXPECTED_INTEGER_NOT_POSITIVE_OR_ZERO,
                        ['value' => $start]);
            }

            $this->__index = $start;
            parent::__construct($array, $start, $length);
        }

        final public function getIteratorMode()
        {
            return $this->__itMode;
        }

        final public function rewind()
        {
            return $this->__index = $this->getFirst();
        }

        final public function current()
        {
            return $this->getReference()->offsetGet($this->__index);
        }

        final public function key()
        {
            return $this->__index;
        }

        final public function next()
        {
            return ++$this->__index;
        }

        final public function prev()
        {
        }

        final public function valid()
        {
            return $this->offsetExists($this->__index);
        }
    }