View Javadoc
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.statistics.descriptive;
18  
19  import java.math.BigInteger;
20  
21  /**
22   * Returns the sum of the available values.
23   *
24   * <ul>
25   *   <li>The result is zero if no values are added.
26   * </ul>
27   *
28   * <p>This class uses an exact integer sum. The exact sum is
29   * returned using {@link #getAsBigInteger()}. Methods that return {@code int} or
30   * {@code long} primitives will raise an exception if the result overflows.
31   *
32   * <p>Note that the implementation does not use {@code BigInteger} arithmetic; for
33   * performance the sum is computed using primitives to create a signed 128-bit integer.
34   * Support is provided for at least 2<sup>63</sup> observations.
35   *
36   * <p>This class is designed to work with (though does not require)
37   * {@linkplain java.util.stream streams}.
38   *
39   * <p><strong>This implementation is not thread safe.</strong>
40   * If multiple threads access an instance of this class concurrently,
41   * and at least one of the threads invokes the {@link java.util.function.LongConsumer#accept(long) accept} or
42   * {@link StatisticAccumulator#combine(StatisticResult) combine} method, it must be synchronized externally.
43   *
44   * <p>However, it is safe to use {@link java.util.function.LongConsumer#accept(long) accept}
45   * and {@link StatisticAccumulator#combine(StatisticResult) combine}
46   * as {@code accumulator} and {@code combiner} functions of
47   * {@link java.util.stream.Collector Collector} on a parallel stream,
48   * because the parallel implementation of {@link java.util.stream.Stream#collect Stream.collect()}
49   * provides the necessary partitioning, isolation, and merging of results for
50   * safe and efficient parallel execution.
51   *
52   * @since 1.1
53   */
54  public final class LongSum implements LongStatistic, StatisticAccumulator<LongSum> {
55      /** Sum of the values. */
56      private final Int128 sum;
57  
58      /**
59       * Create an instance.
60       */
61      private LongSum() {
62          this(Int128.create());
63      }
64  
65      /**
66       * Create an instance.
67       *
68       * @param sum Sum of the values.
69       */
70      private LongSum(Int128 sum) {
71          this.sum = sum;
72      }
73  
74      /**
75       * Creates an instance.
76       *
77       * <p>The initial result is zero.
78       *
79       * @return {@code LongSum} instance.
80       */
81      public static LongSum create() {
82          return new LongSum();
83      }
84  
85      /**
86       * Returns an instance populated using the input {@code values}.
87       *
88       * <p>When the input is an empty array, the result is zero.
89       *
90       * @param values Values.
91       * @return {@code LongSum} instance.
92       */
93      public static LongSum of(long... values) {
94          final Int128 s = Int128.create();
95          for (final long x : values) {
96              s.add(x);
97          }
98          return new LongSum(s);
99      }
100 
101     /**
102      * Returns an instance populated using the specified range of {@code values}.
103      *
104      * <p>When the range is empty, the result is zero.
105      *
106      * @param values Values.
107      * @param from Inclusive start of the range.
108      * @param to Exclusive end of the range.
109      * @return {@code LongSum} instance.
110      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
111      * @since 1.2
112      */
113     public static LongSum ofRange(long[] values, int from, int to) {
114         Statistics.checkFromToIndex(from, to, values.length);
115         return createFromRange(values, from, to);
116     }
117 
118     /**
119      * Create an instance using the specified range of {@code values}.
120      *
121      * <p>Warning: No range checks are performed.
122      *
123      * @param values Values.
124      * @param from Inclusive start of the range.
125      * @param to Exclusive end of the range.
126      * @return {@code LongSum} instance.
127      */
128     static LongSum createFromRange(long[] values, int from, int to) {
129         final Int128 s = Int128.create();
130         for (int i = from; i < to; i++) {
131             s.add(values[i]);
132         }
133         return new LongSum(s);
134     }
135 
136     /**
137      * Gets the sum.
138      *
139      * <p>This is package private for use in {@link LongStatistics}.
140      *
141      * @return the sum
142      */
143     Int128 getSum() {
144         return sum;
145     }
146 
147     /**
148      * Updates the state of the statistic to reflect the addition of {@code value}.
149      *
150      * @param value Value.
151      */
152     @Override
153     public void accept(long value) {
154         sum.add(value);
155     }
156 
157     /**
158      * Gets the sum of all input values.
159      *
160      * <p>When no values have been added, the result is zero.
161      *
162      * <p>Warning: This will raise an {@link ArithmeticException}
163      * if the result is not within the range {@code [-2^31, 2^31)}.
164      *
165      * @return sum of all values.
166      * @throws ArithmeticException if the {@code result} overflows an {@code int}
167      * @see #getAsBigInteger()
168      */
169     @Override
170     public int getAsInt() {
171         return sum.toIntExact();
172     }
173 
174     /**
175      * Gets the sum of all input values.
176      *
177      * <p>When no values have been added, the result is zero.
178      *
179      * <p>Warning: This will raise an {@link ArithmeticException}
180      * if the result is not within the range {@code [-2^63, 2^63)}.
181      *
182      * @return sum of all values.
183      * @throws ArithmeticException if the {@code result} overflows a {@code long}
184      * @see #getAsBigInteger()
185      */
186     @Override
187     public long getAsLong() {
188         return sum.toLongExact();
189     }
190 
191     /**
192      * Gets the sum of all input values.
193      *
194      * <p>When no values have been added, the result is zero.
195      *
196      * <p>Note that this conversion can lose information about the precision of the
197      * {@code BigInteger} value.
198      *
199      * @return sum of all values.
200      * @see #getAsBigInteger()
201      */
202     @Override
203     public double getAsDouble() {
204         return sum.toDouble();
205     }
206 
207     /**
208      * Gets the sum of all input values.
209      *
210      * <p>When no values have been added, the result is zero.
211      *
212      * @return sum of all values.
213      */
214     @Override
215     public BigInteger getAsBigInteger() {
216         return sum.toBigInteger();
217     }
218 
219     @Override
220     public LongSum combine(LongSum other) {
221         sum.add(other.sum);
222         return this;
223     }
224 }