org.apache.commons.math.util
Class ContractableDoubleArray

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

public class ContractableDoubleArray
extends ExpandableDoubleArray
implements Serializable

A variable length double array implementation and extension of ExpandableDoubleArray which automatically handles expanding and contracting double arrays.

This class extends the functionality of ExpandableDoubleArray and inherits the expansion parameters from that class. If a developer instantiates a ContractableDoubleArray and only adds values to that instance, the behavior of this class is no different from the behavior of the super-class ExpandableDoubleArray. If, on the other hand, elements are removed from the array, this implementation tests an additional parameter contractionCriteria. The contractionCriteria dictates when this implementation will contract the size of the internal storage array to the number of elements + 1. This check is performed after every operation that alters the number of elements in the array.

Note that the contractionCriteria must always be greater than the expansionFactor. If this were not the case (assume a contractionCriteria of 1.5f and a expansionFactor of 2.0f) an endless series of expansions and contractions would occur. If the length of this array is highly varied over time it is a good idea to trade efficient memory usage for performance. Each time an array is expanded or contracted the meaningful portions of the internal storage array are copied to a new array and the reference to the internal storage array is swapped.

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

Field Summary
 
Fields inherited from class org.apache.commons.math.util.ExpandableDoubleArray
expansionFactor, initialCapacity, internalArray, numElements, startIndex
 
Constructor Summary
ContractableDoubleArray()
          Create an expandable double array with the default initial capacity of 16, an expansion factor of 2.00, and a contractionCriteria of 2.5
ContractableDoubleArray(int initialCapacity)
          Create an expandable double array with the specified initial capacity, the defult expansion factor of 2.00, and a contractionCriteria of 2.5
ContractableDoubleArray(int initialCapacity, float expansionFactor)
          Create an expandable double array with the specificed initial capacity and expand factor, with a contractionCriteria of 2.5
ContractableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria)
          Create an expandable double array with the specificed initial capacity, expand factor, and contractionCriteria
 
Method Summary
 void addElement(double value)
          Adds an element to the end of this expandable array
 double addElementRolling(double value)
           Adds an element to the end of this expandable array and discards a value from the front of the array.
protected  void checkContractExpand(float contractionCritera, float expansionFactor)
          Checks the expansion factor and the contraction criteria and throws an IllegalArgumentException if the contractionCriteria is less than the expansionCriteria
 void contract()
          Contracts the storage array to the (size of the element set) + 1 - to avoid a zero length array.
 void discardFrontElements(int i)
          Discards values from the front of the list.
 float getContractionCriteria()
          The contraction criteria defines when the internal array will contract to store only the number of elements in the element array.
 void setContractionCriteria(float contractionCriteria)
          Sets the contraction criteria for this ExpandContractDoubleArray.
 void setElement(int index, double value)
          Sets the element at the specified index.
 void setExpansionFactor(float expansionFactor)
          Method invokes the super class' setExpansionFactor but first it must validate the combination of expansionFactor and contractionCriteria.
 
Methods inherited from class org.apache.commons.math.util.ExpandableDoubleArray
clear, expand, getElement, getElements, getExpansionFactor, getNumElements, getValues, setInitialCapacity, setNumElements, start
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ContractableDoubleArray

public ContractableDoubleArray()
Create an expandable double array with the default initial capacity of 16, an expansion factor of 2.00, and a contractionCriteria of 2.5


ContractableDoubleArray

public ContractableDoubleArray(int initialCapacity)
Create an expandable double array with the specified initial capacity, the defult expansion factor of 2.00, and a contractionCriteria of 2.5

Parameters:
initialCapacity - The initial size of the internal storage array

ContractableDoubleArray

public ContractableDoubleArray(int initialCapacity,
                               float expansionFactor)
Create an expandable double array with the specificed initial capacity and expand factor, with a contractionCriteria of 2.5

Parameters:
initialCapacity - The initial size of the internal storage array
expansionFactor - the array will be expanded based on this parameter

ContractableDoubleArray

public ContractableDoubleArray(int initialCapacity,
                               float expansionFactor,
                               float contractionCriteria)
Create an expandable double array with the specificed initial capacity, expand factor, and contractionCriteria

Parameters:
initialCapacity - The initial size of the internal storage array
expansionFactor - the array will be expanded based on this parameter
contractionCriteria - The contraction Criteria.
Method Detail

contract

public void contract()
Contracts the storage array to the (size of the element set) + 1 - to avoid a zero length array. This function also resets the startIndex to zero.


addElement

public void addElement(double value)
Adds an element to the end of this expandable array

Specified by:
addElement in interface DoubleArray
Overrides:
addElement in class ExpandableDoubleArray
Parameters:
value - to be added to end of array

addElementRolling

public double addElementRolling(double value)

Adds an element to the end of this expandable array and discards a value from the front of the array. This method has the effect of adding a value to the end of the list and discarded an element from the front of the list.

When an array rolls it actually "scrolls" the element array in the internal storage array. An element is added to the end of the array, and the first element of the array is discard by incrementing the starting index of the element array within the internal storage array. Over time this will create an orphaned prefix to the element array within the internal storage array. If this function is called frequently, this orphaned prefix list will gradually push the internal storage vs. element storage to the contractionCriteria.

Specified by:
addElementRolling in interface DoubleArray
Overrides:
addElementRolling in class ExpandableDoubleArray
Parameters:
value - to be added to end of array
Returns:
value added

setElement

public void setElement(int index,
                       double value)
Description copied from class: ExpandableDoubleArray
Sets the element at the specified index. This method will expand the internal storage array to accomodate the insertion of a value at an index beyond the current capacity.

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

setExpansionFactor

public void setExpansionFactor(float expansionFactor)
Method invokes the super class' setExpansionFactor but first it must validate the combination of expansionFactor and contractionCriteria.

Overrides:
setExpansionFactor in class ExpandableDoubleArray
Parameters:
expansionFactor - the expansion factor of this array
See Also:
ExpandableDoubleArray.setExpansionFactor(float)

getContractionCriteria

public float getContractionCriteria()
The contraction criteria defines when the internal array will contract to store only the number of elements in the element array. This contractionCriteria gaurantees that the internal storage array will never exceed this factor more than the space needed to store numElements.

Returns:
the contraction criteria used to reclaim memory when array is empty

setContractionCriteria

public void setContractionCriteria(float contractionCriteria)
Sets the contraction criteria for this ExpandContractDoubleArray.

Parameters:
contractionCriteria - contraction criteria

checkContractExpand

protected void checkContractExpand(float contractionCritera,
                                   float expansionFactor)
Checks the expansion factor and the contraction criteria and throws an IllegalArgumentException if the contractionCriteria is less than the expansionCriteria

Parameters:
expansionFactor - factor to be checked
contractionCritera - critera to be checked

discardFrontElements

public void discardFrontElements(int i)
Description copied from class: ExpandableDoubleArray
Discards values from the front of the list. This function removes n elements from the front of the array.

Overrides:
discardFrontElements in class ExpandableDoubleArray
Parameters:
i - number of elements to discard from the front of the array.
See Also:
ExpandableDoubleArray.discardFrontElements(int)


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