1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.math.util;
17
18
19 /**
20 * Provides a standard interface for double arrays. Allows different
21 * array implementations to support various storage mechanisms
22 * such as automatic expansion, contraction, and array "rolling".
23 *
24 * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
25 */
26 public interface DoubleArray {
27
28 /**
29 * Returns the number of elements currently in the array. Please note
30 * that this may be different from the length of the internal storage array.
31 *
32 * @return number of elements
33 */
34 int getNumElements();
35
36 /**
37 * Returns the element at the specified index. Note that if an
38 * out of bounds index is supplied a ArrayIndexOutOfBoundsException
39 * will be thrown.
40 *
41 * @param index index to fetch a value from
42 * @return value stored at the specified index
43 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is less than
44 * zero or is greater than <code>getNumElements() - 1</code>.
45 */
46 double getElement(int index);
47
48 /**
49 * Sets the element at the specified index. If the specified index is greater than
50 * <code>getNumElements() - 1</code>, the <code>numElements</code> property
51 * is increased to <code>index +1</code> and additional storage is allocated
52 * (if necessary) for the new element and all (uninitialized) elements
53 * between the new element and the previous end of the array).
54 *
55 * @param index index to store a value in
56 * @param value value to store at the specified index
57 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is less than
58 * zero.
59 */
60 void setElement(int index, double value);
61
62 /**
63 * Adds an element to the end of this expandable array
64 *
65 * @param value to be added to end of array
66 */
67 void addElement(double value);
68
69 /**
70 * <p>
71 * Adds an element to the end of the array and removes the first
72 * element in the array. Returns the discarded first element.
73 * The effect is similar to a push operation in a FIFO queue.
74 * </p>
75 * <p>
76 * Example: If the array contains the elements 1, 2, 3, 4 (in that order)
77 * and addElementRolling(5) is invoked, the result is an array containing
78 * the entries 2, 3, 4, 5 and the value returned is 1.
79 * </p>
80 *
81 * @param value the value to be added to the array
82 * @return the value which has been discarded or "pushed" out of the array
83 * by this rolling insert
84 */
85 double addElementRolling(double value);
86
87 /**
88 * Returns a double[] array containing the elements of this
89 * <code>DoubleArray</code>. If the underlying implementation is
90 * array-based, this method should always return a copy, rather than a
91 * reference to the underlying array so that changes made to the returned
92 * array have no effect on the <code>DoubleArray.</code>
93 *
94 * @return all elements added to the array
95 */
96 double[] getElements();
97
98 /**
99 * Clear the double array
100 */
101 void clear();
102
103 }