Class Array/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 Array
     *
     * Basic Array: index : offset : value
     *
     * @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
     * @todo    flags/it-modes
     */
    ABSTRACT CLASS ProtoArray EXTENDS Proto IMPLEMENTS iCountable, iArrayAccess, iSerializable, iIterator
    {
        /**
         * iterator modes
         * [fifo: 0] [lifo: 0x00000002] [filo: 0x00000004] [lilo: 0x00000006] [default: 0]
         * @var int
         */
        const IT_MODE_FI        = 0x00000000;

        /**
         * @see IT_MODE_FI
         * @var int
         */
        const IT_MODE_FO        = 0x00000000;

        /**
         * @see IT_MODE_FI
         * @var int
         */
        const IT_MODE_LI        = 0x00000002;

        /**
         * @see IT_MODE_FI
         * @var int
         */
        const IT_MODE_LO        = 0x00000004;

        /**
         * typedef values: if set, strict type for values
         * [mixed: 0] [safe: 0x00000032] [default: 0]
         * @var int
         */
        const VALUE_TYPE_UNSAFE     = 0x00000000;

        /**
         * @see VALUE_TYPE_UNSAFE
         * @var int
         */
        const VALUE_TYPE_SAFE       = 0x00000032;

        /**
         * typedef: zerobased or assoc array
         * [array: 0] [assoc: 0x00000256] [default: 0]
         * @var int
         */
        const ARRAY_MODE_ARRAY      = 0x00000000;

        /**
         * @see ARRAY_MODE_ASSOC
         * @var int
         */
        const ARRAY_MODE_ASSOC      = 0x00000256;

        /**
         * array_merge: order of priority
         * [new before existing: 0] [existing before new: 0x00001024] [default: 0]
         * @var int
         */
        const PERM_VALUE_AS_SUPER   = 0x00000000;

        /**
         * @see PERM_VALUE_AS_SUPER
         * @var int
         */
        const PERM_ARRAY_AS_SUPER   = 0x00001024;

        /**
         * serializable private properties
         * @var array
         * @static
         */
        private static $__serializable  =
                        [
                            '__array',
                            '__offsets',
                            '__indexes',
                            '__bitFlag'
                        ];

        /**
         * bitflag
         * @var int
         * @see IT_MODE_FI
         * @see IT_MODE_FO
         * @see VALUE_TYPE_UNSAFE
         * @see ARRAY_MODE_ARRAY
         * @see PERM_VALUE_AS_SUPER
         */
        private $__bitFlag      = 0x00000000;

        /**
         * data array
         * @var array
         */
        private $__array        = [];

        /**
         * offset cache: array keys from $__array
         * @var array
         */
        private $__offsets      = [];

        /**
         * index cache: flipped $__offsets
         * @var array
         */
        private $__indexes      = [];

        /**
         * iterator index
         * @var int32
         */
        private $__itIndex      = 0;

        /**
         * @param array|ProtoArray $array initial value
         */
        public function __construct($array = [])
        {
            if(NULL === $array)
                $array = [];

            if($array instanceOf ProtoArray
            || $array instanceOf ProtoArraySegment)
                $array = $array->toArray();

            if(FALSE === is_array($array))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_ARRAY);

            self::$__tSerializableProperties = self::$__serializable;

            $this->__array = $array;
            $this->updateEvent();
        }

        // iSerializable

        /**
         * @see tSerializable
         */
        USE tSerializable;

        /**
         * synchronize $__array with $__indexes and $__offsets
         *
         * its essential to update the both arrays whenever you edit $__array
         *
         * @see $__array
         * @see $__indexes
         * @see $__offsets
         */
        protected function updateEvent()
        {
            $this->__offsets = array_keys($this->__array);
            $this->__indexes = array_flip($this->__offsets);
            return $this;
        }

        // Countable

        public function count()
        {
            return sizeOf($this->__array);
        }

        // Iterator

        public function rewind()
        {
            $this->__itIndex = $this->firstIndex();
            return $this->__itIndex;
        }

        public function current()
        {
            return $this->indexGet($this->__itIndex);
        }

        public function key()
        {
            return $this->indexToOffset($this->__itIndex);
        }

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

        public function prev()
        {
            return --$this->__itIndex;
        }

        public function valid()
        {
            return $this->indexExists($this->__itIndex);
        }

        public function currentIndex()
        {
            return $this->__itIndex;
        }

        public function updateIndex($itIndex)
        {
            if(NULL === $itIndex)
                throw new ArgumentNullException;

            if(FALSE === is_integer($itIndex))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

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

            $this->__itIndex = $itIndex;
            return $this;
        }

        // ArrayAccess

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

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

            $this->__array[$offset] = $value;
            return $this->updateEvent();
        }

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

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

            return array_key_exists($offset, $this->__array);
        }

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

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

            if(FALSE === $this->offsetExists($offset))
                return $this;

            unset($this->__array[$offset]);
            return $this->updateEvent();
        }

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

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

            return (TRUE === $this->offsetExists($offset))
                ? $this->__array[$offset]
                : null;
        }

        // IndexAccess

        /**
         * index-based alias for offsetExists
         */
        public function indexExists($index)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

            return array_key_exists($index, $this->__offsets);
        }

        /**
         * index-based alias for offsetSet
         */
        public function indexSet($index, $value)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

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

            return $this->offsetSet($this->indexToOffset($index), $value);
        }

        /**
         * index-based alias for offsetUnset
         */
        public function indexUnset($index)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

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

            return $this->offsetUnset($this->indexToOffset($index));
        }

        /**
         * index-based alias for offsetGet
         */
        public function indexGet($index)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

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

            return $this->offsetGet($this->indexToOffset($index));
        }

        // Conversation

        /**
         * get the index by offset
         */
        public function offsetToIndex($offset)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

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

            return $this->__indexes[$offset];
        }

        /**
         * get the offset by index
         */
        public function indexToOffset($index)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

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

            return $this->__offsets[$index];
        }

        /**
         * bottom value
         */
        public function firstValue()
        {
            return $this->__array[$this->firstOffset()];
        }

        /**
         * top value
         */
        public function lastValue()
        {
            return $this->__array[$this->lastOffset()];
        }

        /**
         * bottom offset
         */
        public function firstOffset()
        {
            return $this->__offsets[$this->firstIndex()];
        }

        /**
         * top offset
         */
        public function lastOffset()
        {
            return $this->__offsets[$this->lastIndex()];
        }

        /**
         * bottom index
         */
        public function firstIndex()
        {
            return 0;
        }

        /**
         * top index
         */
        public function lastIndex()
        {
            return $this->count() - 1;
        }

        /**
         * returns the value by offset or by top-offset
         */
        public function peekValueByOffset($offset)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

            return (FALSE === $this->offsetExists($offset))
                ? $this->lastValue()
                : $this->offsetGet($offset);
        }

        /**
         * returns the value by index or by top-index
         */
        public function peekValueByIndex($index)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

            return (FALSE === $this->indexExists($index))
                ? $this->lastValue()
                : $this->indexGet($index);
        }

        /**
         * returns the index by offset or by top-offset
         */
        public function peekIndexByOffset($offset)
        {
            if(NULL === $offset)
                throw new ArgumentNullException;

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

            if($offset === "")
                throw new ArgumentException(E::ARGUMENT_EXPECTED_STRING_EMPTY);

            return (FALSE === $this->offsetExists($offset))
                ? $this->lastIndex()
                : $this->offsetToIndex($offset);
        }

        /**
         * returns the offset by index or by top-index
         */
        public function peekOffsetByIndex($index)
        {
            if(NULL === $index)
                throw new ArgumentNullException;

            if(FALSE === is_integer($index))
                throw new ArgumentException(E::ARGUMENT_EXPECTED_INTEGER);

            return (FALSE === $this->indexExists($index))
                ? $this->lastOffset()
                : $this->indexToOffset($index);
        }

        // generic array functions

        public function push($value)
        {
        }

        public function toArray()
        {
            return $this->__array;
        }
    }

    /**
     * ILLI System Abstract Prototype Array Segment
     *
     * Basic Array: reference to ProtoArray
     *
     * @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
     */
    CLASS ProtoArraySegment EXTENDS Proto IMPLEMENTS iCountable, iIterator
    {
        private $__reference    = NULL;
        private $__start    = 0;
        private $__length   = 0;
        private $__last     = 0;

        public function __construct(ProtoArray &$proto, $start = NULL, $length = NULL)
        {
            $this->__reference =& $proto;

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

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

            $this->__start = (NULL === $start)
                ? 0
                : $start;

            $this->__length = (NULL === $length)
                ? $this->count()
                : $length;

            $this->__last = $this->__start + $this->__length - 1;
        }

        // Iterator Wrapper for $__reference

        /**
         * @see ProtoArray::count()
         */
        public function count()
        {
            return $this->__length;
        }

        /**
         * @see ProtoArray::rewind()
         */
        public function rewind()
        {
            return $this->__reference->updateIndex($this->__start);
        }

        /**
         * @see ProtoArray::current()
         */
        public function current()
        {
            return $this->__reference->current();
        }

        /**
         * @see ProtoArray::key()
         */
        public function key()
        {
            return $this->__reference->key();
        }

        /**
         * @see ProtoArray::next()
         */
        public function next()
        {
            return $this->__reference->next();
        }

        /**
         * @see ProtoArray::prev()
         */
        public function prev()
        {
            return $this->__reference->prev();
        }

        /**
         * @see ProtoArray::valid()
         */
        public function valid()
        {
            return $this->__reference->valid() && $this->__reference->currentIndex() <= $this->__last;
        }

        /**
         * @return ProtoArray refernced Object
         */
        public function getReference()
        {
            return $this->__reference;
        }

        /**
         * @return array copy of segment
         */
        public function toArray()
        {
            $array  = [];
            foreach($this as $key => $value)
                $array[$key] = $value;

            return $array;
        }
    }