View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.math.stat.descriptive;
18  
19  /**
20   * Extends the definition of {@link UnivariateStatistic} with 
21   * {@link #increment} and {@link #incrementAll(double[])} methods for adding
22   * values and updating internal state.  
23   * <p>
24   * This interface is designed to be used for calculating statistics that can be
25   * computed in one pass through the data without storing the full array of
26   * sample values.</p>
27   *
28   * @version $Revision: 720030 $ $Date: 2008-11-23 13:47:50 -0500 (Sun, 23 Nov 2008) $
29   */
30  public interface StorelessUnivariateStatistic extends UnivariateStatistic {
31  
32      /**
33       * Updates the internal state of the statistic to reflect the addition of the new value.
34       * @param d  the new value.
35       */
36      void increment(double d);
37      
38      /**
39       * Updates the internal state of the statistic to reflect addition of
40       * all values in the values array.  Does not clear the statistic first --
41       * i.e., the values are added <strong>incrementally</strong> to the dataset.
42       * 
43       * @param values  array holding the new values to add
44       * @throws IllegalArgumentException if the array is null
45       */
46      void incrementAll(double[] values);
47      
48      /**
49       * Updates the internal state of the statistic to reflect addition of
50       * the values in the designated portion of the values array.  Does not
51       * clear the statistic first -- i.e., the values are added 
52       * <strong>incrementally</strong> to the dataset.
53       * 
54       * @param values  array holding the new values to add
55       * @param start  the array index of the first value to add
56       * @param length  the number of elements to add
57       * @throws IllegalArgumentException if the array is null or the index
58       */
59      void incrementAll(double[] values, int start, int length);
60  
61      /**
62       * Returns the current value of the Statistic.
63       * @return value of the statistic, <code>Double.NaN</code> if it
64       * has been cleared or just instantiated.
65       */
66      double getResult();
67  
68      /**
69       * Returns the number of values that have been added.
70       * @return the number of values.
71       */
72      long getN();
73  
74      /**
75       * Clears the internal state of the Statistic
76       */
77      void clear();
78      
79      /**
80       * Returns a copy of the statistic with the same internal state.
81       * 
82       * @return a copy of the statistic
83       */
84      StorelessUnivariateStatistic copy();
85  
86  }