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  /**
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 specified range of {@code values}.
85       *
86       * <p>The result is {@code NaN} if any of the values is {@code NaN}
87       * or the product at any point is a {@code NaN}.
88       *
89       * <p>When the range is empty, the result is one.
90       *
91       * @param values Values.
92       * @param from Inclusive start of the range.
93       * @param to Exclusive end of the range.
94       * @return {@code Product} instance.
95       * @throws IndexOutOfBoundsException if the sub-range is out of bounds
96       * @since 1.2
97       */
98      public static Product ofRange(double[] values, int from, int to) {
99          Statistics.checkFromToIndex(from, to, values.length);
100         return createFromRange(values, from, to);
101     }
102 
103     /**
104      * Create an instance using the specified range of {@code values}.
105      *
106      * <p>Warning: No range checks are performed.
107      *
108      * @param values Values.
109      * @param from Inclusive start of the range.
110      * @param to Exclusive end of the range.
111      * @return {@code Product} instance.
112      */
113     static Product createFromRange(double[] values, int from, int to) {
114         return Statistics.add(new Product(), values, from, to);
115     }
116 
117     /**
118      * Returns an instance populated using the input {@code values}.
119      *
120      * <p>When the input is an empty array, the result is one.
121      *
122      * @param values Values.
123      * @return {@code Product} instance.
124      */
125     public static Product of(int... values) {
126         return Statistics.add(new Product(), values);
127     }
128 
129     /**
130      * Returns an instance populated using the specified range of {@code values}.
131      *
132      * <p>When the range is empty, the result is one.
133      *
134      * @param values Values.
135      * @param from Inclusive start of the range.
136      * @param to Exclusive end of the range.
137      * @return {@code Product} instance.
138      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
139      * @since 1.2
140      */
141     public static Product ofRange(int[] values, int from, int to) {
142         Statistics.checkFromToIndex(from, to, values.length);
143         return createFromRange(values, from, to);
144     }
145 
146     /**
147      * Create an instance using the specified range of {@code values}.
148      *
149      * <p>Warning: No range checks are performed.
150      *
151      * @param values Values.
152      * @param from Inclusive start of the range.
153      * @param to Exclusive end of the range.
154      * @return {@code Product} instance.
155      */
156     static Product createFromRange(int[] values, int from, int to) {
157         return Statistics.add(new Product(), values, from, to);
158     }
159 
160     /**
161      * Returns an instance populated using the input {@code values}.
162      *
163      * <p>When the input is an empty array, the result is one.
164      *
165      * @param values Values.
166      * @return {@code Product} instance.
167      */
168     public static Product of(long... values) {
169         return Statistics.add(new Product(), values);
170     }
171 
172     /**
173      * Returns an instance populated using the specified range of {@code values}.
174      *
175      * <p>When the range is empty, the result is one.
176      *
177      * @param values Values.
178      * @param from Inclusive start of the range.
179      * @param to Exclusive end of the range.
180      * @return {@code Product} instance.
181      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
182      * @since 1.2
183      */
184     public static Product ofRange(long[] values, int from, int to) {
185         Statistics.checkFromToIndex(from, to, values.length);
186         return createFromRange(values, from, to);
187     }
188 
189     /**
190      * Create an instance using the specified range of {@code values}.
191      *
192      * <p>Warning: No range checks are performed.
193      *
194      * @param values Values.
195      * @param from Inclusive start of the range.
196      * @param to Exclusive end of the range.
197      * @return {@code Product} instance.
198      */
199     static Product createFromRange(long[] values, int from, int to) {
200         return Statistics.add(new Product(), values, from, to);
201     }
202 
203     /**
204      * Updates the state of the statistic to reflect the addition of {@code value}.
205      *
206      * @param value Value.
207      */
208     @Override
209     public void accept(double value) {
210         this.productValue *= value;
211     }
212 
213     /**
214      * Gets the product of all input values.
215      *
216      * <p>When no values have been added, the result is one.
217      *
218      * @return product of all values.
219      */
220     @Override
221     public double getAsDouble() {
222         return productValue;
223     }
224 
225     @Override
226     public Product combine(Product other) {
227         productValue *= other.productValue;
228         return this;
229     }
230 }