+Show TOC
×Hide TOC

ArrayIterator

Kind of class:	public class
Package:	com.bourre.collection
Inherits from:	none
Implements:	ListIterator
Author:	Cedric Nehemie
Classpath:	com.bourre.collection.ArrayIterator
File last modified:	Monday, 24 November 2008, 11:36:49

► View source

▼ Hide source

/*
 * Copyright the original author or authors.
 * 
 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.mozilla.org/MPL/MPL-1.1.html
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.bourre.collection 
{
    import com.bourre.log.PixlibDebug;    
    import com.bourre.error.IllegalStateException;
    import com.bourre.error.IndexOutOfBoundsException;
    import com.bourre.error.NoSuchElementException;
    import com.bourre.error.NullPointerException;        

    /**
     * The <code>ArrayIterator</code> class provides a convenient way
     * to iterate through each entry of an <code>Array</code> instance 
     * as you could do with a <code>List</code> instance.
     * <p>
     * Iterations are performed from <code>0</code> to <code>length</code> 
     * of the passed-in array.
     * </p> 
     * @author     Cedric Nehemie
     * @see        ListIterator
     */
    public class ArrayIterator 
        implements ListIterator 
    {
        protected var _aArray     : Array;
        protected var _nSize     : Number;
        protected var _nIndex     : Number;
        protected var _bRemoved : Boolean;
        protected var _bAdded     : Boolean;

        /**
         * Creates a new iterator for the passed-in array.
         * 
         * @param    a    <code>Array</code> iterator's target
         * @param    i    iterator's start index
         * @throws     <code>NullPointerException</code> ‚Äî if the array's target is null
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî if the index is out of range
         */
        public function ArrayIterator ( a : Array, i : uint = 0 )
        {
            if ( a == null )
            {
                var msg0 : String = "Array target of " + this + "can't be null.";
                PixlibDebug.ERROR ( msg0 );
                throw new NullPointerException ( msg0 );
            }

            if ( i > a.length )
            {
                var msg1 : String = "'" + i + "' is not a valid index for an array with '" + a.length + "' length.";
                PixlibDebug.ERROR ( msg1 );
                throw new IndexOutOfBoundsException ( msg1 );
            }
        
            _aArray     = a;
            _nSize         = a.length;
            _nIndex     = i - 1;
            _bRemoved     = false;
            _bAdded     = false;
        }

        /**
         * @inheritDoc
         */
        public function hasNext () : Boolean
        {
            return ( _nIndex + 1 < _nSize );
        }
        
        /**
         * @inheritDoc
         */
        public function next () : *
        {
            if( !hasNext() )
            {
                var msg : String = this + " has no more element at '" + ( _nIndex + 1 ) +"' index.";
                PixlibDebug.ERROR ( msg );
                throw new NoSuchElementException ( msg );
            }
            
            _bRemoved     = false;
            _bAdded     = false;
            return _aArray[ ++_nIndex ];
        }
        
        /**
         * @inheritDoc
         */
        public function remove () : void
        {
            if( _bRemoved )
            {
                _aArray.splice( _nIndex--, 1 );
                _nSize--;
                _bRemoved = true;

            } else
            {
                var msg : String = this + ".remove() has been already called in this iteration.";
                PixlibDebug.ERROR ( msg );
                throw new IllegalStateException ( msg );
            }
        }

        /**
         * @inheritDoc
         */
        public function add ( o : Object ) : void
        {
            if( !_bAdded )
            {
                _aArray.splice ( _nIndex + 1, 0, o );
                _nSize++;
                _bAdded = true;

            } else
            {
                var msg : String = this + ".add() has been already called in this iteration.";
                PixlibDebug.ERROR ( msg );
                throw new IllegalStateException ( msg );
            }
        }

        /**
         * @inheritDoc
         */
        public function hasPrevious () : Boolean
        {
            return _nIndex >= 0;
        }

        /**
         * @inheritDoc
         */
        public function nextIndex () : uint
        {
            return _nIndex + 1;
        }

        /**
         * @inheritDoc
         */
        public function previous () : *
        {
            if( !hasPrevious() )
            {
                var msg : String = this + " has no more element at '" + ( _nIndex ) + "' index.";
                PixlibDebug.ERROR ( msg );
                throw new NoSuchElementException ( msg );
            }
            
            _bRemoved     = false;
            _bAdded     = false;
            
            return _aArray[ _nIndex-- ];
        }

        /**
         * @inheritDoc
         */
        public function previousIndex () : uint
        {
            return _nIndex;
        }

        /**
         * @inheritDoc
         */
        public function set ( o : Object ) : void
        {
            if( !_bRemoved && !_bAdded )
            {
                _aArray[ _nIndex ] = o;

            } else
            {
                var msg : String =     this + ".add() or " + this + ".remove() have been " +
                                    "already called in this iteration, the set() operation cannot be done";
                PixlibDebug.ERROR ( msg );
                throw new IllegalStateException ( msg );
            }
        }
    }
}

