001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.statistics.descriptive;
018
019/**
020 * Returns the product of the available values.
021 *
022 * <ul>
023 *   <li>The result is one if no values are observed.
024 *   <li>The result is {@code NaN} if any of the values is {@code NaN}.
025 * </ul>
026 *
027 * <p>This class is designed to work with (though does not require)
028 * {@linkplain java.util.stream streams}.
029 *
030 * <p><strong>This instance is not thread safe.</strong>
031 * If multiple threads access an instance of this class concurrently,
032 * and at least one of the threads invokes the {@link java.util.function.DoubleConsumer#accept(double) accept} or
033 * {@link StatisticAccumulator#combine(StatisticResult) combine} method, it must be synchronized externally.
034 *
035 * <p>However, it is safe to use {@link java.util.function.DoubleConsumer#accept(double) accept}
036 * and {@link StatisticAccumulator#combine(StatisticResult) combine}
037 * as {@code accumulator} and {@code combiner} functions of
038 * {@link java.util.stream.Collector Collector} on a parallel stream,
039 * because the parallel instance of {@link java.util.stream.Stream#collect Stream.collect()}
040 * provides the necessary partitioning, isolation, and merging of results for
041 * safe and efficient parallel execution.
042 *
043 * @since 1.1
044 */
045public final class Product implements DoubleStatistic, StatisticAccumulator<Product> {
046
047    /** Product of all values. */
048    private double productValue = 1;
049
050    /**
051     * Create an instance.
052     */
053    private Product() {
054        // No-op
055    }
056
057    /**
058     * Creates an instance.
059     *
060     * <p>The initial result is one.
061     *
062     * @return {@code Product} instance.
063     */
064    public static Product create() {
065        return new Product();
066    }
067
068    /**
069     * Returns an instance populated using the input {@code values}.
070     *
071     * <p>The result is {@code NaN} if any of the values is {@code NaN}
072     * or the product at any point is a {@code NaN}.
073     *
074     * <p>When the input is an empty array, the result is one.
075     *
076     * @param values Values.
077     * @return {@code Product} instance.
078     */
079    public static Product of(double... values) {
080        return Statistics.add(new Product(), values);
081    }
082
083    /**
084     * Returns an instance populated using the specified range of {@code values}.
085     *
086     * <p>The result is {@code NaN} if any of the values is {@code NaN}
087     * or the product at any point is a {@code NaN}.
088     *
089     * <p>When the range is empty, the result is one.
090     *
091     * @param values Values.
092     * @param from Inclusive start of the range.
093     * @param to Exclusive end of the range.
094     * @return {@code Product} instance.
095     * @throws IndexOutOfBoundsException if the sub-range is out of bounds
096     * @since 1.2
097     */
098    public static Product ofRange(double[] values, int from, int to) {
099        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}