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