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 }