IntMin.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. import java.math.BigInteger;

  19. /**
  20.  * Returns the minimum of the available values. Uses {@link Math#min(int, int) Math.min} as an
  21.  * underlying function to compute the {@code minimum}.
  22.  *
  23.  * <ul>
  24.  *   <li>The result is {@link Integer#MAX_VALUE} if no values are added.
  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 implementation 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.IntConsumer#accept(int) 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.IntConsumer#accept(int) 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 implementation 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.  * @see Math#min(int, int)
  45.  */
  46. public final class IntMin implements IntStatistic, StatisticAccumulator<IntMin> {

  47.     /** Current minimum. */
  48.     private int minimum = Integer.MAX_VALUE;

  49.     /**
  50.      * Create an instance.
  51.      */
  52.     private IntMin() {
  53.         // No-op
  54.     }

  55.     /**
  56.      * Creates an instance.
  57.      *
  58.      * <p>The initial result is {@link Integer#MAX_VALUE}.
  59.      *
  60.      * @return {@code IntMin} instance.
  61.      */
  62.     public static IntMin create() {
  63.         return new IntMin();
  64.     }

  65.     /**
  66.      * Returns an instance populated using the input {@code values}.
  67.      *
  68.      * <p>When the input is an empty array, the result is
  69.      * {@link Integer#MAX_VALUE}.
  70.      *
  71.      * @param values Values.
  72.      * @return {@code IntMin} instance.
  73.      */
  74.     public static IntMin of(int... values) {
  75.         return Statistics.add(new IntMin(), values);
  76.     }

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

  94.     /**
  95.      * Create an instance using the specified range of {@code values}.
  96.      *
  97.      * <p>Warning: No range checks are performed.
  98.      *
  99.      * @param values Values.
  100.      * @param from Inclusive start of the range.
  101.      * @param to Exclusive end of the range.
  102.      * @return {@code IntMin} instance.
  103.      */
  104.     static IntMin createFromRange(int[] values, int from, int to) {
  105.         return Statistics.add(new IntMin(), values, from, to);
  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(int value) {
  114.         minimum = Math.min(minimum, value);
  115.     }

  116.     /**
  117.      * Gets the minimum of all input values.
  118.      *
  119.      * <p>When no values have been added, the result is
  120.      * {@link Integer#MAX_VALUE}.
  121.      *
  122.      * @return minimum of all values.
  123.      */
  124.     @Override
  125.     public int getAsInt() {
  126.         return minimum;
  127.     }

  128.     @Override
  129.     public long getAsLong() {
  130.         return minimum;
  131.     }

  132.     @Override
  133.     public double getAsDouble() {
  134.         return minimum;
  135.     }

  136.     @Override
  137.     public BigInteger getAsBigInteger() {
  138.         return BigInteger.valueOf(minimum);
  139.     }

  140.     @Override
  141.     public IntMin combine(IntMin other) {
  142.         accept(other.getAsInt());
  143.         return this;
  144.     }
  145. }