    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.exception.util.LocalizedFormats;
    020    import org.apache.commons.math.exception.NullArgumentException;
    021    import org.apache.commons.math.util.MathUtils;
    022
    023    /**
    024     *
    025     * Abstract implementation of the {@link StorelessUnivariateStatistic} interface.
    026     * <p>
    027     * Provides default <code>evaluate()</code> and <code>incrementAll(double[])<code>
    028     * implementations.</p>
    029     * <p>
    030     * <strong>Note that these implementations are not synchronized.</strong></p>
    031     *
    032     * @version $Revision: 983921 $ $Date: 2010-08-10 12:46:06 +0200 (mar. 10 ao??t 2010) $
    033     */
    034    public abstract class AbstractStorelessUnivariateStatistic
    035        extends AbstractUnivariateStatistic
    036        implements StorelessUnivariateStatistic {
    037
    038        /**
    039         * This default implementation calls {@link #clear}, then invokes
    040         * {@link #increment} in a loop over the the input array, and then uses
    041         * {@link #getResult} to compute the return value.
    042         * <p>
    043         * Note that this implementation changes the internal state of the
    044         * statistic.  Its side effects are the same as invoking {@link #clear} and
    045         * then {@link #incrementAll(double[])}.</p>
    046         * <p>
    047         * Implementations may override this method with a more efficient and
    048         * possibly more accurate implementation that works directly with the
    049         * input array.</p>
    050         * <p>
    051         * If the array is null, an IllegalArgumentException is thrown.</p>
    052         * @param values input array
    053         * @return the value of the statistic applied to the input array
    054         * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[])
    055         */
    056        @Override
    057        public double evaluate(final double[] values) {
    058            if (values == null) {
    059                throw new NullArgumentException(LocalizedFormats.INPUT_ARRAY);
    060            }
    061            return evaluate(values, 0, values.length);
    062        }
    063
    064        /**
    065         * This default implementation calls {@link #clear}, then invokes
    066         * {@link #increment} in a loop over the specified portion of the input
    067         * array, and then uses {@link #getResult} to compute the return value.
    068         * <p>
    069         * Note that this implementation changes the internal state of the
    070         * statistic.  Its side effects are the same as invoking {@link #clear} and
    071         * then {@link #incrementAll(double[], int, int)}.</p>
    072         * <p>
    073         * Implementations may override this method with a more efficient and
    074         * possibly more accurate implementation that works directly with the
    075         * input array.</p>
    076         * <p>
    077         * If the array is null or the index parameters are not valid, an
    078         * IllegalArgumentException is thrown.</p>
    079         * @param values the input array
    080         * @param begin the index of the first element to include
    081         * @param length the number of elements to include
    082         * @return the value of the statistic applied to the included array entries
    083         * @see org.apache.commons.math.stat.descriptive.UnivariateStatistic#evaluate(double[], int, int)
    084         */
    085        @Override
    086        public double evaluate(final double[] values, final int begin, final int length) {
    087            if (test(values, begin, length)) {
    088                clear();
    089                incrementAll(values, begin, length);
    090            }
    091            return getResult();
    092        }
    093
    094        /**
    095         * {@inheritDoc}
    096         */
    097        @Override
    098        public abstract StorelessUnivariateStatistic copy();
    099
    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    }