    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    }