The ArrayIterator class provides a convenient way
to iterate through each entry of an Array instance
as you could do with a List instance.

Iterations are performed from 0 to length
of the passed-in array.

Summary

Constructor

ArrayIterator (a:Array, i:uint = 0)
- Creates a new iterator for the passed-in array.

Instance methods

hasNext : Boolean
next : *
remove : void
add (o:Object) : void
hasPrevious : Boolean
nextIndex : uint
previous : *
previousIndex : uint
set (o:Object) : void

Constructor

ArrayIterator

public function ArrayIterator (

a:Array, i:uint = 0)

Creates a new iterator for the passed-in array.

Parameters:

Array iterator's target

iterator's start index

Throws:

{VISDOC_LINK_0}NullPointerException — if the array's target is null
{VISDOC_LINK_1}IndexOutOfBoundsException — if the index is out of range

Instance methods

add

public function add (

o:Object) : void

Parameters:

the element to insert.

Throws:

{VISDOC_LINK_0}{VISDOC_CODE_BLOCK_10} — if the set operation
is not supported by this list iterator.
#
{VISDOC_LINK_1}{VISDOC_CODE_BLOCK_11} — if the class of the specified
element prevents it from being added to this list.
#
{VISDOC_LINK_2}{VISDOC_CODE_BLOCK_12} — if some aspect of the
specified element prevents it from being added to this list.
#
{VISDOC_LINK_3}{VISDOC_CODE_BLOCK_13} — if neither next nor previous have
been called, or remove or add have been called after
the last call to next or previous.
#

Specified by:

ListIterator.add

hasNext

public function hasNext (

) : Boolean

Returns:

ArrayIterator if the iterator has more elements.
#

Specified by:

Iterator.hasNext

hasPrevious

public function hasPrevious (

) : Boolean

Returns:

{VISDOC_CODE_BLOCK_15} if the list iterator has more elements when
traversing the list in the reverse direction.
#

Specified by:

ListIterator.hasPrevious

public function next (

) : *

Returns:

the next element in the iteration.
#

Throws:

{VISDOC_LINK_0}Array — iteration has no more elements.
#

Specified by:

Iterator.next

nextIndex

public function nextIndex (

) : uint

Returns:

the index of the element that would be returned
by a subsequent call to next, or list size if list
iterator is at end of list.
#

Specified by:

ListIterator.nextIndex

public function previous (

) : *

Returns:

the previous element in the list.
#

Throws:

{VISDOC_LINK_0}{VISDOC_CODE_BLOCK_16} — if the iteration has no previous element.
#

Specified by:

ListIterator.previous

previousIndex

public function previousIndex (

) : uint

Returns:

the index of the element that would be returned
by a subsequent call to previous, or {VISDOC_CODE_BLOCK_18} if list iterator is at beginning of list.
#

Specified by:

ListIterator.previousIndex

remove

public function remove (

) : void

Throws:

{VISDOC_LINK_0}List — if the remove operation is not
supported by this Iterator.
#
{VISDOC_LINK_1}0 — if the next method has not yet been called,
or the remove method has already been called after the last
call to the next method.
#

Specified by:

Iterator.remove

set

public function set (

o:Object) : void

Parameters:

the element with which to replace the last
element returned by next or previous.

Throws:

{VISDOC_LINK_0}{VISDOC_CODE_BLOCK_21} — if the set operation
is not supported by this list iterator.
#
{VISDOC_LINK_1}{VISDOC_CODE_BLOCK_22} — if the class of the specified
element prevents it from being added to this list.
#
{VISDOC_LINK_2}{VISDOC_CODE_BLOCK_23} — if some aspect of the
specified element prevents it from being added to this list.
#
{VISDOC_LINK_3}{VISDOC_CODE_BLOCK_24} — if neither next nor previous have
been called, or remove or add have been called after
the last call to next or previous.
#

Specified by:

ListIterator.set