Serializable
public class ResizableDoubleArray extends Object implements Serializable
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
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
(ResizableDoubleArray.ExpansionMode.MULTIPLICATIVE
) or if the expansion is additive
(ResizableDoubleArray.ExpansionMode.ADDITIVE
-- expansionFactor
storage
locations added).
The default expansionMode
is MULTIPLICATIVE
and the default
expansionFactor
is 2.
The 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 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
, contraction is triggered when the
ratio between storage array length and numElements
exceeds
contractionFactor.
If the expansionMode
is ADDITIVE
, 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 a MathIllegalArgumentException
if it is
violated.
Note: this class is NOT thread-safe.
Modifier and Type | Class | Description |
---|---|---|
static class |
ResizableDoubleArray.ExpansionMode |
Specification of expansion algorithm.
|
Constructor | Description |
---|---|
ResizableDoubleArray() |
Creates an instance with default properties.
|
ResizableDoubleArray(double[] initialArray) |
Creates an instance from an existing
double[] with the
initial capacity and numElements corresponding to the size of
the supplied double[] array. |
ResizableDoubleArray(int initialCapacity) |
Creates an instance with the specified initial capacity.
|
ResizableDoubleArray(int initialCapacity,
double expansionFactor) |
Creates an instance with the specified initial capacity
and expansion factor.
|
ResizableDoubleArray(int initialCapacity,
double expansionFactor,
double contractionCriterion) |
Creates an instance with the specified initial capacity,
expansion factor, and contraction criteria.
|
ResizableDoubleArray(int initialCapacity,
double expansionFactor,
double contractionCriterion,
ResizableDoubleArray.ExpansionMode expansionMode,
double... data) |
Creates an instance with the specified properties.
|
ResizableDoubleArray(ResizableDoubleArray original) |
Copy constructor.
|
Modifier and Type | Method | Description |
---|---|---|
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 the array and removes the first
element in the array.
|
void |
addElements(double[] values) |
Adds several element to the end of this expandable array.
|
protected void |
checkContractExpand(double contraction,
double expansion) |
Checks the expansion factor and the contraction criterion and raises
an exception if the contraction criterion is smaller than the
expansion criterion.
|
void |
clear() |
Clear the array contents, resetting the number of elements to zero.
|
double |
compute(MathArrays.Function f) |
Performs an operation on the addressable elements of the array.
|
void |
contract() |
Contracts the storage array to the (size of the element set) + 1 - to avoid
a zero length array.
|
ResizableDoubleArray |
copy() |
Returns a copy of the ResizableDoubleArray.
|
void |
discardFrontElements(int i) |
Discards the
i initial elements of the array. |
void |
discardMostRecentElements(int i) |
Discards the
i last elements of the array. |
boolean |
equals(Object object) |
Returns true iff object is a ResizableDoubleArray with the same properties
as this and an identical internal storage array.
|
protected void |
expand() |
Expands the internal storage array using the expansion factor.
|
protected double[] |
getArrayRef() |
Provides direct access to the internal storage array.
|
int |
getCapacity() |
Gets the currently allocated size of the internal data structure used
for storing elements.
|
double |
getContractionCriterion() |
The contraction criterion defines when the internal array will contract
to store only the number of elements in the element array.
|
double |
getElement(int index) |
Returns the element at the specified index.
|
double[] |
getElements() |
Returns a double array containing the elements of this ResizableArray.
|
double |
getExpansionFactor() |
The expansion factor controls the size of a new array when an array
needs to be expanded.
|
ResizableDoubleArray.ExpansionMode |
getExpansionMode() |
The expansion mode determines whether the internal storage
array grows additively or multiplicatively when it is expanded.
|
int |
getNumElements() |
Returns the number of elements currently in the array.
|
protected int |
getStartIndex() |
Returns the "start index" of the internal array.
|
int |
hashCode() |
Returns a hash code consistent with equals.
|
void |
setElement(int index,
double value) |
Sets the element at the specified index.
|
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.
|
double |
substituteMostRecentElement(double value) |
Substitutes
value for the most recently added value. |
public ResizableDoubleArray()
initialCapacity = 16
expansionMode = MULTIPLICATIVE
expansionFactor = 2.0
contractionCriterion = 2.5
public ResizableDoubleArray(int initialCapacity) throws MathIllegalArgumentException
Other properties take default values:
expansionMode = MULTIPLICATIVE
expansionFactor = 2.0
contractionCriterion = 2.5
initialCapacity
- Initial size of the internal storage array.MathIllegalArgumentException
- if initialCapacity <= 0
.public ResizableDoubleArray(double[] initialArray)
double[]
with the
initial capacity and numElements corresponding to the size of
the supplied double[]
array.
If the supplied array is null, a new empty array with the default initial capacity will be created. The input array is copied, not referenced. Other properties take default values:
expansionMode = MULTIPLICATIVE
expansionFactor = 2.0
contractionCriterion = 2.5
initialArray
- initial arraypublic ResizableDoubleArray(int initialCapacity, double expansionFactor) throws MathIllegalArgumentException
The remaining properties take default values:
expansionMode = MULTIPLICATIVE
contractionCriterion = 0.5 + expansionFactor
Throws MathIllegalArgumentException if the following conditions are not met:
initialCapacity > 0
expansionFactor > 1
initialCapacity
- Initial size of the internal storage array.expansionFactor
- The array will be expanded based on this parameter.MathIllegalArgumentException
- if parameters are not valid.public ResizableDoubleArray(int initialCapacity, double expansionFactor, double contractionCriterion) throws MathIllegalArgumentException
The expansion mode will default to MULTIPLICATIVE
.
Throws MathIllegalArgumentException if the following conditions are not met:
initialCapacity > 0
expansionFactor > 1
contractionCriterion >= expansionFactor
initialCapacity
- Initial size of the internal storage array.expansionFactor
- The array will be expanded based on this parameter.contractionCriterion
- Contraction criterion.MathIllegalArgumentException
- if the parameters are not valid.public ResizableDoubleArray(int initialCapacity, double expansionFactor, double contractionCriterion, ResizableDoubleArray.ExpansionMode expansionMode, double... data) throws MathIllegalArgumentException
initialCapacity > 0
expansionFactor > 1
contractionCriterion >= expansionFactor
initialCapacity
- Initial size of the internal storage array.expansionFactor
- The array will be expanded based on this parameter.contractionCriterion
- Contraction criteria.expansionMode
- Expansion mode.data
- Initial contents of the array.MathIllegalArgumentException
- if the parameters are not valid.NullArgumentException
- if expansionMode is nullpublic ResizableDoubleArray(ResizableDoubleArray original) throws NullArgumentException
Creates a new ResizableDoubleArray that is a deep, fresh copy of the original.
Original may not be null; otherwise a NullArgumentException
is thrown.
original
- array to copyNullArgumentException
- if original is nullpublic void addElement(double value)
value
- Value to be added to end of array.public void addElements(double[] values)
values
- Values to be added to end of array.public double addElementRolling(double value)
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.
value
- Value to be added to the array.public double substituteMostRecentElement(double value) throws MathIllegalStateException
value
for the most recently added value.
Returns the value that has been replaced. If the array is empty (i.e.
if numElements
is zero), an MathIllegalStateException is thrown.
value
- New value to substitute for the most recently added valueMathIllegalStateException
- if the array is emptyprotected void checkContractExpand(double contraction, double expansion) throws MathIllegalArgumentException
contraction
- Criterion to be checked.expansion
- Factor to be checked.MathIllegalArgumentException
- if contraction < expansion
.MathIllegalArgumentException
- if contraction <= 1
.MathIllegalArgumentException
- if expansion <= 1
.public void clear()
public void contract()
public void discardFrontElements(int i) throws MathIllegalArgumentException
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.
i
- the number of elements to discard from the front of the arrayMathIllegalArgumentException
- if i is greater than numElements.public void discardMostRecentElements(int i) throws MathIllegalArgumentException
i
last elements of the array.
For example, if the array contains the elements 1,2,3,4, invoking
discardMostRecentElements(2)
will cause the last two elements
to be discarded, leaving 1,2 in the array.
i
- the number of elements to discard from the end of the arrayMathIllegalArgumentException
- if i is greater than numElements.protected void expand()
If expansionMode
is set to MULTIPLICATIVE,
the new array size will be internalArray.length * expansionFactor
.
If expansionMode
is set to ADDITIVE, the length
after expansion will be internalArray.length + expansionFactor
.
public double getContractionCriterion()
If the expansionMode
is MULTIPLICATIVE
,
contraction is triggered when the ratio between storage array length
and numElements
exceeds contractionFactor
.
If the expansionMode
is ADDITIVE
, the
number of excess storage locations is compared to contractionFactor
.
public double getElement(int index)
index
- index to fetch a value fromArrayIndexOutOfBoundsException
- if index
is less than
zero or is greater than getNumElements() - 1
.public double[] getElements()
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.
public double getExpansionFactor()
The expansionMode
determines whether the size of the array
is multiplied by the expansionFactor
(MULTIPLICATIVE) or if
the expansion is additive (ADDITIVE -- expansionFactor
storage locations added). The default expansionMode
is
MULTIPLICATIVE and the default expansionFactor
is 2.0.
public ResizableDoubleArray.ExpansionMode getExpansionMode()
public int getCapacity()
the number of
elements actually stored
.public int getNumElements()
protected double[] getArrayRef()
To correctly address elements of the array, the "start index" is
required (available via the getStartIndex
method.
This method should only be used to avoid copying the internal array. The returned value must be used for reading only; other uses could lead to this object becoming inconsistent.
The getElements()
method has no such limitation since it
returns a copy of this array's addressable elements.
protected int getStartIndex()
The addressable elements in the array are at indices contained in
the interval [getStartIndex()
,
getStartIndex()
+ getNumElements()
- 1].
public double compute(MathArrays.Function f)
f
- Function to be applied on this array.public void setElement(int index, double value)
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).
index
- index to store a value invalue
- value to store at the specified indexArrayIndexOutOfBoundsException
- if index < 0
.public void setNumElements(int i) throws MathIllegalArgumentException
i
- a new number of elementsMathIllegalArgumentException
- if i
is negative.public ResizableDoubleArray copy()
public boolean equals(Object object)
Copyright © 2016–2018 Hipparchus.org. All rights reserved.