ResizableDoubleArray (patrius 4.3 API)

java.lang.Object
- fr.cnes.sirius.patrius.math.util.ResizableDoubleArray

All Implemented Interfaces:

DoubleArray, Serializable
```
public class ResizableDoubleArray
extends Object
implements DoubleArray, Serializable
```
A variable length DoubleArray implementation that automatically handles expanding and contracting its internal storage array as elements are added and removed.

Important note: Usage should not assume that this class is thread-safe even though some of the methods are synchronized. This qualifier will be dropped in the next major release (4.0).

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.

Version:

$Id: ResizableDoubleArray.java 18108 2017-10-04 06:45:27Z bignon $

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ResizableDoubleArray.ExpansionMode
Specification of expansion algorithm.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ResizableDoubleArray.ExpansionMode` Specification of expansion algorithm.

Constructor Summary

Constructors
Constructor and 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 expansionFactorIn)` Creates an instance with the specified initial capacity and expansion factor.
`ResizableDoubleArray(int initialCapacity, double expansionFactorIn, double contractionCriterionIn)` Creates an instance with the specified initial capacity, expansion factor, and contraction criteria.
`ResizableDoubleArray(int initialCapacity, double expansionFactorIn, double contractionCriterionIn, ResizableDoubleArray.ExpansionMode expansionModeIn, double... data)` Creates an instance with the specified properties.
`ResizableDoubleArray(ResizableDoubleArray original)` Copy constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`static void`	`copy(ResizableDoubleArray source, ResizableDoubleArray dest)` Copies source to dest, copying the underlying data, so dest is a new, independent copy of source.
`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`.
`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.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ResizableDoubleArray
```
public ResizableDoubleArray()
```
    Creates an instance with default properties.
    - initialCapacity = 16
    - expansionMode = MULTIPLICATIVE
    - expansionFactor = 2.0
    - contractionCriterion = 2.5
  - ResizableDoubleArray
```
public ResizableDoubleArray(int initialCapacity)
```
    Creates an instance with the specified initial capacity. Other properties take default values:
    - expansionMode = MULTIPLICATIVE
    - expansionFactor = 2.0
    - contractionCriterion = 2.5
    Parameters:
    
    initialCapacity - Initial size of the internal storage array.
    
    Throws:
    
    MathIllegalArgumentException - if initialCapacity <= 0.
  - ResizableDoubleArray
```
public 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. 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:
    - initialCapacity = 16
    - expansionMode = MULTIPLICATIVE
    - expansionFactor = 2.0
    - contractionCriterion = 2.5
    Parameters:
    
    initialArray - initial array
    
    Since:
    
    2.2
  - ResizableDoubleArray
```
public ResizableDoubleArray(int initialCapacity,
                            double expansionFactorIn)
```
    Creates an instance with the specified initial capacity and expansion factor. The remaining properties take default values:
    - expansionMode = MULTIPLICATIVE
    - contractionCriterion = 0.5 + expansionFactor
    Throws IllegalArgumentException if the following conditions are not met:
    - initialCapacity > 0
    - expansionFactor > 1
    Parameters:
    
    initialCapacity - Initial size of the internal storage array.
    
    expansionFactorIn - The array will be expanded based on this parameter.
    
    Throws:
    
    MathIllegalArgumentException - if parameters are not valid.
    
    Since:
    
    3.1
  - ResizableDoubleArray
```
public ResizableDoubleArray(int initialCapacity,
                            double expansionFactorIn,
                            double contractionCriterionIn)
```
    Creates an instance with the specified initial capacity, expansion factor, and contraction criteria. The expansion mode will default to MULTIPLICATIVE.
    Throws IllegalArgumentException if the following conditions are not met:
    - initialCapacity > 0
    - expansionFactor > 1
    - contractionCriterion >= expansionFactor
    Parameters:
    
    initialCapacity - Initial size of the internal storage array..
    
    expansionFactorIn - The array will be expanded based on this parameter.
    
    contractionCriterionIn - Contraction criterion.
    
    Throws:
    
    MathIllegalArgumentException - if the parameters are not valid.
    
    Since:
    
    3.1
  - ResizableDoubleArray
