View Javadoc
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.lang3.math;
18  
19  import org.apache.commons.lang3.Validate;
20  
21  /**
22   * <p>Provides IEEE-754r variants of NumberUtils methods. </p>
23   *
24   * <p>See: <a href="http://en.wikipedia.org/wiki/IEEE_754r">http://en.wikipedia.org/wiki/IEEE_754r</a></p>
25   *
26   * @since 2.4
27   * @version $Id: IEEE754rUtils.java 1593679 2014-05-10 07:22:22Z djones $
28   */
29  public class IEEE754rUtils {
30      
31       /**
32       * <p>Returns the minimum value in an array.</p>
33       * 
34       * @param array  an array, must not be null or empty
35       * @return the minimum value in the array
36       * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
37       * @throws IllegalArgumentException if <code>array</code> is empty
38        * @since 3.4 Changed signature from min(double[]) to min(double...)
39       */
40      public static double min(final double... array) {
41          // Validates input
42          if (array == null) {
43              throw new IllegalArgumentException("The Array must not be null");
44          } 
45          Validate.isTrue(array.length != 0, "Array cannot be empty.");
46          
47      
48          // Finds and returns min
49          double min = array[0];
50          for (int i = 1; i < array.length; i++) {
51              min = min(array[i], min);
52          }
53      
54          return min;
55      }
56  
57      /**
58       * <p>Returns the minimum value in an array.</p>
59       * 
60       * @param array  an array, must not be null or empty
61       * @return the minimum value in the array
62       * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
63       * @throws IllegalArgumentException if <code>array</code> is empty
64       * @since 3.4 Changed signature from min(float[]) to min(float...)
65       */
66      public static float min(final float... array) {
67          // Validates input
68          if (array == null) {
69              throw new IllegalArgumentException("The Array must not be null");
70          } 
71          Validate.isTrue(array.length != 0, "Array cannot be empty.");
72          
73          // Finds and returns min
74          float min = array[0];
75          for (int i = 1; i < array.length; i++) {
76              min = min(array[i], min);
77          }
78      
79          return min;
80      }
81  
82      /**
83       * <p>Gets the minimum of three <code>double</code> values.</p>
84       * 
85       * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
86       * 
87       * @param a  value 1
88       * @param b  value 2
89       * @param c  value 3
90       * @return  the smallest of the values
91       */
92      public static double min(final double a, final double b, final double c) {
93          return min(min(a, b), c);
94      }
95  
96      /**
97       * <p>Gets the minimum of two <code>double</code> values.</p>
98       * 
99       * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
100      * 
101      * @param a  value 1
102      * @param b  value 2
103      * @return  the smallest of the values
104      */
105     public static double min(final double a, final double b) {
106         if(Double.isNaN(a)) {
107             return b;
108         } else
109         if(Double.isNaN(b)) {
110             return a;
111         } else {
112             return Math.min(a, b);
113         }
114     }
115 
116     /**
117      * <p>Gets the minimum of three <code>float</code> values.</p>
118      * 
119      * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
120      *
121      * @param a  value 1
122      * @param b  value 2
123      * @param c  value 3
124      * @return  the smallest of the values
125      */
126     public static float min(final float a, final float b, final float c) {
127         return min(min(a, b), c);
128     }
129 
130     /**
131      * <p>Gets the minimum of two <code>float</code> values.</p>
132      * 
133      * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
134      *
135      * @param a  value 1
136      * @param b  value 2
137      * @return  the smallest of the values
138      */
139     public static float min(final float a, final float b) {
140         if(Float.isNaN(a)) {
141             return b;
142         } else
143         if(Float.isNaN(b)) {
144             return a;
145         } else {
146             return Math.min(a, b);
147         }
148     }
149 
150     /**
151      * <p>Returns the maximum value in an array.</p>
152      * 
153      * @param array  an array, must not be null or empty
154      * @return the minimum value in the array
155      * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
156      * @throws IllegalArgumentException if <code>array</code> is empty
157      * @since 3.4 Changed signature from max(double[]) to max(double...)
158      */
159     public static double max(final double... array) {
160         // Validates input
161         if (array== null) {
162             throw new IllegalArgumentException("The Array must not be null");
163         }         
164         Validate.isTrue(array.length != 0, "Array cannot be empty.");
165         
166         // Finds and returns max
167         double max = array[0];
168         for (int j = 1; j < array.length; j++) {
169             max = max(array[j], max);
170         }
171     
172         return max;
173     }
174 
175     /**
176      * <p>Returns the maximum value in an array.</p>
177      * 
178      * @param array  an array, must not be null or empty
179      * @return the minimum value in the array
180      * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
181      * @throws IllegalArgumentException if <code>array</code> is empty
182      * @since 3.4 Changed signature from max(float[]) to max(float...)
183      */
184     public static float max(final float... array) {
185         // Validates input
186         if (array == null) {
187             throw new IllegalArgumentException("The Array must not be null");
188         } 
189         Validate.isTrue(array.length != 0, "Array cannot be empty.");
190         
191         // Finds and returns max
192         float max = array[0];
193         for (int j = 1; j < array.length; j++) {
194             max = max(array[j], max);
195         }
196 
197         return max;
198     }
199      
200     /**
201      * <p>Gets the maximum of three <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      * @param c  value 3
208      * @return  the largest of the values
209      */
210     public static double max(final double a, final double b, final double c) {
211         return max(max(a, b), c);
212     }
213 
214     /**
215      * <p>Gets the maximum of two <code>double</code> values.</p>
216      * 
217      * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
218      *
219      * @param a  value 1
220      * @param b  value 2
221      * @return  the largest of the values
222      */
223     public static double max(final double a, final double b) {
224         if(Double.isNaN(a)) {
225             return b;
226         } else
227         if(Double.isNaN(b)) {
228             return a;
229         } else {
230             return Math.max(a, b);
231         }
232     }
233 
234     /**
235      * <p>Gets the maximum of three <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      * @param c  value 3
242      * @return  the largest of the values
243      */
244     public static float max(final float a, final float b, final float c) {
245         return max(max(a, b), c);
246     }
247 
248     /**
249      * <p>Gets the maximum of two <code>float</code> values.</p>
250      * 
251      * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
252      *
253      * @param a  value 1
254      * @param b  value 2
255      * @return  the largest of the values
256      */
257     public static float max(final float a, final float b) {
258         if(Float.isNaN(a)) {
259             return b;
260         } else
261         if(Float.isNaN(b)) {
262             return a;
263         } else {
264             return Math.max(a, b);
265         }
266     }
267 
268 }