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 /**
20 * Returns the product of the available values.
21 *
22 * <ul>
23 * <li>The result is one if no values are observed.
24 * <li>The result is {@code NaN} if any of the values is {@code NaN}.
25 * </ul>
26 *
27 * <p>This class is designed to work with (though does not require)
28 * {@linkplain java.util.stream streams}.
29 *
30 * <p><strong>This instance is not thread safe.</strong>
31 * If multiple threads access an instance of this class concurrently,
32 * and at least one of the threads invokes the {@link java.util.function.DoubleConsumer#accept(double) accept} or
33 * {@link StatisticAccumulator#combine(StatisticResult) combine} method, it must be synchronized externally.
34 *
35 * <p>However, it is safe to use {@link java.util.function.DoubleConsumer#accept(double) accept}
36 * and {@link StatisticAccumulator#combine(StatisticResult) combine}
37 * as {@code accumulator} and {@code combiner} functions of
38 * {@link java.util.stream.Collector Collector} on a parallel stream,
39 * because the parallel instance of {@link java.util.stream.Stream#collect Stream.collect()}
40 * provides the necessary partitioning, isolation, and merging of results for
41 * safe and efficient parallel execution.
42 *
43 * @since 1.1
44 */
45 public final class Product implements DoubleStatistic, StatisticAccumulator<Product> {
46
47 /** Product of all values. */
48 private double productValue = 1;
49
50 /**
51 * Create an instance.
52 */
53 private Product() {
54 // No-op
55 }
56
57 /**
58 * Creates an instance.
59 *
60 * <p>The initial result is one.
61 *
62 * @return {@code Product} instance.
63 */
64 public static Product create() {
65 return new Product();
66 }
67
68 /**
69 * Returns an instance populated using the input {@code values}.
70 *
71 * <p>The result is {@code NaN} if any of the values is {@code NaN}
72 * or the product at any point is a {@code NaN}.
73 *
74 * <p>When the input is an empty array, the result is one.
75 *
76 * @param values Values.
77 * @return {@code Product} instance.
78 */
79 public static Product of(double... values) {
80 return Statistics.add(new Product(), values);
81 }
82
83 /**
84 * Returns an instance populated using the input {@code values}.
85 *
86 * <p>When the input is an empty array, the result is one.
87 *
88 * @param values Values.
89 * @return {@code Product} instance.
90 */
91 public static Product of(int... values) {
92 return Statistics.add(new Product(), values);
93 }
94
95 /**
96 * Returns an instance populated using the input {@code values}.
97 *
98 * <p>When the input is an empty array, the result is one.
99 *
100 * @param values Values.
101 * @return {@code Product} instance.
102 */
103 public static Product of(long... values) {
104 return Statistics.add(new Product(), values);
105 }
106
107 /**
108 * Updates the state of the statistic to reflect the addition of {@code value}.
109 *
110 * @param value Value.
111 */
112 @Override
113 public void accept(double value) {
114 this.productValue *= value;
115 }
116
117 /**
118 * Gets the product of all input values.
119 *
120 * <p>When no values have been added, the result is one.
121 *
122 * @return product of all values.
123 */
124 @Override
125 public double getAsDouble() {
126 return productValue;
127 }
128
129 @Override
130 public Product combine(Product other) {
131 productValue *= other.productValue;
132 return this;
133 }
134 }