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 */ 17 package org.apache.commons.math.stat.descriptive; 18 19 import org.apache.commons.math.exception.util.LocalizedFormats; 20 import org.apache.commons.math.exception.NullArgumentException; 21 import 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 */ 34 public 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 evaluate(final double[] values)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 evaluate(final double[] values, final int begin, final int length)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 copy()98 public abstract StorelessUnivariateStatistic copy(); 99 100 /** 101 * {@inheritDoc} 102 */ clear()103 public abstract void clear(); 104 105 /** 106 * {@inheritDoc} 107 */ getResult()108 public abstract double getResult(); 109 110 /** 111 * {@inheritDoc} 112 */ increment(final double d)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 */ incrementAll(double[] values)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 */ incrementAll(double[] values, int begin, int length)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 equals(Object object)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 hashCode()179 public int hashCode() { 180 return 31* (31 + MathUtils.hash(getResult())) + MathUtils.hash(getN()); 181 } 182 183 } 184