1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.math4.legacy.stat.descriptive;
18
19
20 /**
21 * Provides a standard interface for double arrays. Allows different
22 * array implementations to support various storage mechanisms
23 * such as automatic expansion, contraction, and array "rolling".
24 *
25 */
26 interface DoubleArray { // Not in public API.
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 * Adds elements to the end of this expandable array.
71 *
72 * @param values to be added to end of array
73 */
74 void addElements(double[] values);
75
76 /**
77 * <p>
78 * Adds an element to the end of the array and removes the first
79 * element in the array. Returns the discarded first element.
80 * The effect is similar to a push operation in a FIFO queue.
81 * </p>
82 * <p>
83 * Example: If the array contains the elements 1, 2, 3, 4 (in that order)
84 * and addElementRolling(5) is invoked, the result is an array containing
85 * the entries 2, 3, 4, 5 and the value returned is 1.
86 * </p>
87 *
88 * @param value the value to be added to the array
89 * @return the value which has been discarded or "pushed" out of the array
90 * by this rolling insert
91 */
92 double addElementRolling(double value);
93
94 /**
95 * Returns a double[] array containing the elements of this
96 * <code>DoubleArray</code>. If the underlying implementation is
97 * array-based, this method should always return a copy, rather than a
98 * reference to the underlying array so that changes made to the returned
99 * array have no effect on the <code>DoubleArray.</code>
100 *
101 * @return all elements added to the array
102 */
103 double[] getElements();
104
105 /**
106 * Clear the double array.
107 */
108 void clear();
109 }