```
public ResizableDoubleArray(int initialCapacity,
                            double expansionFactorIn,
                            double contractionCriterionIn,
                            ResizableDoubleArray.ExpansionMode expansionModeIn,
                            double... data)
```
    Creates an instance with the specified properties.
    Throws MathIllegalArgumentException if the following conditions are not met:
    - initialCapacity > 0
    - expansionFactor > 1
    - contractionCriterion >= expansionFactor
    Parameters:
    
    initialCapacity - Initial size of the internal storage array.
    
    expansionFactorIn - The array will be expanded based on this parameter.
    
    contractionCriterionIn - Contraction criteria.
    
    expansionModeIn - Expansion mode.
    
    data - Initial contents of the array.
    
    Throws:
    
    MathIllegalArgumentException - if the parameters are not valid.
  - ResizableDoubleArray
```
public ResizableDoubleArray(ResizableDoubleArray original)
```
    Copy constructor. Creates a new ResizableDoubleArray that is a deep, fresh copy of the original. Needs to acquire synchronization lock on original. Original may not be null; otherwise a NullArgumentException is thrown.
    
    Parameters:
    
    original - array to copy
    
    Throws:
    
    NullArgumentException - if original is null
    
    Since:
    
    2.0
- Method Detail
  - addElement
```
public void addElement(double value)
```
    Adds an element to the end of this expandable array.
    
    Specified by:
    
    addElement in interface DoubleArray
    
    Parameters:
    
    value - Value to be added to end of array.
  - addElements
```
public void addElements(double[] values)
```
    Adds several element to the end of this expandable array.
    
    Specified by:
    
    addElements in interface DoubleArray
    
    Parameters:
    
    values - Values to be added to end of array.
    
    Since:
    
    2.2
  - addElementRolling
```
public double addElementRolling(double value)
```
    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.
    
    Specified by:
    
    addElementRolling in interface DoubleArray
    
    Parameters:
    
    value - Value to be added to the array.
    
    Returns:
    
    the value which has been discarded or "pushed" out of the array by this rolling insert.
  - substituteMostRecentElement
```
public double substituteMostRecentElement(double value)
```
    Substitutes 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 IllegalStateException is thrown.
    
    Parameters:
    
    value - New value to substitute for the most recently added value
    
    Returns:
    
    the value that has been replaced in the array.
    
    Throws:
    
    MathIllegalStateException - if the array is empty
    
    Since:
    
    2.0
  - checkContractExpand
```
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.
    
    Parameters:
    
    contraction - Criterion to be checked.
    
    expansion - Factor to be checked.
    
    Throws:
    
    NumberIsTooSmallException - if contraction < expansion.
    
    NumberIsTooSmallException - if contraction <= 1.
    
    NumberIsTooSmallException - if expansion <= 1 .
    
    Since:
    
    3.1
  - clear
```
public void clear()
```
    Clear the array contents, resetting the number of elements to zero.
    
    Specified by:
    
    clear in interface DoubleArray
  - 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.
  - discardFrontElements
```
public void discardFrontElements(int i)
```
    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:
    
    MathIllegalArgumentException - if i is greater than numElements.
    
    Since:
    
    2.0
  - discardMostRecentElements
```
public void discardMostRecentElements(int i)
```
    Discards the 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. Throws illegalArgumentException if i exceeds numElements.
    
    Parameters:
    
    i - the number of elements to discard from the end of the array
    
    Throws:
    
    MathIllegalArgumentException - if i is greater than numElements.
    
    Since:
    
    2.0
  - expand
```
protected void expand()
```
    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
  - getContractionCriterion
```
public double getContractionCriterion()
```
    The contraction criterion 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.
    
    Returns:
    
    the contraction criterion used to reclaim memory.
    
    Since:
    
    3.1
  - getElement
```
public double getElement(int index)
```
    Returns the element at the specified index
    
    Specified by:
    
    getElement in interface DoubleArray
    
    Parameters:
    
    index - index to fetch a value from
    
    Returns:
    
    value stored at the specified index
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if index is less than zero or is greater than getNumElements() - 1.
  - getElements
```
public double[] getElements()
```
    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.
    
    Specified by:
    
    getElements in interface DoubleArray
    
    Returns:
    
    the double array.
  - getCapacity
```
public int getCapacity()
```
    Gets the currently allocated size of the internal data structure used for storing elements. This is not to be confused with the number of elements actually stored.
    
    Returns:
    
    the length of the internal array.
    
    Since:
    
    3.1
  - getNumElements
```
public int getNumElements()
```
    Returns the number of elements currently in the array. Please note that this is different from the length of the internal storage array.
    
    Specified by:
    
    getNumElements in interface DoubleArray
    
    Returns:
    
    the number of elements.
  - getArrayRef
```
protected double[] getArrayRef()
```
    Provides direct access to the internal storage array. Please note that this method returns a reference to this object's storage array, not a copy.
    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.
    
    Returns:
    
    the internal storage array used by this object.
    
    Since:
    
    3.1
  - getStartIndex
```
protected int getStartIndex()
```
    Returns the "start index" of the internal array. This index is the position of the first addressable element in the internal storage array. The addressable elements in the array are at indices contained in the interval [getStartIndex(), getStartIndex() + getNumElements() - 1].
    
    Returns:
    
    the start index.
    
    Since:
    
    3.1
  - compute
```
public double compute(MathArrays.Function f)
```
    Performs an operation on the addressable elements of the array.
    
    Parameters:
    
    f - Function to be applied on this array.
    
    Returns:
    
    the result.
    
    Since:
    
    3.1
  - setElement
```
public void setElement(int index,
                       double value)
