Class ProtoArray

<?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
     */
    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 = [])
        {
            self::$__tSerializableProperties = self::$__serializable;

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

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

        /**
         * 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;
        }

        // iSerializable

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

        // 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);
        }

        // ArrayAccess

        public function offsetSet($offset, $value)
        {
            $this->__array[$offset] = $value;
            return $this->updateEvent();
        }

        public function offsetExists($offset)
        {
            return array_key_exists($offset, $this->__array);
        }

        public function offsetUnset($offset)
        {
            if(FALSE === $this->offsetExists($offset))
                return $this;

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

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

        // IndexAccess

        /**
         * index-based alias for offsetExists
         */
        public function indexExists($index)
        {
            return array_key_exists($index, $this->__offsets);
        }

        /**
         * index-based alias for offsetSet
         */
        public function indexSet($index, $value)
        {
            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(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(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(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(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)
        {
            return (FALSE === $this->offsetExists($offset))
                ? $this->lastValue()
                : $this->offsetGet($offset);
        }

        /**
         * returns the value by index or by top-index
         */
        public function peekValueByIndex($index)
        {
            return (FALSE === $this->indexExists($index))
                ? $this->lastValue()
                : $this->indexGet($index);
        }

        /**
         * returns the index by offset or by top-offset
         */
        public function peekIndexByOffset($offset)
        {
            return (FALSE === $this->offsetExists($offset))
                ? $this->lastIndex()
                : $this->offsetToIndex($offset);
        }

        /**
         * returns the offset by index or by top-index
         */
        public function peekOffsetByIndex($index)
        {
            return (FALSE === $this->indexExists($index))
                ? $this->lastOffset()
                : $this->indexToOffset($index);
        }

        // generic array functions

        public function push($value)
        {
        }

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