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