| java.lang.Object
 org.apache.commons.math.util.ResizableDoubleArray
| ResizableDoubleArray | | public class ResizableDoubleArray implements DoubleArray,Serializable(Code) | |
A variable length
DoubleArray implementation that automatically
handles expanding and contracting its internal storage array as elements
are added and removed.
The internal storage array starts with capacity determined by the
initialCapacity property, which can be set by the constructor.
The default initial capacity is 16. Adding elements using
ResizableDoubleArray.addElement(double) appends elements to the end of the array. When
there are no open entries at the end of the internal storage array, the
array is expanded. The size of the expanded array depends on the
expansionMode and expansionFactor properties.
The expansionMode determines whether the size of the array is
multiplied by the expansionFactor (MULTIPLICATIVE_MODE) or if
the expansion is additive (ADDITIVE_MODE -- expansionFactor
storage locations added). The default expansionMode is
MULTIPLICATIVE_MODE and the default expansionFactor
is 2.0.
The
ResizableDoubleArray.addElementRolling(double) method adds a new element to the end
of the internal storage array and adjusts the "usable window" of the
internal array forward by one position (effectively making what was the
second element the first, and so on). Repeated activations of this method
(or activation of
ResizableDoubleArray.discardFrontElements(int) ) will effectively orphan
the storage locations at the beginning of the internal storage array. To
reclaim this storage, each time one of these methods is activated, the size
of the internal storage array is compared to the number of addressable
elements (the numElements property) and if the difference
is too large, the internal array is contracted to size
numElements + 1. The determination of when the internal
storage array is "too large" depends on the expansionMode and
contractionFactor properties. If the expansionMode
is MULTIPLICATIVE_MODE, contraction is triggered when the
ratio between storage array length and numElements exceeds
contractionFactor. If the expansionMode
is ADDITIVE_MODE, the number of excess storage locations
is compared to contractionFactor.
To avoid cycles of expansions and contractions, the
expansionFactor must not exceed the
contractionFactor. Constructors and mutators for both of these
properties enforce this requirement, throwing IllegalArgumentException if it
is violated.
version:
$Revision: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $ |
| Field Summary | |
| final public static int | ADDITIVE_MODE
| | final public static int | MULTIPLICATIVE_MODE
| | protected float | contractionCriteria
The contraction criteria determines when the internal array will be
contracted to fit the number of elements contained in the element
array + 1. | | protected float | expansionFactor
The expansion factor of the array. | | protected int | expansionMode
Determines whether array expansion by expansionFactor
is additive or multiplicative. | | protected int | initialCapacity
The initial capacity of the array. | | protected double[] | internalArray
The internal storage array. | | protected int | numElements
The number of addressable elements in the array. | | protected int | startIndex
The position of the first addressable element in the internal storage
array. |
| Constructor Summary | |
| public | ResizableDoubleArray()
Create a ResizableArray with default properties. | | public | ResizableDoubleArray(int initialCapacity)
Create a ResizableArray with the specified initial capacity. | | public | ResizableDoubleArray(int initialCapacity, float expansionFactor)
Create a ResizableArray with the specified initial capacity
and expansion factor. | | public | ResizableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria)
Create a ResizableArray with the specified initialCapacity,
expansionFactor, and contractionCriteria. | | public | ResizableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria, int expansionMode)
|
| Method Summary | |
| public synchronized void | addElement(double value)
Adds an element to the end of this expandable array. | | public synchronized double | addElementRolling(double value)
Adds an element to the end of the array and removes the first
element in the array. | | protected void | checkContractExpand(float contractionCritera, float expansionFactor)
| | public synchronized void | clear()
Clear the array, reset the size to the initialCapacity and the number
of elements to zero. | | public synchronized void | contract()
Contracts the storage array to the (size of the element set) + 1 - to
avoid a zero length array. | | public synchronized void | discardFrontElements(int i)
Discards the i initial elements of the array. | | protected synchronized void | expand()
Expands the internal storage array using the expansion factor. | | public float | getContractionCriteria()
The contraction criteria defines when the internal array will contract
to store only the number of elements in the element array. | | public synchronized double | getElement(int index)
| | public synchronized double[] | getElements()
Returns a double array containing the elements of this
ResizableArray. | | public float | getExpansionFactor()
The expansion factor controls the size of a new aray when an array
needs to be expanded. | | public int | getExpansionMode()
The expansionMode determines whether the internal storage
array grows additively (ADDITIVE_MODE) or multiplicatively
(MULTIPLICATIVE_MODE) when it is expanded. | | synchronized int | getInternalLength()
Notice the package scope on this method. | | public synchronized int | getNumElements()
Returns the number of elements currently in the array. | | public synchronized double[] | getValues()
Returns the internal storage array. | | public void | setContractionCriteria(float contractionCriteria)
Sets the contraction criteria for this ExpandContractDoubleArray. | | public synchronized void | setElement(int index, double value)
Sets the element at the specified index. | | public void | setExpansionFactor(float expansionFactor)
Sets the expansionFactor. | | public void | setExpansionMode(int expansionMode)
Sets the expansionMode. | | protected void | setInitialCapacity(int initialCapacity)
Sets the initial capacity. | | public synchronized void | setNumElements(int i)
This function allows you to control the number of elements contained
in this array, and can be used to "throw out" the last n values in an
array. | | public synchronized int | start()
Returns the starting index of the internal array. |
| ADDITIVE_MODE | | final public static int ADDITIVE_MODE(Code) | | additive expansion mode
|
| MULTIPLICATIVE_MODE | | final public static int MULTIPLICATIVE_MODE(Code) | | multiplicative expansion mode
|
| contractionCriteria | | protected float contractionCriteria(Code) | | The contraction criteria determines when the internal array will be
contracted to fit the number of elements contained in the element
array + 1.
|
| expansionFactor | | protected float expansionFactor(Code) | | The expansion factor of the array. When the array needs to be expanded,
the new array size will be
internalArray.length * expansionFactor
if expansionMode is set to MULTIPLICATIVE_MODE, or
internalArray.length + expansionFactor if
expansionMode is set to ADDITIVE_MODE.
|
| expansionMode | | protected int expansionMode(Code) | | Determines whether array expansion by expansionFactor
is additive or multiplicative.
|
| initialCapacity | | protected int initialCapacity(Code) | | The initial capacity of the array. Initial capacity is not exposed as a
property as it is only meaningful when passed to a constructor.
|
| internalArray | | protected double[] internalArray(Code) | | The internal storage array.
|
| numElements | | protected int numElements(Code) | | The number of addressable elements in the array. Note that this
has nothing to do with the length of the internal storage array.
|
| startIndex | | protected int startIndex(Code) | | The position of the first addressable element in the internal storage
array. The addressable elements in the array are
internalArray[startIndex],...,internalArray[startIndex + numElements -1]
|
| ResizableDoubleArray | | public ResizableDoubleArray()(Code) | | Create a ResizableArray with default properties.
initialCapacity = 16expansionMode = MULTIPLICATIVE_MODEexpansionFactor = 2.5contractionFactor = 2.0
|
| ResizableDoubleArray | | public ResizableDoubleArray(int initialCapacity)(Code) | | Create a ResizableArray with the specified initial capacity. Other
properties take default values:
expansionMode = MULTIPLICATIVE_MODEexpansionFactor = 2.5contractionFactor = 2.0
Parameters:
initialCapacity - The initial size of the internal storage array
throws:
IllegalArgumentException - if initialCapacity is not > 0 |
| ResizableDoubleArray | | public ResizableDoubleArray(int initialCapacity, float expansionFactor)(Code) | |
Create a ResizableArray with the specified initial capacity
and expansion factor. The remaining properties take default
values:
expansionMode = MULTIPLICATIVE_MODEcontractionFactor = 0.5 + expansionFactor
Throws IllegalArgumentException if the following conditions are
not met:
initialCapacity > 0expansionFactor > 1
Parameters:
initialCapacity - The initial size of the internal storage array
Parameters:
expansionFactor - the array will be expanded based on this parameter
throws:
IllegalArgumentException - if parameters are not valid |
| ResizableDoubleArray | | public ResizableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria)(Code) | |
Create a ResizableArray with the specified initialCapacity,
expansionFactor, and contractionCriteria. The expansionMode
will default to MULTIPLICATIVE_MODE.
Throws IllegalArgumentException if the following conditions are
not met:
initialCapacity > 0expansionFactor > 1contractionFactor >= expansionFactor
Parameters:
initialCapacity - The initial size of the internal storage array
Parameters:
expansionFactor - the array will be expanded based on this parameter
Parameters:
contractionCriteria - The contraction Criteria.
throws:
IllegalArgumentException - if parameters are not valid |
| ResizableDoubleArray | | public ResizableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria, int expansionMode)(Code) | |
Create a ResizableArray with the specified properties.
Throws IllegalArgumentException if the following conditions are
not met:
initialCapacity > 0expansionFactor > 1contractionFactor >= expansionFactorexpansionMode in {MULTIPLICATIVE_MODE, ADDITIVE_MODE}
Parameters:
initialCapacity - the initial size of the internal storage array
Parameters:
expansionFactor - the array will be expanded based on this parameter
Parameters:
contractionCriteria - the contraction Criteria
Parameters:
expansionMode - the expansion mode
throws:
IllegalArgumentException - if parameters are not valid |
| addElement | | public synchronized void addElement(double value)(Code) | | Adds an element to the end of this expandable array.
Parameters:
value - to be added to end of array |
| addElementRolling | | public synchronized double addElementRolling(double value)(Code) | |
Adds an element to the end of the array and removes the first
element in the array. Returns the discarded first element.
The effect is similar to a push operation in a FIFO queue.
Example: If the array contains the elements 1, 2, 3, 4 (in that order)
and addElementRolling(5) is invoked, the result is an array containing
the entries 2, 3, 4, 5 and the value returned is 1.
Parameters:
value - the value to be added to the array the value which has been discarded or "pushed" out of the arrayby this rolling insert |
| checkContractExpand | | protected void checkContractExpand(float contractionCritera, float expansionFactor)(Code) | | 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
Parameters:
contractionCritera - critera to be checked
throws:
IllegalArgumentException - if the contractionCriteria is less thanthe expansionCriteria. |
| clear | | public synchronized void clear()(Code) | | Clear the array, reset the size to the initialCapacity and the number
of elements to zero.
|
| contract | | public synchronized void contract()(Code) | | 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.
|
| discardFrontElements | | public synchronized void discardFrontElements(int i)(Code) | | Discards the i initial elements of the array. For example,
if the array contains the elements 1,2,3,4, invoking
discardFrontElements(2) will cause the first two elements
to be discarded, leaving 3,4 in the array. Throws illegalArgumentException
if i exceeds numElements.
Parameters:
i - the number of elements to discard from the front of the array
throws:
IllegalArgumentException - if i is greater than numElements. |
| expand | | protected synchronized void expand()(Code) | | Expands the internal storage array using the expansion factor.
if expansionMode is set to MULTIPLICATIVE_MODE,
the new array size will be internalArray.length * expansionFactor.
If expansionMode is set to ADDITIVE_MODE, the length
after expansion will be internalArray.length + expansionFactor
|
| getContractionCriteria | | public float getContractionCriteria()(Code) | | The contraction criteria defines when the internal array will contract
to store only the number of elements in the element array.
If the expansionMode is MULTIPLICATIVE_MODE,
contraction is triggered when the ratio between storage array length
and numElements exceeds contractionFactor.
If the expansionMode is ADDITIVE_MODE, the
number of excess storage locations is compared to
contractionFactor.
the contraction criteria used to reclaim memory. |
| getElement | | public synchronized double getElement(int index)(Code) | | Returns the element at the specified index
Parameters:
index - index to fetch a value from value stored at the specified index
throws:
ArrayIndexOutOfBoundsException - if index is less thanzero or is greater than getNumElements() - 1. |
| getElements | | public synchronized double[] getElements()(Code) | | Returns a double array containing the elements of this
ResizableArray. This method returns a copy, not a
reference to the underlying array, so that changes made to the returned
array have no effect on this ResizableArray.
the double array. |
| getExpansionFactor | | public float getExpansionFactor()(Code) | | The expansion factor controls the size of a new aray when an array
needs to be expanded. The expansionMode
determines whether the size of the array is multiplied by the
expansionFactor (MULTIPLICATIVE_MODE) or if
the expansion is additive (ADDITIVE_MODE -- expansionFactor
storage locations added). The default expansionMode is
MULTIPLICATIVE_MODE and the default expansionFactor
is 2.0.
the expansion factor of this expandable double array |
| getExpansionMode | | public int getExpansionMode()(Code) | | The expansionMode determines whether the internal storage
array grows additively (ADDITIVE_MODE) or multiplicatively
(MULTIPLICATIVE_MODE) when it is expanded.
Returns the expansionMode. |
| getInternalLength | | synchronized int getInternalLength()(Code) | | Notice the package scope on this method. This method is simply here
for the JUnit test, it allows us check if the expansion is working
properly after a number of expansions. This is not meant to be a part
of the public interface of this class.
the length of the internal storage array. |
| getNumElements | | public synchronized int getNumElements()(Code) | | Returns the number of elements currently in the array. Please note
that this is different from the length of the internal storage array.
number of elements |
| getValues | | public synchronized double[] getValues()(Code) | | Returns the internal storage array. Note that this method returns
a reference to the internal storage array, not a copy, and to correctly
address elements of the array, the startIndex is
required (available via the
ResizableDoubleArray.start method). This method should
only be used in cases where copying the internal array is not practical.
The
ResizableDoubleArray.getElements method should be used in all other cases.
the internal storage array used by this object |
| setContractionCriteria | | public void setContractionCriteria(float contractionCriteria)(Code) | | Sets the contraction criteria for this ExpandContractDoubleArray.
Parameters:
contractionCriteria - contraction criteria |
| setElement | | public synchronized void setElement(int index, double value)(Code) | | Sets the element at the specified index. If the specified index is greater than
getNumElements() - 1, the numElements property
is increased to index +1 and additional storage is allocated
(if necessary) for the new element and all (uninitialized) elements
between the new element and the previous end of the array).
Parameters:
index - index to store a value in
Parameters:
value - value to store at the specified index
throws:
ArrayIndexOutOfBoundsException - if index is less thanzero. |
| setExpansionFactor | | public void setExpansionFactor(float expansionFactor)(Code) | | Sets the expansionFactor. Throws IllegalArgumentException if the
the following conditions are not met:
expansionFactor > 1contractionFactor >= expansionFactor
Parameters:
expansionFactor - the new expansion factor value.
throws:
IllegalArgumentException - if expansionFactor is <= 1 or greaterthan contractionFactor |
| setExpansionMode | | public void setExpansionMode(int expansionMode)(Code) | | Sets the expansionMode. The specified value must be one of
ADDITIVE_MODE, MULTIPLICATIVE_MODE.
Parameters:
expansionMode - The expansionMode to set.
throws:
IllegalArgumentException - if the specified mode value is not valid |
| setInitialCapacity | | protected void setInitialCapacity(int initialCapacity)(Code) | | Sets the initial capacity. Should only be invoked by constructors.
Parameters:
initialCapacity - of the array
throws:
IllegalArgumentException - if initialCapacity is notpositive. |
| setNumElements | | public synchronized void setNumElements(int i)(Code) | | This function allows you to control the number of elements contained
in this array, and can be used to "throw out" the last n values in an
array. This function will also expand the internal array as needed.
Parameters:
i - a new number of elements
throws:
IllegalArgumentException - if i is negative. |
| start | | public synchronized int start()(Code) | | Returns the starting index of the internal array. The starting index is
the position of the first addressable element in the internal storage
array. The addressable elements in the array are
internalArray[startIndex],...,internalArray[startIndex + numElements -1]
starting index |
|
|