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