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