Product.java

  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.  * Returns the product of the available values.
  20.  *
  21.  * <ul>
  22.  *   <li>The result is one if no values are observed.
  23.  *   <li>The result is {@code NaN} if any of the values is {@code NaN}.
  24.  * </ul>
  25.  *
  26.  * <p>This class is designed to work with (though does not require)
  27.  * {@linkplain java.util.stream streams}.
  28.  *
  29.  * <p><strong>This instance is not thread safe.</strong>
  30.  * If multiple threads access an instance of this class concurrently,
  31.  * and at least one of the threads invokes the {@link java.util.function.DoubleConsumer#accept(double) accept} or
  32.  * {@link StatisticAccumulator#combine(StatisticResult) combine} method, it must be synchronized externally.
  33.  *
  34.  * <p>However, it is safe to use {@link java.util.function.DoubleConsumer#accept(double) accept}
  35.  * and {@link StatisticAccumulator#combine(StatisticResult) combine}
  36.  * as {@code accumulator} and {@code combiner} functions of
  37.  * {@link java.util.stream.Collector Collector} on a parallel stream,
  38.  * because the parallel instance of {@link java.util.stream.Stream#collect Stream.collect()}
  39.  * provides the necessary partitioning, isolation, and merging of results for
  40.  * safe and efficient parallel execution.
  41.  *
  42.  * @since 1.1
  43.  */
  44. public final class Product implements DoubleStatistic, StatisticAccumulator<Product> {

  45.     /** Product of all values. */
  46.     private double productValue = 1;

  47.     /**
  48.      * Create an instance.
  49.      */
  50.     private Product() {
  51.         // No-op
  52.     }

  53.     /**
  54.      * Creates an instance.
  55.      *
  56.      * <p>The initial result is one.
  57.      *
  58.      * @return {@code Product} instance.
  59.      */
  60.     public static Product create() {
  61.         return new Product();
  62.     }

  63.     /**
  64.      * Returns an instance populated using the input {@code values}.
  65.      *
  66.      * <p>The result is {@code NaN} if any of the values is {@code NaN}
  67.      * or the product at any point is a {@code NaN}.
  68.      *
  69.      * <p>When the input is an empty array, the result is one.
  70.      *
  71.      * @param values Values.
  72.      * @return {@code Product} instance.
  73.      */
  74.     public static Product of(double... values) {
  75.         return Statistics.add(new Product(), values);
  76.     }

  77.     /**
  78.      * Returns an instance populated using the specified range of {@code values}.
  79.      *
  80.      * <p>The result is {@code NaN} if any of the values is {@code NaN}
  81.      * or the product at any point is a {@code NaN}.
  82.      *
  83.      * <p>When the range is empty, the result is one.
  84.      *
  85.      * @param values Values.
  86.      * @param from Inclusive start of the range.
  87.      * @param to Exclusive end of the range.
  88.      * @return {@code Product} instance.
  89.      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
  90.      * @since 1.2
  91.      */
  92.     public static Product ofRange(double[] values, int from, int to) {
  93.         Statistics.checkFromToIndex(from, to, values.length);
  94.         return createFromRange(values, from, to);
  95.     }

  96.     /**
  97.      * Create an instance using the specified range of {@code values}.
  98.      *
  99.      * <p>Warning: No range checks are performed.
  100.      *
  101.      * @param values Values.
  102.      * @param from Inclusive start of the range.
  103.      * @param to Exclusive end of the range.
  104.      * @return {@code Product} instance.
  105.      */
  106.     static Product createFromRange(double[] values, int from, int to) {
  107.         return Statistics.add(new Product(), values, from, to);
  108.     }

  109.     /**
  110.      * Returns an instance populated using the input {@code values}.
  111.      *
  112.      * <p>When the input is an empty array, the result is one.
  113.      *
  114.      * @param values Values.
  115.      * @return {@code Product} instance.
  116.      */
  117.     public static Product of(int... values) {
  118.         return Statistics.add(new Product(), values);
  119.     }

  120.     /**
  121.      * Returns an instance populated using the specified range of {@code values}.
  122.      *
  123.      * <p>When the range is empty, the result is one.
  124.      *
  125.      * @param values Values.
  126.      * @param from Inclusive start of the range.
  127.      * @param to Exclusive end of the range.
  128.      * @return {@code Product} instance.
  129.      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
  130.      * @since 1.2
  131.      */
  132.     public static Product ofRange(int[] values, int from, int to) {
  133.         Statistics.checkFromToIndex(from, to, values.length);
  134.         return createFromRange(values, from, to);
  135.     }

  136.     /**
  137.      * Create an instance using the specified range of {@code values}.
  138.      *
  139.      * <p>Warning: No range checks are performed.
  140.      *
  141.      * @param values Values.
  142.      * @param from Inclusive start of the range.
  143.      * @param to Exclusive end of the range.
  144.      * @return {@code Product} instance.
  145.      */
  146.     static Product createFromRange(int[] values, int from, int to) {
  147.         return Statistics.add(new Product(), values, from, to);
  148.     }

  149.     /**
  150.      * Returns an instance populated using the input {@code values}.
  151.      *
  152.      * <p>When the input is an empty array, the result is one.
  153.      *
  154.      * @param values Values.
  155.      * @return {@code Product} instance.
  156.      */
  157.     public static Product of(long... values) {
  158.         return Statistics.add(new Product(), values);
  159.     }

  160.     /**
  161.      * Returns an instance populated using the specified range of {@code values}.
  162.      *
  163.      * <p>When the range is empty, the result is one.
  164.      *
  165.      * @param values Values.
  166.      * @param from Inclusive start of the range.
  167.      * @param to Exclusive end of the range.
  168.      * @return {@code Product} instance.
  169.      * @throws IndexOutOfBoundsException if the sub-range is out of bounds
  170.      * @since 1.2
  171.      */
  172.     public static Product ofRange(long[] values, int from, int to) {
  173.         Statistics.checkFromToIndex(from, to, values.length);
  174.         return createFromRange(values, from, to);
  175.     }

  176.     /**
  177.      * Create an instance using the specified range of {@code values}.
  178.      *
  179.      * <p>Warning: No range checks are performed.
  180.      *
  181.      * @param values Values.
  182.      * @param from Inclusive start of the range.
  183.      * @param to Exclusive end of the range.
  184.      * @return {@code Product} instance.
  185.      */
  186.     static Product createFromRange(long[] values, int from, int to) {
  187.         return Statistics.add(new Product(), values, from, to);
  188.     }

  189.     /**
  190.      * Updates the state of the statistic to reflect the addition of {@code value}.
  191.      *
  192.      * @param value Value.
  193.      */
  194.     @Override
  195.     public void accept(double value) {
  196.         this.productValue *= value;
  197.     }

  198.     /**
  199.      * Gets the product of all input values.
  200.      *
  201.      * <p>When no values have been added, the result is one.
  202.      *
  203.      * @return product of all values.
  204.      */
  205.     @Override
  206.     public double getAsDouble() {
  207.         return productValue;
  208.     }

  209.     @Override
  210.     public Product combine(Product other) {
  211.         productValue *= other.productValue;
  212.         return this;
  213.     }
  214. }