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.summary;
018    
019    import java.io.Serializable;
020    
021    import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
022    
023    
024    /**
025      * Returns the sum of the available values.
026     * <p>
027     * If there are no values in the dataset, or any of the values are
028     * <code>NaN</code>, then <code>NaN</code> is returned.</p>
029     * <p>
030     * <strong>Note that this implementation is not synchronized.</strong> If
031     * multiple threads access an instance of this class concurrently, and at least
032     * one of the threads invokes the <code>increment()</code> or
033     * <code>clear()</code> method, it must be synchronized externally.</p>
034     *
035     * @version $Revision: 917270 $ $Date: 2010-02-28 14:37:53 -0500 (Sun, 28 Feb 2010) $
036     */
037    public class Sum extends AbstractStorelessUnivariateStatistic implements Serializable {
038    
039        /** Serializable version identifier */
040        private static final long serialVersionUID = -8231831954703408316L;
041    
042        /** */
043        private long n;
044    
045        /**
046         * The currently running sum.
047         */
048        private double value;
049    
050        /**
051         * Create a Sum instance
052         */
053        public Sum() {
054            n = 0;
055            value = Double.NaN;
056        }
057    
058        /**
059         * Copy constructor, creates a new {@code Sum} identical
060         * to the {@code original}
061         *
062         * @param original the {@code Sum} instance to copy
063         */
064        public Sum(Sum original) {
065            copy(original, this);
066        }
067    
068        /**
069         * {@inheritDoc}
070         */
071        @Override
072        public void increment(final double d) {
073            if (n == 0) {
074                value = d;
075            } else {
076                value += d;
077            }
078            n++;
079        }
080    
081        /**
082         * {@inheritDoc}
083         */
084        @Override
085        public double getResult() {
086            return value;
087        }
088    
089        /**
090         * {@inheritDoc}
091         */
092        public long getN() {
093            return n;
094        }
095    
096        /**
097         * {@inheritDoc}
098         */
099        @Override
100        public void clear() {
101            value = Double.NaN;
102            n = 0;
103        }
104    
105        /**
106         * The sum of the entries in the specified portion of
107         * the input array, or <code>Double.NaN</code> if the designated subarray
108         * is empty.
109         * <p>
110         * Throws <code>IllegalArgumentException</code> if the array is null.</p>
111         *
112         * @param values the input array
113         * @param begin index of the first array element to include
114         * @param length the number of elements to include
115         * @return the sum of the values or Double.NaN if length = 0
116         * @throws IllegalArgumentException if the array is null or the array index
117         *  parameters are not valid
118         */
119        @Override
120        public double evaluate(final double[] values, final int begin, final int length) {
121            double sum = Double.NaN;
122            if (test(values, begin, length)) {
123                sum = 0.0;
124                for (int i = begin; i < begin + length; i++) {
125                    sum += values[i];
126                }
127            }
128            return sum;
129        }
130    
131        /**
132         * The weighted sum of the entries in the specified portion of
133         * the input array, or <code>Double.NaN</code> if the designated subarray
134         * is empty.
135         * <p>
136         * Throws <code>IllegalArgumentException</code> if any of the following are true:
137         * <ul><li>the values array is null</li>
138         *     <li>the weights array is null</li>
139         *     <li>the weights array does not have the same length as the values array</li>
140         *     <li>the weights array contains one or more infinite values</li>
141         *     <li>the weights array contains one or more NaN values</li>
142         *     <li>the weights array contains negative values</li>
143         *     <li>the start and length arguments do not determine a valid array</li>
144         * </ul></p>
145         * <p>
146         * Uses the formula, <pre>
147         *    weighted sum = &Sigma;(values[i] * weights[i])
148         * </pre></p>
149         *
150         * @param values the input array
151         * @param weights the weights array
152         * @param begin index of the first array element to include
153         * @param length the number of elements to include
154         * @return the sum of the values or Double.NaN if length = 0
155         * @throws IllegalArgumentException if the parameters are not valid
156         * @since 2.1
157         */
158        public double evaluate(final double[] values, final double[] weights,
159                               final int begin, final int length) {
160            double sum = Double.NaN;
161            if (test(values, weights, begin, length)) {
162                sum = 0.0;
163                for (int i = begin; i < begin + length; i++) {
164                    sum += values[i] * weights[i];
165                }
166            }
167            return sum;
168        }
169    
170        /**
171         * The weighted sum of the entries in the the input array.
172         * <p>
173         * Throws <code>IllegalArgumentException</code> if any of the following are true:
174         * <ul><li>the values array is null</li>
175         *     <li>the weights array is null</li>
176         *     <li>the weights array does not have the same length as the values array</li>
177         *     <li>the weights array contains one or more infinite values</li>
178         *     <li>the weights array contains one or more NaN values</li>
179         *     <li>the weights array contains negative values</li>
180         * </ul></p>
181         * <p>
182         * Uses the formula, <pre>
183         *    weighted sum = &Sigma;(values[i] * weights[i])
184         * </pre></p>
185         *
186         * @param values the input array
187         * @param weights the weights array
188         * @return the sum of the values or Double.NaN if length = 0
189         * @throws IllegalArgumentException if the parameters are not valid
190         * @since 2.1
191         */
192        public double evaluate(final double[] values, final double[] weights) {
193            return evaluate(values, weights, 0, values.length);
194        }
195    
196        /**
197         * {@inheritDoc}
198         */
199        @Override
200        public Sum copy() {
201            Sum result = new Sum();
202            copy(this, result);
203            return result;
204        }
205    
206        /**
207         * Copies source to dest.
208         * <p>Neither source nor dest can be null.</p>
209         *
210         * @param source Sum to copy
211         * @param dest Sum to copy to
212         * @throws NullPointerException if either source or dest is null
213         */
214        public static void copy(Sum source, Sum dest) {
215            dest.n = source.n;
216            dest.value = source.value;
217        }
218    
219    }