    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 *      https://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.lang3.math;
    018
    019import java.util.Objects;
    020
    021import org.apache.commons.lang3.Validate;
    022
    023/**
    024 * Provides IEEE-754r variants of NumberUtils methods.
    025 *
    026 * <p>See: <a href="https://en.wikipedia.org/wiki/IEEE_754r">https://en.wikipedia.org/wiki/IEEE_754r</a></p>
    027 *
    028 * @since 2.4
    029 */
    030public class IEEE754rUtils {
    031
    032     /**
    033     * Returns the maximum value in an array.
    034     *
    035     * @param array  an array, must not be null or empty.
    036     * @return the minimum value in the array.
    037     * @throws NullPointerException if {@code array} is {@code null}.
    038     * @throws IllegalArgumentException if {@code array} is empty.
    039     * @since 3.4 Changed signature from max(double[]) to max(double...)
    040     */
    041    public static double max(final double... array) {
    042        Objects.requireNonNull(array, "array");
    043        Validate.isTrue(array.length != 0, "Array cannot be empty.");
    044
    045        // Finds and returns max
    046        double max = array[0];
    047        for (int j = 1; j < array.length; j++) {
    048            max = max(array[j], max);
    049        }
    050
    051        return max;
    052    }
    053
    054    /**
    055     * Gets the maximum of two {@code double} values.
    056     *
    057     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    058     *
    059     * @param a  value 1.
    060     * @param b  value 2.
    061     * @return  the largest of the values.
    062     */
    063    public static double max(final double a, final double b) {
    064        if (Double.isNaN(a)) {
    065            return b;
    066        }
    067        if (Double.isNaN(b)) {
    068            return a;
    069        }
    070        return Math.max(a, b);
    071    }
    072
    073    /**
    074     * Gets the maximum of three {@code double} values.
    075     *
    076     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    077     *
    078     * @param a  value 1.
    079     * @param b  value 2.
    080     * @param c  value 3.
    081     * @return  the largest of the values.
    082     */
    083    public static double max(final double a, final double b, final double c) {
    084        return max(max(a, b), c);
    085    }
    086
    087    /**
    088     * Returns the maximum value in an array.
    089     *
    090     * @param array  an array, must not be null or empty.
    091     * @return the minimum value in the array.
    092     * @throws NullPointerException if {@code array} is {@code null}.
    093     * @throws IllegalArgumentException if {@code array} is empty.
    094     * @since 3.4 Changed signature from max(float[]) to max(float...)
    095     */
    096    public static float max(final float... array) {
    097        Objects.requireNonNull(array, "array");
    098        Validate.isTrue(array.length != 0, "Array cannot be empty.");
    099
    100        // Finds and returns max
    101        float max = array[0];
    102        for (int j = 1; j < array.length; j++) {
    103            max = max(array[j], max);
    104        }
    105
    106        return max;
    107    }
    108
    109    /**
    110     * Gets the maximum of two {@code float} values.
    111     *
    112     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    113     *
    114     * @param a  value 1.
    115     * @param b  value 2.
    116     * @return  the largest of the values.
    117     */
    118    public static float max(final float a, final float b) {
    119        if (Float.isNaN(a)) {
    120            return b;
    121        }
    122        if (Float.isNaN(b)) {
    123            return a;
    124        }
    125        return Math.max(a, b);
    126    }
    127
    128    /**
    129     * Gets the maximum of three {@code float} values.
    130     *
    131     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    132     *
    133     * @param a  value 1.
    134     * @param b  value 2.
    135     * @param c  value 3.
    136     * @return  the largest of the values.
    137     */
    138    public static float max(final float a, final float b, final float c) {
    139        return max(max(a, b), c);
    140    }
    141
    142    /**
    143     * Returns the minimum value in an array.
    144     *
    145     * @param array  an array, must not be null or empty.
    146     * @return the minimum value in the array.
    147     * @throws NullPointerException if {@code array} is {@code null}.
    148     * @throws IllegalArgumentException if {@code array} is empty.
    149     * @since 3.4 Changed signature from min(double[]) to min(double...).
    150     */
    151    public static double min(final double... array) {
    152        Objects.requireNonNull(array, "array");
    153        Validate.isTrue(array.length != 0, "Array cannot be empty.");
    154
    155        // Finds and returns min
    156        double min = array[0];
    157        for (int i = 1; i < array.length; i++) {
    158            min = min(array[i], min);
    159        }
    160
    161        return min;
    162    }
    163
    164    /**
    165     * Gets the minimum of two {@code double} values.
    166     *
    167     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    168     *
    169     * @param a  value 1.
    170     * @param b  value 2.
    171     * @return  the smallest of the values.
    172     */
    173    public static double min(final double a, final double b) {
    174        if (Double.isNaN(a)) {
    175            return b;
    176        }
    177        if (Double.isNaN(b)) {
    178            return a;
    179        }
    180        return Math.min(a, b);
    181    }
    182
    183    /**
    184     * Gets the minimum of three {@code double} values.
    185     *
    186     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    187     *
    188     * @param a  value 1
    189     * @param b  value 2
    190     * @param c  value 3
    191     * @return  the smallest of the values
    192     */
    193    public static double min(final double a, final double b, final double c) {
    194        return min(min(a, b), c);
    195    }
    196
    197    /**
    198     * Returns the minimum value in an array.
    199     *
    200     * @param array  an array, must not be null or empty.
    201     * @return the minimum value in the array.
    202     * @throws NullPointerException if {@code array} is {@code null}.
    203     * @throws IllegalArgumentException if {@code array} is empty.
    204     * @since 3.4 Changed signature from min(float[]) to min(float...).
    205     */
    206    public static float min(final float... array) {
    207        Objects.requireNonNull(array, "array");
    208        Validate.isTrue(array.length != 0, "Array cannot be empty.");
    209
    210        // Finds and returns min
    211        float min = array[0];
    212        for (int i = 1; i < array.length; i++) {
    213            min = min(array[i], min);
    214        }
    215
    216        return min;
    217    }
    218
    219    /**
    220     * Gets the minimum of two {@code float} values.
    221     *
    222     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    223     *
    224     * @param a  value 1.
    225     * @param b  value 2.
    226     * @return  the smallest of the values.
    227     */
    228    public static float min(final float a, final float b) {
    229        if (Float.isNaN(a)) {
    230            return b;
    231        }
    232        if (Float.isNaN(b)) {
    233            return a;
    234        }
    235        return Math.min(a, b);
    236    }
    237
    238    /**
    239     * Gets the minimum of three {@code float} values.
    240     *
    241     * <p>NaN is only returned if all numbers are NaN as per IEEE-754r.</p>
    242     *
    243     * @param a  value 1.
    244     * @param b  value 2.
    245     * @param c  value 3.
    246     * @return  the smallest of the values.
    247     */
    248    public static float min(final float a, final float b, final float c) {
    249        return min(min(a, b), c);
    250    }
    251
    252    /**
    253     * Make private in 4.0.
    254     *
    255     * @deprecated TODO Make private in 4.0.
    256     */
    257    @Deprecated
    258    public IEEE754rUtils() {
    259        // empty
    260    }
    261}