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 }