org.apache.commons.math.util
Class FixedDoubleArray

java.lang.Object
  extended byorg.apache.commons.math.util.FixedDoubleArray
All Implemented Interfaces:
DoubleArray, Serializable

public class FixedDoubleArray
extends Object
implements DoubleArray, Serializable

Provides an implementation of the DoubleArray with a maximum number of elements. Creating an array implementation with an upper limit on the number of elements allows us to support a more efficient "rolling" mechanism to support addElementRoling(double). Please note that this implementation will not preserve the order of the values supplied to this array, calling getValues() will return an array of indeterminate order.

Values are added to this array by calling addElement(double) or addElementRolling(double). If addElement(double) is called on an array that already contains the maximum number of elements, an ArrayIndexOutOfBoundsException will be thrown to reflect an attempt to add a value beyond the boundaries of the fixed length array - in this respect a FixedDoubleArray can be considered "full". Calling addElementRolling(double) on an array which contains the maximum number of elements will cause the array to overwrite the "oldest" value in the array.

This class is called FixedDoubleArray not because it is of a fixed size. The name is appropriate because the internal storage array remains "fixed" in memory, this implementation will never allocate, or copy the internal storage array to a new array instance.

Version:
$Revision: 1.12 $ $Date: 2003/11/19 03:28:24 $
See Also:
Serialized Form

Constructor Summary
FixedDoubleArray(double[] array)
          Create a fixed array backed by the provided double[] implementation.
FixedDoubleArray(int maxElements)
          Create a fixed array for double primitives which can hold up to maxElements doubles.
 
Method Summary
 void addElement(double value)
          Add an element to the current array, testing to see if this array has already met or exceeded the maximum number of elements
 double addElementRolling(double value)
           Adds an element by "rolling" the new value into the current array while discarding the element which was added maxElement add operations ago.
 void clear()
          Clear the array - drop all the data and start with a blank internal array.
 double getElement(int index)
          Returns the element value at the specified index.
 double[] getElements()
          Provides an array of double[] which contain the number of elements added to this array.
 int getNumElements()
          Retrieves the current size of the array.
 double[] getValues()
          Returns the internal storage array
 void setElement(int index, double value)
           Sets the element at the specified index to the value supplied.
 int start()
          The starting index in the InternalArray.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FixedDoubleArray

public FixedDoubleArray(int maxElements)
Create a fixed array for double primitives which can hold up to maxElements doubles. This implementation of DoubleArray was created to provide a more "performance-oriented" in-place rolling mechanism for calculations which need to operate on a rolling window of values.

Parameters:
maxElements - the maximum number of elements this FixeddoubleArray may contain.

FixedDoubleArray

public FixedDoubleArray(double[] array)
Create a fixed array backed by the provided double[] implementation. the array should have all the elements occupied. the size and maxElements are drawn from the array's length. This implementation of DoubleArray was created to provide a more "performance-oriented" in-place rolling mechanism for calculations which need to operate on a rolling window of values.

Parameters:
array - the backing array
Method Detail

getNumElements

public int getNumElements()
Retrieves the current size of the array.

Specified by:
getNumElements in interface DoubleArray
Returns:
number of elements
See Also:
DoubleArray.getNumElements()

getElement

public double getElement(int index)
Returns the element value at the specified index. Please note that the size of the element array is not directly related to the maximum number of elements which this array can contain. One can create an instance of FixedDoubleArray with a maximum of ten elements, add three items, and get any items from index 0 to index 2 - trying to retrieve an element outside of the current element array will throw an ArrayIndexOutOfBoundsException.

Specified by:
getElement in interface DoubleArray
Parameters:
index - index to fetch a value from
Returns:
value stored at the specified index
See Also:
DoubleArray.getElement(int)

setElement

public void setElement(int index,
                       double value)

Sets the element at the specified index to the value supplied.

Implementation Notes:

    This implementation will not expand the array to the specified size. Unlike the expandable double array implementation calling setElement(10, 3.0) on an array with 5 elements will throw an ArrayIndexOutOfBoundsException.
    The number of elements in an array corresponds to the number of elements that have been added to this FixedDoubleArray. This is not the same as the maximum number of elements which can be contained in this array. A FixedDoubleArray instance can be created with a maximum upper limit of 10 elements, until 10 elements have been added to this array, the size of the array reflects the number of elements added.

Specified by:
setElement in interface DoubleArray
Parameters:
index - index to store a value in
value - value to store at the specified index
See Also:
DoubleArray.setElement(int, double)

addElement

public void addElement(double value)
Add an element to the current array, testing to see if this array has already met or exceeded the maximum number of elements

Specified by:
addElement in interface DoubleArray
Parameters:
value - to be added to end of array
See Also:
DoubleArray.addElement(double)

addElementRolling

public double addElementRolling(double value)

Adds an element by "rolling" the new value into the current array while discarding the element which was added maxElement add operations ago. The value replaced is returned from this method. Until an array contains the maximum number of element, this method has the same result as the addElement(double) operation. Once the maximum number of elements has been reached this implementation inserts the new values starting at index 0 of the internal storage array. This allows for efficient rolling, but prevents us from preserving the order of the added values.

Note: This function will return Double.NaN if no value has been discarded in this roll. This can happen when the array has not met the size limitation introduced in the constructor.

Specified by:
addElementRolling in interface DoubleArray
Parameters:
value - the value to be added to the array
Returns:
Returns the value which a has been "removed" from the database. Important: If the element array has not reached the maximum size, then it is possible that no element will be discarded from a given roll. In this case this method will return a Double.NaN value.
See Also:
DoubleArray.addElementRolling(double)

getElements

public double[] getElements()
Provides an array of double[] which contain the number of elements added to this array. This method will return an array from zero to maxElements in length.

Specified by:
getElements in interface DoubleArray
Returns:
The array of elements added to this DoubleArray implementation.
See Also:
DoubleArray.getElements()

getValues

public double[] getValues()
Returns the internal storage array

Returns:
the internal storage array used by this object

start

public int start()
The starting index in the InternalArray.

Returns:
starting index.

clear

public void clear()
Clear the array - drop all the data and start with a blank internal array. This implementation takes care of setting the size of the array back to zero, and reinitializing the internal storage array.

Specified by:
clear in interface DoubleArray
See Also:
DoubleArray.clear()


Copyright © 2003-2004 Apache Software Foundation. All Rights Reserved.