View Javadoc

1   /*
2    * Copyright 2003-2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.stat.descriptive;
17  
18  import org.apache.commons.math.util.MathUtils;
19  import java.io.Serializable;
20  
21  /**
22   *
23   * Abstract implementation of the {@link StorelessUnivariateStatistic} interface.
24   * <p>
25   * Provides default <code>evaluate()</code> and <code>incrementAll(double[])<code>
26   * implementations. 
27   * <p>
28   * <strong>Note that these implementations are not synchronized.</strong>
29   *
30   * @version $Revision: 355770 $ $Date: 2005-12-10 12:48:57 -0700 (Sat, 10 Dec 2005) $
31   */
32  public abstract class AbstractStorelessUnivariateStatistic
33      extends AbstractUnivariateStatistic
34      implements StorelessUnivariateStatistic, Serializable {
35  
36      /** Serialization UID */
37      private static final long serialVersionUID = -44915725420072521L;
38      
39      /**
40       * This default implementation calls {@link #clear}, then invokes 
41       * {@link #increment} in a loop over the the input array, and then uses 
42       * {@link #getResult} to compute the return value.  
43       * <p>
44       * Note that this implementation changes the internal state of the
45       * statistic.  Its side effects are the same as invoking {@link #clear} and
46       * then {@link #incrementAll(double[])}.
47       * <p>
48       * Implementations may override this method with a more efficient 
49       * implementation that works directly with the input array.
50       * <p>
51       * If the array is null, an IllegalArgumentException is thrown.
52       * 
53       * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[])
54       */
55      public double evaluate(final double[] values) {
56          if (values == null) {
57              throw new IllegalArgumentException("input value array is null");
58          }
59          return evaluate(values, 0, values.length);
60      }
61      
62      /**
63       * This default implementation calls {@link #clear}, then invokes 
64       * {@link #increment} in a loop over the specified portion of the input 
65       * array, and then uses {@link #getResult} to compute the return value.  
66       * <p>
67       * Note that this implementation changes the internal state of the
68       * statistic.  Its side effects are the same as invoking {@link #clear} and
69       * then {@link #incrementAll(double[], int, int)}.
70       * <p>
71       * Implementations may override this method with a more efficient 
72       * implementation that works directly with the input array.
73       * <p>
74       * If the array is null or the index parameters are not valid, an 
75       * IllegalArgumentException is thrown.
76       * 
77       * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[], int, int)
78       */
79      public double evaluate(final double[] values, final int begin, final int length) {
80          if (test(values, begin, length)) {
81              clear();
82              incrementAll(values, begin, length);
83          }
84          return getResult();
85      }
86  
87      /**
88       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear()
89       */
90      public abstract void clear();
91  
92      /**
93       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult()
94       */
95      public abstract double getResult();
96  
97      /**
98       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
99       */
100     public abstract void increment(final double d);
101     
102     /**
103      * This default implementation just calls {@link #increment} in a loop over
104      * the input array.   
105      * <p>
106      * Throws IllegalArgumentException if the input values array is null.
107      * 
108      * @param values values to add
109      * @throws IllegalArgumentException if values is null
110      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[])
111      */
112     public void incrementAll(double[] values) {
113         if (values == null) {
114             throw new IllegalArgumentException("input values array is null");
115         }
116         incrementAll(values, 0, values.length);
117     } 
118    
119     /**
120      * This default implementation just calls {@link #increment} in a loop over
121      * the specified portion of the input array.
122      * <p>
123      * Throws IllegalArgumentException if the input values array is null.
124      * 
125      * @param values  array holding values to add
126      * @param begin   index of the first array element to add
127      * @param length  number of array elements to add
128      * @throws IllegalArgumentException if values is null
129      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[], int, int)
130      */
131     public void incrementAll(double[] values, int begin, int length) {
132         if (test(values, begin, length)) {
133             int k = begin + length;
134             for (int i = begin; i < k; i++) {
135                 increment(values[i]);
136             }   
137         }
138     }
139     
140     /**
141      * Returns true iff <code>object</code> is an 
142      * <code>AbstractStorelessUnivariateStatistic</code> returning the same
143      * values as this for <code>getResult()</code> and <code>getN()</code>
144      * @param object object to test equality against.
145      * @return true if object returns the same value as this
146      */
147     public boolean equals(Object object) {
148         if (object == this ) {
149             return true;
150         }
151        if (object instanceof AbstractStorelessUnivariateStatistic == false) {
152             return false;
153         }
154         AbstractStorelessUnivariateStatistic stat = (AbstractStorelessUnivariateStatistic) object;
155         return (MathUtils.equals(stat.getResult(), this.getResult()) && 
156                 MathUtils.equals(stat.getN(), this.getN()));
157     }
158     
159     /**
160      * Returns hash code based on getResult() and getN()
161      * 
162      * @return hash code
163      */
164     public int hashCode() {
165         return 31* (31 + MathUtils.hash(getResult())) + MathUtils.hash(getN());
166     }
167 
168 }