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          Validate.isTrue(array != null, "The Array must not be null");
41          Validate.isTrue(array.length != 0, "Array cannot be empty.");
42  
43          // Finds and returns min
44          double min = array[0];
45          for (int i = 1; i < array.length; i++) {
46              min = min(array[i], min);
47          }
48  
49          return min;
50      }
51  
52      /**
53       * <p>Returns the minimum value in an array.</p>
54       *
55       * @param array  an array, must not be null or empty
56       * @return the minimum value in the array
57       * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
58       * @throws IllegalArgumentException if <code>array</code> is empty
59       * @since 3.4 Changed signature from min(float[]) to min(float...)
60       */
61      public static float min(final float... array) {
62          Validate.isTrue(array != null, "The Array must not be null");
63          Validate.isTrue(array.length != 0, "Array cannot be empty.");
64  
65          // Finds and returns min
66          float min = array[0];
67          for (int i = 1; i < array.length; i++) {
68              min = min(array[i], min);
69          }
70  
71          return min;
72      }
73  
74      /**
75       * <p>Gets the minimum of three <code>double</code> values.</p>
76       *
77       * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
78       *
79       * @param a  value 1
80       * @param b  value 2
81       * @param c  value 3
82       * @return  the smallest of the values
83       */
84      public static double min(final double a, final double b, final double c) {
85          return min(min(a, b), c);
86      }
87  
88      /**
89       * <p>Gets the minimum of two <code>double</code> values.</p>
90       *
91       * <p>NaN is only returned if all numbers are NaN as per IEEE-754r. </p>
92       *
93       * @param a  value 1
94       * @param b  value 2
95       * @return  the smallest of the values
96       */
97      public static double min(final double a, final double b) {
98          if(Double.isNaN(a)) {
99              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 }