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