```
    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).
    
    Specified by:
    
    setElement in interface DoubleArray
    
    Parameters:
    
    index - index to store a value in
    
    value - value to store at the specified index
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if index < 0.
  - setNumElements
```
public 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. This function will also expand the internal array as needed.
    
    Parameters:
    
    i - a new number of elements
    
    Throws:
    
    MathIllegalArgumentException - if i is negative.
  - copy
```
public static void copy(ResizableDoubleArray source,
                        ResizableDoubleArray dest)
```
    Copies source to dest, copying the underlying data, so dest is a new, independent copy of source. Does not contract before the copy.
    
    Obtains synchronization locks on both source and dest (in that order) before performing the copy.
    
    Neither source nor dest may be null; otherwise a NullArgumentException is thrown
    
    Parameters:
    
    source - ResizableDoubleArray to copy
    
    dest - ResizableArray to replace with a copy of the source array
    
    Throws:
    
    NullArgumentException - if either source or dest is null
    
    Since:
    
    2.0
  - copy
```
public ResizableDoubleArray copy()
```
    Returns a copy of the ResizableDoubleArray. Does not contract before the copy, so the returned object is an exact copy of this.
    
    Returns:
    
    a new ResizableDoubleArray with the same data and configuration properties as this
    
    Since:
    
    2.0
  - equals
```
public boolean equals(Object object)
```
    Returns true iff object is a ResizableDoubleArray with the same properties as this and an identical internal storage array.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - object to be compared for equality with this
    
    Returns:
    
    true iff object is a ResizableDoubleArray with the same data and properties as this
    
    Since:
    
    2.0
  - hashCode
```
public int hashCode()
```
    Returns a hash code consistent with equals.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hash code representing this ResizableDoubleArray.
    
    Since:
    
    2.0

Class ResizableDoubleArray

Important note: Usage should not assume that this class is thread-safe even though some of the methods are `synchronized`. This qualifier will be dropped in the next major release (4.0).

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

Method Detail

addElement

addElements

addElementRolling

substituteMostRecentElement

checkContractExpand

clear

contract

discardFrontElements

discardMostRecentElements

expand

getContractionCriterion

getElement

getElements

getCapacity

getNumElements

getArrayRef

getStartIndex

compute

setElement

setNumElements

copy

copy

equals

hashCode

Class ResizableDoubleArray

Important note: Usage should not assume that this class is thread-safe even though some of the methods are synchronized. This qualifier will be dropped in the next major release (4.0).

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

ResizableDoubleArray

Method Detail

addElement

addElements

addElementRolling

substituteMostRecentElement

checkContractExpand

clear

contract

discardFrontElements

discardMostRecentElements

expand

getContractionCriterion

getElement

getElements

getCapacity

getNumElements

getArrayRef

getStartIndex

compute

setElement

setNumElements

copy

copy

equals

hashCode

Important note: Usage should not assume that this class is thread-safe even though some of the methods are `synchronized`. This qualifier will be dropped in the next major release (4.0).