Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.math.util
Class ResizableDoubleArray

    java.lang.Object
      org.apache.commons.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.

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` (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 `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_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: 1.2 $ $Date: 2004/06/23 16:26:16 $
See Also:
  Serialized Form

Field Summary
`static int` | `ADDITIVE_MODE` additive expansion 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.
`static int` | `MULTIPLICATIVE_MODE` multiplicative expansion mode
`protected int` | `numElements` The number of addressable elements in the array.
`(package private) static long` | `serialVersionUID` Serializable version identifier
`protected int` | `startIndex` The position of the first addressable element in the internal storage array.

Constructor Summary
`ResizableDoubleArray()` Create a ResizableArray with default properties.
`ResizableDoubleArray(int initialCapacity)` Create a ResizableArray with the specified initial capacity.
`ResizableDoubleArray(int initialCapacity, float expansionFactor)` Create a ResizableArray with the specified initial capacity and expansion factor.
`ResizableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria)` Create a ResizableArray with the specified initialCapacity, expansionFactor, and contractionCriteria.
`ResizableDoubleArray(int initialCapacity, float expansionFactor, float contractionCriteria, int expansionMode)` Create a ResizableArray with the specified properties.

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 the array and removes the first element in 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` | `clear()` Clear the array, reset the size to the initialCapacity and the number of elements to zero.
`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 the `i`initial elements of the array.``
`protected void` | `expand()` Expands the internal storage array using the expansion factor.
`float` | `getContractionCriteria()` The contraction criteria 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`.
`float` | `getExpansionFactor()` The expansion factor controls the size of a new aray when an array needs to be expanded.
`int` | `getExpansionMode()` The `expansionMode` determines whether the internal storage array grows additively (ADDITIVE_MODE) or multiplicatively (MULTIPLICATIVE_MODE) when it is expanded.
`(package private) int` | `getInternalLength()` Notice the package scope on this method.
`int` | `getNumElements()` Returns the number of elements currently in the array.
`double[]` | `getValues()` Returns the internal storage 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)` Sets the expansionFactor.
`void` | `setExpansionMode(int expansionMode)` Sets the `expansionMode`.
`protected void` | `setInitialCapacity(int initialCapacity)` Sets the initial capacity.
`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.
`int` | `start()` Returns the starting index of the internal array.

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

Field Detail

### serialVersionUID

    static final long serialVersionUID

  Serializable version identifier

  See Also:
    Constant Field Values

### ADDITIVE_MODE

    public static final int ADDITIVE_MODE

  additive expansion mode

  See Also:
    Constant Field Values

### MULTIPLICATIVE_MODE

    public static final int MULTIPLICATIVE_MODE

  multiplicative expansion mode

  See Also:
    Constant Field Values

### contractionCriteria

    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.

### expansionFactor

    protected float expansionFactor

  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

  Determines whether array expansion by `expansionFactor` is additive or multiplicative.

### initialCapacity

    protected int initialCapacity

  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

  The internal storage array.

### numElements

    protected int numElements

  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

  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]`

Constructor Detail

### ResizableDoubleArray

    public ResizableDoubleArray()

  Create a ResizableArray with default properties.
  - `initialCapacity = 16`
  - `expansionMode = MULTIPLICATIVE_MODE`
  - `expansionFactor = 2.5`
  - `contractionFactor = 2.0`

### ResizableDoubleArray

    public ResizableDoubleArray(int initialCapacity)

  Create a ResizableArray with the specified initial capacity. Other properties take default values:
  - `expansionMode = MULTIPLICATIVE_MODE`
  - `expansionFactor = 2.5`
  - `contractionFactor = 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)

  Create a ResizableArray with the specified initial capacity and expansion factor. The remaining properties take default values:

  - `expansionMode = MULTIPLICATIVE_MODE`
  - `contractionFactor = 0.5 + expansionFactor`

  Throws IllegalArgumentException if the following conditions are not met:

  - `initialCapacity > 0`
  - `expansionFactor > 1`

Parameters:
  `initialCapacity` - The initial size of the internal storage array
  `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)

  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 > 0`
  - `expansionFactor > 1`
  - `contractionFactor >= expansionFactor`

Parameters:
  `initialCapacity` - The initial size of the internal storage array
  `expansionFactor` - the array will be expanded based on this parameter
  `contractionCriteria` - The contraction Criteria.
Throws:
  `IllegalArgumentException` - if parameters are not valid

### ResizableDoubleArray

    public ResizableDoubleArray(int initialCapacity,
                                float expansionFactor,
                                float contractionCriteria,
                                int expansionMode)

  Create a ResizableArray with the specified properties.

  Throws IllegalArgumentException if the following conditions are not met:

  - `initialCapacity > 0`
  - `expansionFactor > 1`
  - `contractionFactor >= expansionFactor`
  - `expansionMode in {MULTIPLICATIVE_MODE, ADDITIVE_MODE}`

Parameters:
  `initialCapacity` - the initial size of the internal storage array
  `expansionFactor` - the array will be expanded based on this parameter
  `contractionCriteria` - the contraction Criteria
  `expansionMode` - the expansion mode
Throws:
  `IllegalArgumentException` - if parameters are not valid

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` - to be added to end of array

### 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` - the value to be added to the array
  Returns:
    the value which has been discarded or "pushed" out of the array by this rolling insert

### 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
  Throws:
    `IllegalArgumentException` - if the contractionCriteria is less than the expansionCriteria.

### clear

    public void clear()

  Clear the array, reset the size to the initialCapacity and 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:
    `IllegalArgumentException` - if i is greater than numElements.

### 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`

### 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. 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 criteria used to reclaim memory.

### 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.

### getExpansionFactor

    public float getExpansionFactor()

  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.

  Returns:
    the expansion factor of this expandable double array

### getExpansionMode

    public int getExpansionMode()

  The `expansionMode` determines whether the internal storage array grows additively (ADDITIVE_MODE) or multiplicatively (MULTIPLICATIVE_MODE) when it is expanded.

  Returns:
    Returns the expansionMode.

### getInternalLength

    int getInternalLength()

  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.

  Returns:
    the length of the internal storage array.

### 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:
    number of elements

### getValues

    public double[] getValues()

  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 `start()` method). This method should only be used in cases where copying the internal array is not practical. The `getElements()` method should be used in all other cases.

  Returns:
    the internal storage array used by this object

### setContractionCriteria

    public void setContractionCriteria(float contractionCriteria)

  Sets the contraction criteria for this ExpandContractDoubleArray.

  Parameters:
    `contractionCriteria` - contraction criteria

### 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` is less than zero.

### setExpansionFactor

    public void setExpansionFactor(float expansionFactor)

  Sets the expansionFactor. Throws IllegalArgumentException if the the following conditions are not met:
  - `expansionFactor > 1`
  - `contractionFactor >= expansionFactor`

  Parameters:
    `expansionFactor` - the new expansion factor value.
  Throws:
    `IllegalArgumentException` - if expansionFactor is <= 1 or greater than contractionFactor

### setExpansionMode

    public void setExpansionMode(int expansionMode)

  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)

  Sets the initial capacity. Should only be invoked by constructors.

  Parameters:
    `initialCapacity` - of the array
  Throws:
    `IllegalArgumentException` - if `initialCapacity` is not positive.

### 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:
    `IllegalArgumentException` - if `i` is negative.

### start

    public int start()

  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]`

  Returns:
    starting index

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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