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 maximum of the available values. Uses {@link Math#max(double, double) Math.max} as an 21 * underlying function to compute the {@code maximum}. 22 * 23 * <ul> 24 * <li>The result is {@link Double#NEGATIVE_INFINITY negative 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#max(double, double) 47 */ 48 public final class Max implements DoubleStatistic, StatisticAccumulator<Max> { 49 50 /** Current maximum. */ 51 private double maximum = Double.NEGATIVE_INFINITY; 52 53 /** 54 * Create an instance. 55 */ 56 private Max() { 57 // No-op 58 } 59 60 /** 61 * Creates an instance. 62 * 63 * <p>The initial result is {@link Double#NEGATIVE_INFINITY negative infinity}. 64 * 65 * @return {@code Max} instance. 66 */ 67 public static Max create() { 68 return new Max(); 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#NEGATIVE_INFINITY negative infinity}. 78 * 79 * @param values Values. 80 * @return {@code Max} instance. 81 */ 82 public static Max of(double... values) { 83 return Statistics.add(new Max(), values); 84 } 85 86 /** 87 * Returns an instance populated using the specified range of {@code values}. 88 * 89 * <p>The result is {@code NaN} if any of the values is {@code NaN}. 90 * 91 * <p>When the range is empty, the result is 92 * {@link Double#NEGATIVE_INFINITY negative infinity}. 93 * 94 * @param values Values. 95 * @param from Inclusive start of the range. 96 * @param to Exclusive end of the range. 97 * @return {@code Max} instance. 98 * @throws IndexOutOfBoundsException if the sub-range is out of bounds 99 * @since 1.2 100 */ 101 public static Max ofRange(double[] values, int from, int to) { 102 Statistics.checkFromToIndex(from, to, values.length); 103 return createFromRange(values, from, to); 104 } 105 106 /** 107 * Create an instance using the specified range of {@code values}. 108 * 109 * <p>Warning: No range checks are performed. 110 * 111 * @param values Values. 112 * @param from Inclusive start of the range. 113 * @param to Exclusive end of the range. 114 * @return {@code Max} instance. 115 */ 116 static Max createFromRange(double[] values, int from, int to) { 117 return Statistics.add(new Max(), values, from, to); 118 } 119 120 /** 121 * Updates the state of the statistic to reflect the addition of {@code value}. 122 * 123 * @param value Value. 124 */ 125 @Override 126 public void accept(double value) { 127 maximum = Math.max(maximum, value); 128 } 129 130 /** 131 * Gets the maximum of all input values. 132 * 133 * <p>When no values have been added, the result is 134 * {@link Double#NEGATIVE_INFINITY negative infinity}. 135 * 136 * @return maximum of all values. 137 */ 138 @Override 139 public double getAsDouble() { 140 return maximum; 141 } 142 143 @Override 144 public Max combine(Max other) { 145 accept(other.getAsDouble()); 146 return this; 147 } 148 }