001: /*
002: * Copyright 2003-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.math.util;
017:
018: /**
019: * Provides a standard interface for double arrays. Allows different
020: * array implementations to support various storage mechanisms
021: * such as automatic expansion, contraction, and array "rolling".
022: *
023: * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
024: */
025: public interface DoubleArray {
026:
027: /**
028: * Returns the number of elements currently in the array. Please note
029: * that this may be different from the length of the internal storage array.
030: *
031: * @return number of elements
032: */
033: int getNumElements();
034:
035: /**
036: * Returns the element at the specified index. Note that if an
037: * out of bounds index is supplied a ArrayIndexOutOfBoundsException
038: * will be thrown.
039: *
040: * @param index index to fetch a value from
041: * @return value stored at the specified index
042: * @throws ArrayIndexOutOfBoundsException if <code>index</code> is less than
043: * zero or is greater than <code>getNumElements() - 1</code>.
044: */
045: double getElement(int index);
046:
047: /**
048: * Sets the element at the specified index. If the specified index is greater than
049: * <code>getNumElements() - 1</code>, the <code>numElements</code> property
050: * is increased to <code>index +1</code> and additional storage is allocated
051: * (if necessary) for the new element and all (uninitialized) elements
052: * between the new element and the previous end of the array).
053: *
054: * @param index index to store a value in
055: * @param value value to store at the specified index
056: * @throws ArrayIndexOutOfBoundsException if <code>index</code> is less than
057: * zero.
058: */
059: void setElement(int index, double value);
060:
061: /**
062: * Adds an element to the end of this expandable array
063: *
064: * @param value to be added to end of array
065: */
066: void addElement(double value);
067:
068: /**
069: * <p>
070: * Adds an element to the end of the array and removes the first
071: * element in the array. Returns the discarded first element.
072: * The effect is similar to a push operation in a FIFO queue.
073: * </p>
074: * <p>
075: * Example: If the array contains the elements 1, 2, 3, 4 (in that order)
076: * and addElementRolling(5) is invoked, the result is an array containing
077: * the entries 2, 3, 4, 5 and the value returned is 1.
078: * </p>
079: *
080: * @param value the value to be added to the array
081: * @return the value which has been discarded or "pushed" out of the array
082: * by this rolling insert
083: */
084: double addElementRolling(double value);
085:
086: /**
087: * Returns a double[] array containing the elements of this
088: * <code>DoubleArray</code>. If the underlying implementation is
089: * array-based, this method should always return a copy, rather than a
090: * reference to the underlying array so that changes made to the returned
091: * array have no effect on the <code>DoubleArray.</code>
092: *
093: * @return all elements added to the array
094: */
095: double[] getElements();
096:
097: /**
098: * Clear the double array
099: */
100: void clear();
101:
102: }
|