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 */
17package org.apache.commons.math.stat.descriptive;
18
19import org.apache.commons.math.exception.util.LocalizedFormats;
20import org.apache.commons.math.exception.NullArgumentException;
21import org.apache.commons.math.util.MathUtils;
22
23/**
24 *
25 * Abstract implementation of the {@link StorelessUnivariateStatistic} interface.
26 * <p>
27 * Provides default <code>evaluate()</code> and <code>incrementAll(double[])<code>
28 * implementations.</p>
29 * <p>
30 * <strong>Note that these implementations are not synchronized.</strong></p>
31 *
32 * @version $Revision: 983921 $ $Date: 2010-08-10 12:46:06 +0200 (mar. 10 août 2010) $
33 */
34public abstract class AbstractStorelessUnivariateStatistic
35    extends AbstractUnivariateStatistic
36    implements StorelessUnivariateStatistic {
37
38    /**
39     * This default implementation calls {@link #clear}, then invokes
40     * {@link #increment} in a loop over the the input array, and then uses
41     * {@link #getResult} to compute the return value.
42     * <p>
43     * Note that this implementation changes the internal state of the
44     * statistic.  Its side effects are the same as invoking {@link #clear} and
45     * then {@link #incrementAll(double[])}.</p>
46     * <p>
47     * Implementations may override this method with a more efficient and
48     * possibly more accurate implementation that works directly with the
49     * input array.</p>
50     * <p>
51     * If the array is null, an IllegalArgumentException is thrown.</p>
52     * @param values input array
53     * @return the value of the statistic applied to the input array
54     * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[])
55     */
56    @Override
57    public double evaluate(final double[] values) {
58        if (values == null) {
59            throw new NullArgumentException(LocalizedFormats.INPUT_ARRAY);
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     * @param values the input array
80     * @param begin the index of the first element to include
81     * @param length the number of elements to include
82     * @return the value of the statistic applied to the included array entries
83     * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[], int, int)
84     */
85    @Override
86    public double evaluate(final double[] values, final int begin, final int length) {
87        if (test(values, begin, length)) {
88            clear();
89            incrementAll(values, begin, length);
90        }
91        return getResult();
92    }
93
94    /**
95     * {@inheritDoc}
96     */
97    @Override
98    public abstract StorelessUnivariateStatistic copy();
99
100    /**
101     * {@inheritDoc}
102     */
103    public abstract void clear();
104
105    /**
106     * {@inheritDoc}
107     */
108    public abstract double getResult();
109
110    /**
111     * {@inheritDoc}
112     */
113    public abstract void increment(final double d);
114
115    /**
116     * This default implementation just calls {@link #increment} in a loop over
117     * the input array.
118     * <p>
119     * Throws IllegalArgumentException if the input values array is null.</p>
120     *
121     * @param values values to add
122     * @throws IllegalArgumentException if values is null
123     * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[])
124     */
125    public void incrementAll(double[] values) {
126        if (values == null) {
127            throw new NullArgumentException(LocalizedFormats.INPUT_ARRAY);
128        }
129        incrementAll(values, 0, values.length);
130    }
131
132    /**
133     * This default implementation just calls {@link #increment} in a loop over
134     * the specified portion of the input array.
135     * <p>
136     * Throws IllegalArgumentException if the input values array is null.</p>
137     *
138     * @param values  array holding values to add
139     * @param begin   index of the first array element to add
140     * @param length  number of array elements to add
141     * @throws IllegalArgumentException if values is null
142     * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[], int, int)
143     */
144    public void incrementAll(double[] values, int begin, int length) {
145        if (test(values, begin, length)) {
146            int k = begin + length;
147            for (int i = begin; i < k; i++) {
148                increment(values[i]);
149            }
150        }
151    }
152
153    /**
154     * Returns true iff <code>object</code> is an
155     * <code>AbstractStorelessUnivariateStatistic</code> returning the same
156     * values as this for <code>getResult()</code> and <code>getN()</code>
157     * @param object object to test equality against.
158     * @return true if object returns the same value as this
159     */
160    @Override
161    public boolean equals(Object object) {
162        if (object == this ) {
163            return true;
164        }
165       if (object instanceof AbstractStorelessUnivariateStatistic == false) {
166            return false;
167        }
168        AbstractStorelessUnivariateStatistic stat = (AbstractStorelessUnivariateStatistic) object;
169        return MathUtils.equalsIncludingNaN(stat.getResult(), this.getResult()) &&
170               MathUtils.equalsIncludingNaN(stat.getN(), this.getN());
171    }
172
173    /**
174     * Returns hash code based on getResult() and getN()
175     *
176     * @return hash code
177     */
178    @Override
179    public int hashCode() {
180        return 31* (31 + MathUtils.hash(getResult())) + MathUtils.hash(getN());
181    }
182
183}
184