ArrayEnumerator

Kind of class:	class
Inherits from:	Enumerator < Dispatcher
Known subclasses:	TraverseArrayEnumerator
Author:	Arthur Clemens
Classpath:	org.asapframework.data.array.ArrayEnumerator
File last modified:	Thursday, 12 October 2006, 11:19:40

► View source

▼ Hide source

/*
Copyright 2005-2006 by the authors of asapframework, http://asapframework.org

Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0

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.
*/

import org.asapframework.data.Enumerator;

/**
Straightforward enumeration (iterator) class for arrays. ArrayEnumerator has one way of iterating: forward ({@link #getNextObject}). For more options see {@link TraverseArrayEnumerator}.
@author Arthur Clemens
*/

class org.asapframework.data.array.ArrayEnumerator extends Enumerator {

    private var mArray:Array; /**< Pointer to external array. */
    private var mLocation:Number;

    /**
    Creates a new array enumerator. Optionally stores a pointer to array inArray.
    @param inArray : (optional) the array to enumerate
    */
    public function ArrayEnumerator (inArray:Array) {
        super();
        if (inArray != undefined) {
            mArray = inArray;
            reset();
        }
    }
    
    /**
    Stores a pointer to array inArray.
    @param inArray : the array to enumerate
    */
    public function setArray (inArray:Array) : Void {
        mArray = inArray;
        reset();
    }
    
    /**
    Retrieves the object from the array at the current pointer location.
    @return (Deliberately untyped) The object from the array at the current pointer location.
    */
    public function getCurrentObject () {
        if (mLocation == -1) {
            return null;
        }
        return mArray[mLocation];
    }
    
    /**
    Increments the location pointer by one and returns the object from the array at that location.
    @return (Deliberately untyped) The object at the new location. Returns null if the location pointer has moved past the end of the array.
    @implementationNote Calls {@link #update}.
    */
    public function getNextObject () {
        if (mLocation < mArray.length) {
            return update(mLocation + 1);
        }
        return null;
    }
    
    /**
    Sets the location pointer to a new position.
    @param inLocation : the new pointer location
    @implementationNote Calls {@link #update}.
    */
    public function setCurrentLocation (inLocation:Number) : Void {
        update(inLocation);
    }
    
    /**
    Sets the location pointer to the location (in the array) of inObject.
    @param inObject : the object whose index the location pointer should point to
    @implementationNote Calls {@link #update}.
    */
    public function setCurrentObject (inObject:Object) : Void {
        var index:Number = findLocationForObject(inObject);
        if (index != -1) {
            update(index);
        }
    }
    
    /**
    Retrieves all objects.
    @return The array as set in the constructor or in {@link #setArray}.
    */
    public function getAllObjects () : Array {
        return mArray;
    }
    
    /**
    Puts the enumerator just before the first array item. At this point calling {@link #getCurrentObject} will generate an error; you must first move the enumerator using {@link #getNextObject}.
    @implementationNote Calls {@link #update}.    
    */
    public function reset () : Void {
        update(-1);
    }
            
    /**
    @exclude
    */
    public function toString () : String {
        return "ArrayEnumerator; array " + mArray;
    }
    
    // PRIVATE METHODS
    
    /**
    Updates the location pointer to a new index location.
    @param inLocation : the new index location
    @sends TraverseArrayEnumeratorEvent#UPDATE If the delegate validation method exists and only if the delegate method returns true.
    */
    private function update (inLocation:Number) {
        mLocation = inLocation;
        return getCurrentObject();
    }
    
    /**
    Retrieves the array index location of item inObject.
    @param inObject : the object to be found
    @return The array index location of item inObject. Returns -1 when the object is not found.
    */
    private function findLocationForObject (inObject:Object) : Number {
        var i:Number = mArray.length;
        while (i--) {
            if (mArray[i] == inObject) {
                return i;
            }
        }
        return -1;
    }
    
}

Straightforward enumeration (iterator) class for arrays. ArrayEnumerator has one way of iterating: forward (getNextObject). For more options see TraverseArrayEnumerator.

Events broadcasted to listeners:

TraverseArrayEnumeratorEvent with type: UPDATE If the delegate validation method exists and only if the delegate method returns true.
- (null)

Summary

Constructor

ArrayEnumerator (inArray:Array)
- Creates a new array enumerator.

Instance properties

mArray : Array
- Pointer to external array.
mLocation : Number

Instance properties inherited from Dispatcher

addEventListener dispatchEvent removeEventListener

Instance methods

setArray (inArray:Array) : Void
- Stores a pointer to array inArray.
getCurrentObject
getNextObject
setCurrentLocation (inLocation:Number) : Void
- Sets the location pointer to a new position.
setCurrentObject (inObject:Object) : Void
- Sets the location pointer to the location (in the array) of inObject.
getAllObjects : Array
- Retrieves all objects.
reset : Void
- Puts the enumerator just before the first array item.
update (inLocation:Number)
- Updates the location pointer to a new index location.
findLocationForObject (inObject:Object) : Number
- Retrieves the array index location of item inObject.

Instance methods inherited from Enumerator

getAllObjects getCurrentObject getNextObject reset

Constructor

ArrayEnumerator

function ArrayEnumerator (

inArray:Array)

Creates a new array enumerator. Optionally stores a pointer to array inArray.

Parameters:

inArray:

(optional) the array to enumerate

Instance properties

mArray

private mArray:Array

(read)

Pointer to external array.

mLocation

private mLocation:Number

(read)

Instance methods

findLocationForObject

private function findLocationForObject (

inObject:Object) : Number

Retrieves the array index location of item inObject.

Parameters:

inObject:

the object to be found

Returns:

The array index location of item inObject. Returns -1 when the object is not found.

getAllObjects

function getAllObjects (

) : Array

Retrieves all objects.

Returns:

The array as set in the constructor or in setArray.

Overrides:

org.asapframework.data.Enumerator.getAllObjects

getCurrentObject

function getCurrentObject (

)

Retrieves the object from the array at the current pointer location.

Returns:

(Deliberately untyped) The object from the array at the current pointer location.

getNextObject

function getNextObject (

)

Increments the location pointer by one and returns the object from the array at that location.

Returns:

(Deliberately untyped) The object at the new location. Returns null if the location pointer has moved past the end of the array.

Implementation note:

Calls update.

reset

function reset (

) : Void

Puts the enumerator just before the first array item. At this point calling getCurrentObject will generate an error; you must first move the enumerator using getNextObject.

Implementation note:

Calls update.

Overrides:

org.asapframework.data.Enumerator.reset

setArray

function setArray (

inArray:Array) : Void

Stores a pointer to array inArray.

Parameters:

inArray:

the array to enumerate

setCurrentLocation

function setCurrentLocation (

inLocation:Number) : Void

Sets the location pointer to a new position.

Parameters:

inLocation:

the new pointer location

Implementation note:

Calls update.

setCurrentObject

function setCurrentObject (

inObject:Object) : Void

Sets the location pointer to the location (in the array) of inObject.

Parameters:

inObject:

the object whose index the location pointer should point to

Implementation note:

Calls update.

update

private function update (

inLocation:Number)

Updates the location pointer to a new index location.

Parameters:

inLocation:

the new index location

Events broadcasted to listeners:

TraverseArrayEnumeratorEvent with type: UPDATE If the delegate validation method exists and only if the delegate method returns true.
- (null)