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