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  import org.apache.commons.math.util.MathUtils;
20  import java.io.Serializable;
21  
22  /**
23   *
24   * Abstract implementation of the {@link StorelessUnivariateStatistic} interface.
25   * <p>
26   * Provides default <code>evaluate()</code> and <code>incrementAll(double[])<code>
27   * implementations.</p>
28   * <p>
29   * <strong>Note that these implementations are not synchronized.</strong></p>
30   *
31   * @version $Revision: 617953 $ $Date: 2008-02-02 22:54:00 -0700 (Sat, 02 Feb 2008) $
32   */
33  public abstract class AbstractStorelessUnivariateStatistic
34      extends AbstractUnivariateStatistic
35      implements StorelessUnivariateStatistic, Serializable {
36  
37      /** Serialization UID */
38      private static final long serialVersionUID = -44915725420072521L;
39      
40      /**
41       * This default implementation calls {@link #clear}, then invokes 
42       * {@link #increment} in a loop over the the input array, and then uses 
43       * {@link #getResult} to compute the return value.  
44       * <p>
45       * Note that this implementation changes the internal state of the
46       * statistic.  Its side effects are the same as invoking {@link #clear} and
47       * then {@link #incrementAll(double[])}.</p>
48       * <p>
49       * Implementations may override this method with a more efficient and
50       * possibly more accurate implementation that works directly with the
51       * input array.</p>
52       * <p>
53       * If the array is null, an IllegalArgumentException is thrown.</p>
54       * 
55       * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[])
56       */
57      public double evaluate(final double[] values) {
58          if (values == null) {
59              throw new IllegalArgumentException("input value array is null");
60          }
61          return evaluate(values, 0, values.length);
62      }
63      
64      /**
65       * This default implementation calls {@link #clear}, then invokes 
66       * {@link #increment} in a loop over the specified portion of the input 
67       * array, and then uses {@link #getResult} to compute the return value.  
68       * <p>
69       * Note that this implementation changes the internal state of the
70       * statistic.  Its side effects are the same as invoking {@link #clear} and
71       * then {@link #incrementAll(double[], int, int)}.</p>
72       * <p>
73       * Implementations may override this method with a more efficient and
74       * possibly more accurate implementation that works directly with the
75       * input array.</p>
76       * <p>
77       * If the array is null or the index parameters are not valid, an 
78       * IllegalArgumentException is thrown.</p>
79       * 
80       * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[], int, int)
81       */
82      public double evaluate(final double[] values, final int begin, final int length) {
83          if (test(values, begin, length)) {
84              clear();
85              incrementAll(values, begin, length);
86          }
87          return getResult();
88      }
89  
90      /**
91       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear()
92       */
93      public abstract void clear();
94  
95      /**
96       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult()
97       */
98      public abstract double getResult();
99  
100     /**
101      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
102      */
103     public abstract void increment(final double d);
104     
105     /**
106      * This default implementation just calls {@link #increment} in a loop over
107      * the input array.   
108      * <p>
109      * Throws IllegalArgumentException if the input values array is null.</p>
110      * 
111      * @param values values to add
112      * @throws IllegalArgumentException if values is null
113      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[])
114      */
115     public void incrementAll(double[] values) {
116         if (values == null) {
117             throw new IllegalArgumentException("input values array is null");
118         }
119         incrementAll(values, 0, values.length);
120     } 
121    
122     /**
123      * This default implementation just calls {@link #increment} in a loop over
124      * the specified portion of the input array.
125      * <p>
126      * Throws IllegalArgumentException if the input values array is null.</p>
127      * 
128      * @param values  array holding values to add
129      * @param begin   index of the first array element to add
130      * @param length  number of array elements to add
131      * @throws IllegalArgumentException if values is null
132      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[], int, int)
133      */
134     public void incrementAll(double[] values, int begin, int length) {
135         if (test(values, begin, length)) {
136             int k = begin + length;
137             for (int i = begin; i < k; i++) {
138                 increment(values[i]);
139             }   
140         }
141     }
142     
143     /**
144      * Returns true iff <code>object</code> is an 
145      * <code>AbstractStorelessUnivariateStatistic</code> returning the same
146      * values as this for <code>getResult()</code> and <code>getN()</code>
147      * @param object object to test equality against.
148      * @return true if object returns the same value as this
149      */
150     public boolean equals(Object object) {
151         if (object == this ) {
152             return true;
153         }
154        if (object instanceof AbstractStorelessUnivariateStatistic == false) {
155             return false;
156         }
157         AbstractStorelessUnivariateStatistic stat = (AbstractStorelessUnivariateStatistic) object;
158         return (MathUtils.equals(stat.getResult(), this.getResult()) && 
159                 MathUtils.equals(stat.getN(), this.getN()));
160     }
161     
162     /**
163      * Returns hash code based on getResult() and getN()
164      * 
165      * @return hash code
166      */
167     public int hashCode() {
168         return 31* (31 + MathUtils.hash(getResult())) + MathUtils.hash(getN());
169     }
170 
171 }