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.stat.descriptive;
018    
019    /**
020     * Extends the definition of {@link UnivariateStatistic} with
021     * {@link #increment} and {@link #incrementAll(double[])} methods for adding
022     * values and updating internal state.
023     * <p>
024     * This interface is designed to be used for calculating statistics that can be
025     * computed in one pass through the data without storing the full array of
026     * sample values.</p>
027     *
028     * @version $Revision: 811685 $ $Date: 2009-09-05 19:36:48 +0200 (sam. 05 sept. 2009) $
029     */
030    public interface StorelessUnivariateStatistic extends UnivariateStatistic {
031    
032        /**
033         * Updates the internal state of the statistic to reflect the addition of the new value.
034         * @param d  the new value.
035         */
036        void increment(double d);
037    
038        /**
039         * Updates the internal state of the statistic to reflect addition of
040         * all values in the values array.  Does not clear the statistic first --
041         * i.e., the values are added <strong>incrementally</strong> to the dataset.
042         *
043         * @param values  array holding the new values to add
044         * @throws IllegalArgumentException if the array is null
045         */
046        void incrementAll(double[] values);
047    
048        /**
049         * Updates the internal state of the statistic to reflect addition of
050         * the values in the designated portion of the values array.  Does not
051         * clear the statistic first -- i.e., the values are added
052         * <strong>incrementally</strong> to the dataset.
053         *
054         * @param values  array holding the new values to add
055         * @param start  the array index of the first value to add
056         * @param length  the number of elements to add
057         * @throws IllegalArgumentException if the array is null or the index
058         */
059        void incrementAll(double[] values, int start, int length);
060    
061        /**
062         * Returns the current value of the Statistic.
063         * @return value of the statistic, <code>Double.NaN</code> if it
064         * has been cleared or just instantiated.
065         */
066        double getResult();
067    
068        /**
069         * Returns the number of values that have been added.
070         * @return the number of values.
071         */
072        long getN();
073    
074        /**
075         * Clears the internal state of the Statistic
076         */
077        void clear();
078    
079        /**
080         * Returns a copy of the statistic with the same internal state.
081         *
082         * @return a copy of the statistic
083         */
084        StorelessUnivariateStatistic copy();
085    
086    }