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