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    import org.apache.commons.math.MathRuntimeException;
020    import org.apache.commons.math.util.MathUtils;
021    
022    /**
023     *
024     * Abstract implementation of the {@link StorelessUnivariateStatistic} interface.
025     * <p>
026     * Provides default <code>evaluate()</code> and <code>incrementAll(double[])<code>
027     * implementations.</p>
028     * <p>
029     * <strong>Note that these implementations are not synchronized.</strong></p>
030     *
031     * @version $Revision: 780637 $ $Date: 2009-06-01 08:48:32 -0400 (Mon, 01 Jun 2009) $
032     */
033    public abstract class AbstractStorelessUnivariateStatistic
034        extends AbstractUnivariateStatistic
035        implements StorelessUnivariateStatistic {
036        
037        /**
038         * This default implementation calls {@link #clear}, then invokes 
039         * {@link #increment} in a loop over the the input array, and then uses 
040         * {@link #getResult} to compute the return value.  
041         * <p>
042         * Note that this implementation changes the internal state of the
043         * statistic.  Its side effects are the same as invoking {@link #clear} and
044         * then {@link #incrementAll(double[])}.</p>
045         * <p>
046         * Implementations may override this method with a more efficient and
047         * possibly more accurate implementation that works directly with the
048         * input array.</p>
049         * <p>
050         * If the array is null, an IllegalArgumentException is thrown.</p>
051         * @param values input array
052         * @return the value of the statistic applied to the input array
053         * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[])
054         */
055        @Override
056        public double evaluate(final double[] values) {
057            if (values == null) {
058                throw MathRuntimeException.createIllegalArgumentException("input values array is null");
059            }
060            return evaluate(values, 0, values.length);
061        }
062        
063        /**
064         * This default implementation calls {@link #clear}, then invokes 
065         * {@link #increment} in a loop over the specified portion of the input 
066         * array, and then uses {@link #getResult} to compute the return value.  
067         * <p>
068         * Note that this implementation changes the internal state of the
069         * statistic.  Its side effects are the same as invoking {@link #clear} and
070         * then {@link #incrementAll(double[], int, int)}.</p>
071         * <p>
072         * Implementations may override this method with a more efficient and
073         * possibly more accurate implementation that works directly with the
074         * input array.</p>
075         * <p>
076         * If the array is null or the index parameters are not valid, an 
077         * IllegalArgumentException is thrown.</p>
078         * @param values the input array
079         * @param begin the index of the first element to include
080         * @param length the number of elements to include
081         * @return the value of the statistic applied to the included array entries
082         * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[], int, int)
083         */
084        @Override
085        public double evaluate(final double[] values, final int begin, final int length) {
086            if (test(values, begin, length)) {
087                clear();
088                incrementAll(values, begin, length);
089            }
090            return getResult();
091        }
092    
093        /**
094         * {@inheritDoc}
095         */
096        @Override
097        public abstract StorelessUnivariateStatistic copy();
098    
099        /**
100         * {@inheritDoc}
101         */
102        public abstract void clear();
103    
104        /**
105         * {@inheritDoc}
106         */
107        public abstract double getResult();
108    
109        /**
110         * {@inheritDoc}
111         */
112        public abstract void increment(final double d);
113        
114        /**
115         * This default implementation just calls {@link #increment} in a loop over
116         * the input array.   
117         * <p>
118         * Throws IllegalArgumentException if the input values array is null.</p>
119         * 
120         * @param values values to add
121         * @throws IllegalArgumentException if values is null
122         * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[])
123         */
124        public void incrementAll(double[] values) {
125            if (values == null) {
126                throw MathRuntimeException.createIllegalArgumentException("input values array is null");
127            }
128            incrementAll(values, 0, values.length);
129        } 
130       
131        /**
132         * This default implementation just calls {@link #increment} in a loop over
133         * the specified portion of the input array.
134         * <p>
135         * Throws IllegalArgumentException if the input values array is null.</p>
136         * 
137         * @param values  array holding values to add
138         * @param begin   index of the first array element to add
139         * @param length  number of array elements to add
140         * @throws IllegalArgumentException if values is null
141         * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#incrementAll(double[], int, int)
142         */
143        public void incrementAll(double[] values, int begin, int length) {
144            if (test(values, begin, length)) {
145                int k = begin + length;
146                for (int i = begin; i < k; i++) {
147                    increment(values[i]);
148                }   
149            }
150        }
151        
152        /**
153         * Returns true iff <code>object</code> is an 
154         * <code>AbstractStorelessUnivariateStatistic</code> returning the same
155         * values as this for <code>getResult()</code> and <code>getN()</code>
156         * @param object object to test equality against.
157         * @return true if object returns the same value as this
158         */
159        @Override
160        public boolean equals(Object object) {
161            if (object == this ) {
162                return true;
163            }
164           if (object instanceof AbstractStorelessUnivariateStatistic == false) {
165                return false;
166            }
167            AbstractStorelessUnivariateStatistic stat = (AbstractStorelessUnivariateStatistic) object;
168            return (MathUtils.equals(stat.getResult(), this.getResult()) && 
169                    MathUtils.equals(stat.getN(), this.getN()));
170        }
171        
172        /**
173         * Returns hash code based on getResult() and getN()
174         * 
175         * @return hash code
176         */
177        @Override
178        public int hashCode() {
179            return 31* (31 + MathUtils.hash(getResult())) + MathUtils.hash(getN());
180        }
181    
182    }