    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    }