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 * Gets the sum.
103 *
104 * <p>This is package private for use in {@link LongStatistics}.
105 *
106 * @return the sum
107 */
108 Int128 getSum() {
109 return sum;
110 }
111
112 /**
113 * Updates the state of the statistic to reflect the addition of {@code value}.
114 *
115 * @param value Value.
116 */
117 @Override
118 public void accept(long value) {
119 sum.add(value);
120 }
121
122 /**
123 * Gets the sum of all input values.
124 *
125 * <p>When no values have been added, the result is zero.
126 *
127 * <p>Warning: This will raise an {@link ArithmeticException}
128 * if the result is not within the range {@code [-2^31, 2^31)}.
129 *
130 * @return sum of all values.
131 * @throws ArithmeticException if the {@code result} overflows an {@code int}
132 * @see #getAsBigInteger()
133 */
134 @Override
135 public int getAsInt() {
136 return sum.toIntExact();
137 }
138
139 /**
140 * Gets the sum of all input values.
141 *
142 * <p>When no values have been added, the result is zero.
143 *
144 * <p>Warning: This will raise an {@link ArithmeticException}
145 * if the result is not within the range {@code [-2^63, 2^63)}.
146 *
147 * @return sum of all values.
148 * @throws ArithmeticException if the {@code result} overflows a {@code long}
149 * @see #getAsBigInteger()
150 */
151 @Override
152 public long getAsLong() {
153 return sum.toLongExact();
154 }
155
156 /**
157 * Gets the sum of all input values.
158 *
159 * <p>When no values have been added, the result is zero.
160 *
161 * <p>Note that this conversion can lose information about the precision of the
162 * {@code BigInteger} value.
163 *
164 * @return sum of all values.
165 * @see #getAsBigInteger()
166 */
167 @Override
168 public double getAsDouble() {
169 return sum.toDouble();
170 }
171
172 /**
173 * Gets the sum of all input values.
174 *
175 * <p>When no values have been added, the result is zero.
176 *
177 * @return sum of all values.
178 */
179 @Override
180 public BigInteger getAsBigInteger() {
181 return sum.toBigInteger();
182 }
183
184 @Override
185 public LongSum combine(LongSum other) {
186 sum.add(other.sum);
187 return this;
188 }
189 }