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}