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 java.lang.reflect.Array;
20 import java.math.BigDecimal;
21 import java.math.BigInteger;
22 import java.math.RoundingMode;
23 import java.util.Objects;
24
25 import org.apache.commons.lang3.StringUtils;
26 import org.apache.commons.lang3.Validate;
27
28 /**
29 * Provides extra functionality for Java Number classes.
30 *
31 * @since 2.0
32 */
33 public class NumberUtils {
34
35 /** Reusable Long constant for zero. */
36 public static final Long LONG_ZERO = Long.valueOf(0L);
37 /** Reusable Long constant for one. */
38 public static final Long LONG_ONE = Long.valueOf(1L);
39 /** Reusable Long constant for minus one. */
40 public static final Long LONG_MINUS_ONE = Long.valueOf(-1L);
41 /** Reusable Integer constant for zero. */
42 public static final Integer INTEGER_ZERO = Integer.valueOf(0);
43 /** Reusable Integer constant for one. */
44 public static final Integer INTEGER_ONE = Integer.valueOf(1);
45 /** Reusable Integer constant for two */
46 public static final Integer INTEGER_TWO = Integer.valueOf(2);
47 /** Reusable Integer constant for minus one. */
48 public static final Integer INTEGER_MINUS_ONE = Integer.valueOf(-1);
49 /** Reusable Short constant for zero. */
50 public static final Short SHORT_ZERO = Short.valueOf((short) 0);
51 /** Reusable Short constant for one. */
52 public static final Short SHORT_ONE = Short.valueOf((short) 1);
53 /** Reusable Short constant for minus one. */
54 public static final Short SHORT_MINUS_ONE = Short.valueOf((short) -1);
55 /** Reusable Byte constant for zero. */
56 public static final Byte BYTE_ZERO = Byte.valueOf((byte) 0);
57 /** Reusable Byte constant for one. */
58 public static final Byte BYTE_ONE = Byte.valueOf((byte) 1);
59 /** Reusable Byte constant for minus one. */
60 public static final Byte BYTE_MINUS_ONE = Byte.valueOf((byte) -1);
61 /** Reusable Double constant for zero. */
62 public static final Double DOUBLE_ZERO = Double.valueOf(0.0d);
63 /** Reusable Double constant for one. */
64 public static final Double DOUBLE_ONE = Double.valueOf(1.0d);
65 /** Reusable Double constant for minus one. */
66 public static final Double DOUBLE_MINUS_ONE = Double.valueOf(-1.0d);
67 /** Reusable Float constant for zero. */
68 public static final Float FLOAT_ZERO = Float.valueOf(0.0f);
69 /** Reusable Float constant for one. */
70 public static final Float FLOAT_ONE = Float.valueOf(1.0f);
71 /** Reusable Float constant for minus one. */
72 public static final Float FLOAT_MINUS_ONE = Float.valueOf(-1.0f);
73
74 /**
75 * {@link Integer#MAX_VALUE} as a {@link Long}.
76 *
77 * @since 3.12.0
78 */
79 public static final Long LONG_INT_MAX_VALUE = Long.valueOf(Integer.MAX_VALUE);
80
81 /**
82 * {@link Integer#MIN_VALUE} as a {@link Long}.
83 *
84 * @since 3.12.0
85 */
86 public static final Long LONG_INT_MIN_VALUE = Long.valueOf(Integer.MIN_VALUE);
87
88
89 /**
90 * Compares two {@code byte} values numerically. This is the same functionality as provided in Java 7.
91 *
92 * @param x the first {@code byte} to compare
93 * @param y the second {@code byte} to compare
94 * @return the value {@code 0} if {@code x == y};
95 * a value less than {@code 0} if {@code x < y}; and
96 * a value greater than {@code 0} if {@code x > y}
97 * @since 3.4
98 */
99 public static int compare(final byte x, final byte y) {
100 return x - y;
101 }
102
103 /**
104 * Compares two {@code int} values numerically. This is the same functionality as provided in Java 7.
105 *
106 * @param x the first {@code int} to compare
107 * @param y the second {@code int} to compare
108 * @return the value {@code 0} if {@code x == y};
109 * a value less than {@code 0} if {@code x < y}; and
110 * a value greater than {@code 0} if {@code x > y}
111 * @since 3.4
112 */
113 public static int compare(final int x, final int y) {
114 if (x == y) {
115 return 0;
116 }
117 return x < y ? -1 : 1;
118 }
119
120 /**
121 * Compares to {@code long} values numerically. This is the same functionality as provided in Java 7.
122 *
123 * @param x the first {@code long} to compare
124 * @param y the second {@code long} to compare
125 * @return the value {@code 0} if {@code x == y};
126 * a value less than {@code 0} if {@code x < y}; and
127 * a value greater than {@code 0} if {@code x > y}
128 * @since 3.4
129 */
130 public static int compare(final long x, final long y) {
131 if (x == y) {
132 return 0;
133 }
134 return x < y ? -1 : 1;
135 }
136
137 /**
138 * Compares to {@code short} values numerically. This is the same functionality as provided in Java 7.
139 *
140 * @param x the first {@code short} to compare
141 * @param y the second {@code short} to compare
142 * @return the value {@code 0} if {@code x == y};
143 * a value less than {@code 0} if {@code x < y}; and
144 * a value greater than {@code 0} if {@code x > y}
145 * @since 3.4
146 */
147 public static int compare(final short x, final short y) {
148 if (x == y) {
149 return 0;
150 }
151 return x < y ? -1 : 1;
152 }
153
154 /**
155 * Convert a {@link String} to a {@link BigDecimal}.
156 *
157 * <p>Returns {@code null} if the string is {@code null}.</p>
158 *
159 * @param str a {@link String} to convert, may be null
160 * @return converted {@link BigDecimal} (or null if the input is null)
161 * @throws NumberFormatException if the value cannot be converted
162 */
163 public static BigDecimal createBigDecimal(final String str) {
164 if (str == null) {
165 return null;
166 }
167 // handle JDK1.3.1 bug where "" throws IndexOutOfBoundsException
168 if (StringUtils.isBlank(str)) {
169 throw new NumberFormatException("A blank string is not a valid number");
170 }
171 return new BigDecimal(str);
172 }
173
174 /**
175 * Convert a {@link String} to a {@link BigInteger};
176 * since 3.2 it handles hexadecimal (0x or #) and octal (0) notations.
177 *
178 * <p>Returns {@code null} if the string is {@code null}.</p>
179 *
180 * @param str a {@link String} to convert, may be null
181 * @return converted {@link BigInteger} (or null if the input is null)
182 * @throws NumberFormatException if the value cannot be converted
183 */
184 public static BigInteger createBigInteger(final String str) {
185 if (str == null) {
186 return null;
187 }
188 if (str.isEmpty()) {
189 throw new NumberFormatException("An empty string is not a valid number");
190 }
191 int pos = 0; // offset within string
192 int radix = 10;
193 boolean negate = false; // need to negate later?
194 final char char0 = str.charAt(0);
195 if (char0 == '-') {
196 negate = true;
197 pos = 1;
198 } else if (char0 == '+') {
199 pos = 1;
200 }
201 if (str.startsWith("0x", pos) || str.startsWith("0X", pos)) { // hex
202 radix = 16;
203 pos += 2;
204 } else if (str.startsWith("#", pos)) { // alternative hex (allowed by Long/Integer)
205 radix = 16;
206 pos++;
207 } else if (str.startsWith("0", pos) && str.length() > pos + 1) { // octal; so long as there are additional digits
208 radix = 8;
209 pos++;
210 } // default is to treat as decimal
211
212 final BigInteger value = new BigInteger(str.substring(pos), radix);
213 return negate ? value.negate() : value;
214 }
215
216 /**
217 * Convert a {@link String} to a {@link Double}.
218 *
219 * <p>Returns {@code null} if the string is {@code null}.</p>
220 *
221 * @param str a {@link String} to convert, may be null
222 * @return converted {@link Double} (or null if the input is null)
223 * @throws NumberFormatException if the value cannot be converted
224 */
225 public static Double createDouble(final String str) {
226 if (str == null) {
227 return null;
228 }
229 return Double.valueOf(str);
230 }
231
232 /**
233 * Convert a {@link String} to a {@link Float}.
234 *
235 * <p>Returns {@code null} if the string is {@code null}.</p>
236 *
237 * @param str a {@link String} to convert, may be null
238 * @return converted {@link Float} (or null if the input is null)
239 * @throws NumberFormatException if the value cannot be converted
240 */
241 public static Float createFloat(final String str) {
242 if (str == null) {
243 return null;
244 }
245 return Float.valueOf(str);
246 }
247
248 /**
249 * Convert a {@link String} to a {@link Integer}, handling
250 * hexadecimal (0xhhhh) and octal (0dddd) notations.
251 * N.B. a leading zero means octal; spaces are not trimmed.
252 *
253 * <p>Returns {@code null} if the string is {@code null}.</p>
254 *
255 * @param str a {@link String} to convert, may be null
256 * @return converted {@link Integer} (or null if the input is null)
257 * @throws NumberFormatException if the value cannot be converted
258 */
259 public static Integer createInteger(final String str) {
260 if (str == null) {
261 return null;
262 }
263 // decode() handles 0xAABD and 0777 (hex and octal) as well.
264 return Integer.decode(str);
265 }
266
267 /**
268 * Convert a {@link String} to a {@link Long};
269 * since 3.1 it handles hexadecimal (0Xhhhh) and octal (0ddd) notations.
270 * N.B. a leading zero means octal; spaces are not trimmed.
271 *
272 * <p>Returns {@code null} if the string is {@code null}.</p>
273 *
274 * @param str a {@link String} to convert, may be null
275 * @return converted {@link Long} (or null if the input is null)
276 * @throws NumberFormatException if the value cannot be converted
277 */
278 public static Long createLong(final String str) {
279 if (str == null) {
280 return null;
281 }
282 return Long.decode(str);
283 }
284
285 /**
286 * Turns a string value into a java.lang.Number.
287 *
288 * <p>If the string starts with {@code 0x} or {@code -0x} (lower or upper case) or {@code #} or {@code -#}, it
289 * will be interpreted as a hexadecimal Integer - or Long, if the number of digits after the
290 * prefix is more than 8 - or BigInteger if there are more than 16 digits.
291 * </p>
292 * <p>Then, the value is examined for a type qualifier on the end, i.e. one of
293 * {@code 'f', 'F', 'd', 'D', 'l', 'L'}. If it is found, it starts
294 * trying to create successively larger types from the type specified
295 * until one is found that can represent the value.</p>
296 *
297 * <p>If a type specifier is not found, it will check for a decimal point
298 * and then try successively larger types from {@link Integer} to
299 * {@link BigInteger} and from {@link Float} to
300 * {@link BigDecimal}.</p>
301 *
302 * <p>
303 * Integral values with a leading {@code 0} will be interpreted as octal; the returned number will
304 * be Integer, Long or BigDecimal as appropriate.
305 * </p>
306 *
307 * <p>Returns {@code null} if the string is {@code null}.</p>
308 *
309 * <p>This method does not trim the input string, i.e., strings with leading
310 * or trailing spaces will generate NumberFormatExceptions.</p>
311 *
312 * @param str String containing a number, may be null
313 * @return Number created from the string (or null if the input is null)
314 * @throws NumberFormatException if the value cannot be converted
315 */
316 public static Number createNumber(final String str) {
317 if (str == null) {
318 return null;
319 }
320 if (StringUtils.isBlank(str)) {
321 throw new NumberFormatException("A blank string is not a valid number");
322 }
323 // Need to deal with all possible hex prefixes here
324 final String[] hexPrefixes = {"0x", "0X", "#"};
325 final int length = str.length();
326 final int offset = str.charAt(0) == '+' || str.charAt(0) == '-' ? 1 : 0;
327 int pfxLen = 0;
328 for (final String pfx : hexPrefixes) {
329 if (str.startsWith(pfx, offset)) {
330 pfxLen += pfx.length() + offset;
331 break;
332 }
333 }
334 if (pfxLen > 0) { // we have a hex number
335 char firstSigDigit = 0; // strip leading zeroes
336 for (int i = pfxLen; i < length; i++) {
337 firstSigDigit = str.charAt(i);
338 if (firstSigDigit != '0') {
339 break;
340 }
341 pfxLen++;
342 }
343 final int hexDigits = length - pfxLen;
344 if (hexDigits > 16 || hexDigits == 16 && firstSigDigit > '7') { // too many for Long
345 return createBigInteger(str);
346 }
347 if (hexDigits > 8 || hexDigits == 8 && firstSigDigit > '7') { // too many for an int
348 return createLong(str);
349 }
350 return createInteger(str);
351 }
352 final char lastChar = str.charAt(length - 1);
353 final String mant;
354 final String dec;
355 final String exp;
356 final int decPos = str.indexOf('.');
357 final int expPos = str.indexOf('e') + str.indexOf('E') + 1; // assumes both not present
358 // if both e and E are present, this is caught by the checks on expPos (which prevent IOOBE)
359 // and the parsing which will detect if e or E appear in a number due to using the wrong offset
360
361 // Detect if the return type has been requested
362 final boolean requestType = !Character.isDigit(lastChar) && lastChar != '.';
363 if (decPos > -1) { // there is a decimal point
364 if (expPos > -1) { // there is an exponent
365 if (expPos < decPos || expPos > length) { // prevents double exponent causing IOOBE
366 throw new NumberFormatException(str + " is not a valid number.");
367 }
368 dec = str.substring(decPos + 1, expPos);
369 } else {
370 // No exponent, but there may be a type character to remove
371 dec = str.substring(decPos + 1, requestType ? length - 1 : length);
372 }
373 mant = getMantissa(str, decPos);
374 } else {
375 if (expPos > -1) {
376 if (expPos > length) { // prevents double exponent causing IOOBE
377 throw new NumberFormatException(str + " is not a valid number.");
378 }
379 mant = getMantissa(str, expPos);
380 } else {
381 // No decimal, no exponent, but there may be a type character to remove
382 mant = getMantissa(str, requestType ? length - 1 : length);
383 }
384 dec = null;
385 }
386 if (requestType) {
387 if (expPos > -1 && expPos < length - 1) {
388 exp = str.substring(expPos + 1, length - 1);
389 } else {
390 exp = null;
391 }
392 //Requesting a specific type.
393 final String numeric = str.substring(0, length - 1);
394 switch (lastChar) {
395 case 'l' :
396 case 'L' :
397 if (dec == null
398 && exp == null
399 && (!numeric.isEmpty() && numeric.charAt(0) == '-' && isDigits(numeric.substring(1)) || isDigits(numeric))) {
400 try {
401 return createLong(numeric);
402 } catch (final NumberFormatException ignored) {
403 // Too big for a long
404 }
405 return createBigInteger(numeric);
406
407 }
408 throw new NumberFormatException(str + " is not a valid number.");
409 case 'f' :
410 case 'F' :
411 try {
412 final Float f = createFloat(str);
413 if (!(f.isInfinite() || f.floatValue() == 0.0F && !isZero(mant, dec))) {
414 //If it's too big for a float or the float value = 0 and the string
415 //has non-zeros in it, then float does not have the precision we want
416 return f;
417 }
418
419 } catch (final NumberFormatException ignored) {
420 // ignore the bad number
421 }
422 //$FALL-THROUGH$
423 case 'd' :
424 case 'D' :
425 try {
426 final Double d = createDouble(str);
427 if (!(d.isInfinite() || d.doubleValue() == 0.0D && !isZero(mant, dec))) {
428 return d;
429 }
430 } catch (final NumberFormatException ignored) {
431 // ignore the bad number
432 }
433 try {
434 return createBigDecimal(numeric);
435 } catch (final NumberFormatException ignored) {
436 // ignore the bad number
437 }
438 //$FALL-THROUGH$
439 default :
440 throw new NumberFormatException(str + " is not a valid number.");
441
442 }
443 }
444 //User doesn't have a preference on the return type, so let's start
445 //small and go from there...
446 if (expPos > -1 && expPos < length - 1) {
447 exp = str.substring(expPos + 1);
448 } else {
449 exp = null;
450 }
451 if (dec == null && exp == null) { // no decimal point and no exponent
452 //Must be an Integer, Long, Biginteger
453 try {
454 return createInteger(str);
455 } catch (final NumberFormatException ignored) {
456 // ignore the bad number
457 }
458 try {
459 return createLong(str);
460 } catch (final NumberFormatException ignored) {
461 // ignore the bad number
462 }
463 return createBigInteger(str);
464 }
465
466 //Must be a Float, Double, BigDecimal
467 try {
468 final Float f = createFloat(str);
469 final Double d = createDouble(str);
470 if (!f.isInfinite()
471 && !(f.floatValue() == 0.0F && !isZero(mant, dec))
472 && f.toString().equals(d.toString())) {
473 return f;
474 }
475 if (!d.isInfinite() && !(d.doubleValue() == 0.0D && !isZero(mant, dec))) {
476 final BigDecimal b = createBigDecimal(str);
477 if (b.compareTo(BigDecimal.valueOf(d.doubleValue())) == 0) {
478 return d;
479 }
480 return b;
481 }
482 } catch (final NumberFormatException ignored) {
483 // ignore the bad number
484 }
485 return createBigDecimal(str);
486 }
487
488 /**
489 * Utility method for {@link #createNumber(java.lang.String)}.
490 *
491 * <p>Returns mantissa of the given number.</p>
492 *
493 * @param str the string representation of the number
494 * @param stopPos the position of the exponent or decimal point
495 * @return mantissa of the given number
496 */
497 private static String getMantissa(final String str, final int stopPos) {
498 final char firstChar = str.charAt(0);
499 final boolean hasSign = firstChar == '-' || firstChar == '+';
500
501 return hasSign ? str.substring(1, stopPos) : str.substring(0, stopPos);
502 }
503
504 /**
505 * Utility method for {@link #createNumber(java.lang.String)}.
506 *
507 * <p>Returns {@code true} if s is {@code null} or empty.</p>
508 *
509 * @param str the String to check
510 * @return if it is all zeros or {@code null}
511 */
512 private static boolean isAllZeros(final String str) {
513 if (str == null) {
514 return true;
515 }
516 for (int i = str.length() - 1; i >= 0; i--) {
517 if (str.charAt(i) != '0') {
518 return false;
519 }
520 }
521 return true;
522 }
523
524 /**
525 * Checks whether the String is a valid Java number.
526 *
527 * <p>Valid numbers include hexadecimal marked with the {@code 0x} or
528 * {@code 0X} qualifier, octal numbers, scientific notation and
529 * numbers marked with a type qualifier (e.g. 123L).</p>
530 *
531 * <p>Non-hexadecimal strings beginning with a leading zero are
532 * treated as octal values. Thus the string {@code 09} will return
533 * {@code false}, since {@code 9} is not a valid octal value.
534 * However, numbers beginning with {@code 0.} are treated as decimal.</p>
535 *
536 * <p>{@code null} and empty/blank {@link String} will return
537 * {@code false}.</p>
538 *
539 * <p>Note, {@link #createNumber(String)} should return a number for every
540 * input resulting in {@code true}.</p>
541 *
542 * @param str the {@link String} to check
543 * @return {@code true} if the string is a correctly formatted number
544 * @since 3.5
545 */
546 public static boolean isCreatable(final String str) {
547 if (StringUtils.isEmpty(str)) {
548 return false;
549 }
550 final char[] chars = str.toCharArray();
551 int sz = chars.length;
552 boolean hasExp = false;
553 boolean hasDecPoint = false;
554 boolean allowSigns = false;
555 boolean foundDigit = false;
556 // deal with any possible sign up front
557 final int start = chars[0] == '-' || chars[0] == '+' ? 1 : 0;
558 if (sz > start + 1 && chars[start] == '0' && !StringUtils.contains(str, '.')) { // leading 0, skip if is a decimal number
559 if (chars[start + 1] == 'x' || chars[start + 1] == 'X') { // leading 0x/0X
560 int i = start + 2;
561 if (i == sz) {
562 return false; // str == "0x"
563 }
564 // checking hex (it can't be anything else)
565 for (; i < chars.length; i++) {
566 if ((chars[i] < '0' || chars[i] > '9')
567 && (chars[i] < 'a' || chars[i] > 'f')
568 && (chars[i] < 'A' || chars[i] > 'F')) {
569 return false;
570 }
571 }
572 return true;
573 }
574 if (Character.isDigit(chars[start + 1])) {
575 // leading 0, but not hex, must be octal
576 int i = start + 1;
577 for (; i < chars.length; i++) {
578 if (chars[i] < '0' || chars[i] > '7') {
579 return false;
580 }
581 }
582 return true;
583 }
584 }
585 sz--; // don't want to loop to the last char, check it afterwards
586 // for type qualifiers
587 int i = start;
588 // loop to the next to last char or to the last char if we need another digit to
589 // make a valid number (e.g. chars[0..5] = "1234E")
590 while (i < sz || i < sz + 1 && allowSigns && !foundDigit) {
591 if (chars[i] >= '0' && chars[i] <= '9') {
592 foundDigit = true;
593 allowSigns = false;
594
595 } else if (chars[i] == '.') {
596 if (hasDecPoint || hasExp) {
597 // two decimal points or dec in exponent
598 return false;
599 }
600 hasDecPoint = true;
601 } else if (chars[i] == 'e' || chars[i] == 'E') {
602 // we've already taken care of hex.
603 if (hasExp) {
604 // two E's
605 return false;
606 }
607 if (!foundDigit) {
608 return false;
609 }
610 hasExp = true;
611 allowSigns = true;
612 } else if (chars[i] == '+' || chars[i] == '-') {
613 if (!allowSigns) {
614 return false;
615 }
616 allowSigns = false;
617 foundDigit = false; // we need a digit after the E
618 } else {
619 return false;
620 }
621 i++;
622 }
623 if (i < chars.length) {
624 if (chars[i] >= '0' && chars[i] <= '9') {
625 // no type qualifier, OK
626 return true;
627 }
628 if (chars[i] == 'e' || chars[i] == 'E') {
629 // can't have an E at the last byte
630 return false;
631 }
632 if (chars[i] == '.') {
633 if (hasDecPoint || hasExp) {
634 // two decimal points or dec in exponent
635 return false;
636 }
637 // single trailing decimal point after non-exponent is ok
638 return foundDigit;
639 }
640 if (!allowSigns
641 && (chars[i] == 'd'
642 || chars[i] == 'D'
643 || chars[i] == 'f'
644 || chars[i] == 'F')) {
645 return foundDigit;
646 }
647 if (chars[i] == 'l'
648 || chars[i] == 'L') {
649 // not allowing L with an exponent or decimal point
650 return foundDigit && !hasExp && !hasDecPoint;
651 }
652 // last character is illegal
653 return false;
654 }
655 // allowSigns is true iff the val ends in 'E'
656 // found digit it to make sure weird stuff like '.' and '1E-' doesn't pass
657 return !allowSigns && foundDigit;
658 }
659
660 /**
661 * Checks whether the {@link String} contains only
662 * digit characters.
663 *
664 * <p>{@code null} and empty String will return
665 * {@code false}.</p>
666 *
667 * @param str the {@link String} to check
668 * @return {@code true} if str contains only Unicode numeric
669 */
670 public static boolean isDigits(final String str) {
671 return StringUtils.isNumeric(str);
672 }
673
674 /**
675 * Checks whether the String is a valid Java number.
676 *
677 * <p>Valid numbers include hexadecimal marked with the {@code 0x} or
678 * {@code 0X} qualifier, octal numbers, scientific notation and
679 * numbers marked with a type qualifier (e.g. 123L).</p>
680 *
681 * <p>Non-hexadecimal strings beginning with a leading zero are
682 * treated as octal values. Thus the string {@code 09} will return
683 * {@code false}, since {@code 9} is not a valid octal value.
684 * However, numbers beginning with {@code 0.} are treated as decimal.</p>
685 *
686 * <p>{@code null} and empty/blank {@link String} will return
687 * {@code false}.</p>
688 *
689 * <p>Note, {@link #createNumber(String)} should return a number for every
690 * input resulting in {@code true}.</p>
691 *
692 * @param str the {@link String} to check
693 * @return {@code true} if the string is a correctly formatted number
694 * @since 3.3 the code supports hexadecimal {@code 0Xhhh} an
695 * octal {@code 0ddd} validation
696 * @deprecated This feature will be removed in Lang 4,
697 * use {@link NumberUtils#isCreatable(String)} instead
698 */
699 @Deprecated
700 public static boolean isNumber(final String str) {
701 return isCreatable(str);
702 }
703
704 /**
705 * Checks whether the given String is a parsable number.
706 *
707 * <p>Parsable numbers include those Strings understood by {@link Integer#parseInt(String)},
708 * {@link Long#parseLong(String)}, {@link Float#parseFloat(String)} or
709 * {@link Double#parseDouble(String)}. This method can be used instead of catching {@link java.text.ParseException}
710 * when calling one of those methods.</p>
711 *
712 * <p>Hexadecimal and scientific notations are <strong>not</strong> considered parsable.
713 * See {@link #isCreatable(String)} on those cases.</p>
714 *
715 * <p>{@code null} and empty String will return {@code false}.</p>
716 *
717 * @param str the String to check.
718 * @return {@code true} if the string is a parsable number.
719 * @since 3.4
720 */
721 public static boolean isParsable(final String str) {
722 if (StringUtils.isEmpty(str)) {
723 return false;
724 }
725 if (str.charAt(str.length() - 1) == '.') {
726 return false;
727 }
728 if (str.charAt(0) == '-') {
729 if (str.length() == 1) {
730 return false;
731 }
732 return withDecimalsParsing(str, 1);
733 }
734 return withDecimalsParsing(str, 0);
735 }
736
737 /**
738 * Utility method for {@link #createNumber(java.lang.String)}.
739 *
740 * <p>This will check if the magnitude of the number is zero by checking if there
741 * are only zeros before and after the decimal place.</p>
742 *
743 * <p>Note: It is <strong>assumed</strong> that the input string has been converted
744 * to either a Float or Double with a value of zero when this method is called.
745 * This eliminates invalid input for example {@code ".", ".D", ".e0"}.</p>
746 *
747 * <p>Thus the method only requires checking if both arguments are null, empty or
748 * contain only zeros.</p>
749 *
750 * <p>Given {@code s = mant + "." + dec}:</p>
751 * <ul>
752 * <li>{@code true} if s is {@code "0.0"}
753 * <li>{@code true} if s is {@code "0."}
754 * <li>{@code true} if s is {@code ".0"}
755 * <li>{@code false} otherwise (this assumes {@code "."} is not possible)
756 * </ul>
757 *
758 * @param mant the mantissa decimal digits before the decimal point (sign must be removed; never null)
759 * @param dec the decimal digits after the decimal point (exponent and type specifier removed;
760 * can be null)
761 * @return true if the magnitude is zero
762 */
763 private static boolean isZero(final String mant, final String dec) {
764 return isAllZeros(mant) && isAllZeros(dec);
765 }
766
767 /**
768 * Returns the maximum value in an array.
769 *
770 * @param array an array, must not be null or empty
771 * @return the maximum value in the array
772 * @throws NullPointerException if {@code array} is {@code null}
773 * @throws IllegalArgumentException if {@code array} is empty
774 * @since 3.4 Changed signature from max(byte[]) to max(byte...)
775 */
776 public static byte max(final byte... array) {
777 // Validates input
778 validateArray(array);
779
780 // Finds and returns max
781 byte max = array[0];
782 for (int i = 1; i < array.length; i++) {
783 if (array[i] > max) {
784 max = array[i];
785 }
786 }
787
788 return max;
789 }
790
791 /**
792 * Gets the maximum of three {@code byte} values.
793 *
794 * @param a value 1
795 * @param b value 2
796 * @param c value 3
797 * @return the largest of the values
798 */
799 public static byte max(byte a, final byte b, final byte c) {
800 if (b > a) {
801 a = b;
802 }
803 if (c > a) {
804 a = c;
805 }
806 return a;
807 }
808
809 /**
810 * Returns the maximum value in an array.
811 *
812 * @param array an array, must not be null or empty
813 * @return the maximum value in the array
814 * @throws NullPointerException if {@code array} is {@code null}
815 * @throws IllegalArgumentException if {@code array} is empty
816 * @see IEEE754rUtils#max(double[]) IEEE754rUtils for a version of this method that handles NaN differently
817 * @since 3.4 Changed signature from max(double[]) to max(double...)
818 */
819 public static double max(final double... array) {
820 // Validates input
821 validateArray(array);
822
823 // Finds and returns max
824 double max = array[0];
825 for (int j = 1; j < array.length; j++) {
826 if (Double.isNaN(array[j])) {
827 return Double.NaN;
828 }
829 if (array[j] > max) {
830 max = array[j];
831 }
832 }
833
834 return max;
835 }
836
837 /**
838 * Gets the maximum of three {@code double} values.
839 *
840 * <p>If any value is {@code NaN}, {@code NaN} is
841 * returned. Infinity is handled.</p>
842 *
843 * @param a value 1
844 * @param b value 2
845 * @param c value 3
846 * @return the largest of the values
847 * @see IEEE754rUtils#max(double, double, double) for a version of this method that handles NaN differently
848 */
849 public static double max(final double a, final double b, final double c) {
850 return Math.max(Math.max(a, b), c);
851 }
852
853 /**
854 * Returns the maximum value in an array.
855 *
856 * @param array an array, must not be null or empty
857 * @return the maximum value in the array
858 * @throws NullPointerException if {@code array} is {@code null}
859 * @throws IllegalArgumentException if {@code array} is empty
860 * @see IEEE754rUtils#max(float[]) IEEE754rUtils for a version of this method that handles NaN differently
861 * @since 3.4 Changed signature from max(float[]) to max(float...)
862 */
863 public static float max(final float... array) {
864 // Validates input
865 validateArray(array);
866
867 // Finds and returns max
868 float max = array[0];
869 for (int j = 1; j < array.length; j++) {
870 if (Float.isNaN(array[j])) {
871 return Float.NaN;
872 }
873 if (array[j] > max) {
874 max = array[j];
875 }
876 }
877
878 return max;
879 }
880
881 // must handle Long, Float, Integer, Float, Short,
882 // BigDecimal, BigInteger and Byte
883 // useful methods:
884 // Byte.decode(String)
885 // Byte.valueOf(String, int radix)
886 // Byte.valueOf(String)
887 // Double.valueOf(String)
888 // Float.valueOf(String)
889 // Float.valueOf(String)
890 // Integer.valueOf(String, int radix)
891 // Integer.valueOf(String)
892 // Integer.decode(String)
893 // Integer.getInteger(String)
894 // Integer.getInteger(String, int val)
895 // Integer.getInteger(String, Integer val)
896 // Integer.valueOf(String)
897 // Double.valueOf(String)
898 // new Byte(String)
899 // Long.valueOf(String)
900 // Long.getLong(String)
901 // Long.getLong(String, int)
902 // Long.getLong(String, Integer)
903 // Long.valueOf(String, int)
904 // Long.valueOf(String)
905 // Short.valueOf(String)
906 // Short.decode(String)
907 // Short.valueOf(String, int)
908 // Short.valueOf(String)
909 // new BigDecimal(String)
910 // new BigInteger(String)
911 // new BigInteger(String, int radix)
912 // Possible inputs:
913 // 45 45.5 45E7 4.5E7 Hex Oct Binary xxxF xxxD xxxf xxxd
914 // plus minus everything. Prolly more. A lot are not separable.
915
916 /**
917 * Gets the maximum of three {@code float} values.
918 *
919 * <p>If any value is {@code NaN}, {@code NaN} is
920 * returned. Infinity is handled.</p>
921 *
922 * @param a value 1
923 * @param b value 2
924 * @param c value 3
925 * @return the largest of the values
926 * @see IEEE754rUtils#max(float, float, float) for a version of this method that handles NaN differently
927 */
928 public static float max(final float a, final float b, final float c) {
929 return Math.max(Math.max(a, b), c);
930 }
931
932 /**
933 * Returns the maximum value in an array.
934 *
935 * @param array an array, must not be null or empty
936 * @return the maximum value in the array
937 * @throws NullPointerException if {@code array} is {@code null}
938 * @throws IllegalArgumentException if {@code array} is empty
939 * @since 3.4 Changed signature from max(int[]) to max(int...)
940 */
941 public static int max(final int... array) {
942 // Validates input
943 validateArray(array);
944
945 // Finds and returns max
946 int max = array[0];
947 for (int j = 1; j < array.length; j++) {
948 if (array[j] > max) {
949 max = array[j];
950 }
951 }
952
953 return max;
954 }
955
956 /**
957 * Gets the maximum of three {@code int} values.
958 *
959 * @param a value 1
960 * @param b value 2
961 * @param c value 3
962 * @return the largest of the values
963 */
964 public static int max(int a, final int b, final int c) {
965 if (b > a) {
966 a = b;
967 }
968 if (c > a) {
969 a = c;
970 }
971 return a;
972 }
973
974 /**
975 * Returns the maximum value in an array.
976 *
977 * @param array an array, must not be null or empty
978 * @return the maximum value in the array
979 * @throws NullPointerException if {@code array} is {@code null}
980 * @throws IllegalArgumentException if {@code array} is empty
981 * @since 3.4 Changed signature from max(long[]) to max(long...)
982 */
983 public static long max(final long... array) {
984 // Validates input
985 validateArray(array);
986
987 // Finds and returns max
988 long max = array[0];
989 for (int j = 1; j < array.length; j++) {
990 if (array[j] > max) {
991 max = array[j];
992 }
993 }
994
995 return max;
996 }
997
998 // 3 param max
999 /**
1000 * Gets the maximum of three {@code long} values.
1001 *
1002 * @param a value 1
1003 * @param b value 2
1004 * @param c value 3
1005 * @return the largest of the values
1006 */
1007 public static long max(long a, final long b, final long c) {
1008 if (b > a) {
1009 a = b;
1010 }
1011 if (c > a) {
1012 a = c;
1013 }
1014 return a;
1015 }
1016
1017 /**
1018 * Returns the maximum value in an array.
1019 *
1020 * @param array an array, must not be null or empty
1021 * @return the maximum value in the array
1022 * @throws NullPointerException if {@code array} is {@code null}
1023 * @throws IllegalArgumentException if {@code array} is empty
1024 * @since 3.4 Changed signature from max(short[]) to max(short...)
1025 */
1026 public static short max(final short... array) {
1027 // Validates input
1028 validateArray(array);
1029
1030 // Finds and returns max
1031 short max = array[0];
1032 for (int i = 1; i < array.length; i++) {
1033 if (array[i] > max) {
1034 max = array[i];
1035 }
1036 }
1037
1038 return max;
1039 }
1040
1041 /**
1042 * Gets the maximum of three {@code short} values.
1043 *
1044 * @param a value 1
1045 * @param b value 2
1046 * @param c value 3
1047 * @return the largest of the values
1048 */
1049 public static short max(short a, final short b, final short c) {
1050 if (b > a) {
1051 a = b;
1052 }
1053 if (c > a) {
1054 a = c;
1055 }
1056 return a;
1057 }
1058
1059 /**
1060 * Returns the minimum value in an array.
1061 *
1062 * @param array an array, must not be null or empty
1063 * @return the minimum value in the array
1064 * @throws NullPointerException if {@code array} is {@code null}
1065 * @throws IllegalArgumentException if {@code array} is empty
1066 * @since 3.4 Changed signature from min(byte[]) to min(byte...)
1067 */
1068 public static byte min(final byte... array) {
1069 // Validates input
1070 validateArray(array);
1071
1072 // Finds and returns min
1073 byte min = array[0];
1074 for (int i = 1; i < array.length; i++) {
1075 if (array[i] < min) {
1076 min = array[i];
1077 }
1078 }
1079
1080 return min;
1081 }
1082
1083 /**
1084 * Gets the minimum of three {@code byte} values.
1085 *
1086 * @param a value 1
1087 * @param b value 2
1088 * @param c value 3
1089 * @return the smallest of the values
1090 */
1091 public static byte min(byte a, final byte b, final byte c) {
1092 if (b < a) {
1093 a = b;
1094 }
1095 if (c < a) {
1096 a = c;
1097 }
1098 return a;
1099 }
1100
1101 /**
1102 * Returns the minimum value in an array.
1103 *
1104 * @param array an array, must not be null or empty
1105 * @return the minimum value in the array
1106 * @throws NullPointerException if {@code array} is {@code null}
1107 * @throws IllegalArgumentException if {@code array} is empty
1108 * @see IEEE754rUtils#min(double[]) IEEE754rUtils for a version of this method that handles NaN differently
1109 * @since 3.4 Changed signature from min(double[]) to min(double...)
1110 */
1111 public static double min(final double... array) {
1112 // Validates input
1113 validateArray(array);
1114
1115 // Finds and returns min
1116 double min = array[0];
1117 for (int i = 1; i < array.length; i++) {
1118 if (Double.isNaN(array[i])) {
1119 return Double.NaN;
1120 }
1121 if (array[i] < min) {
1122 min = array[i];
1123 }
1124 }
1125
1126 return min;
1127 }
1128
1129 /**
1130 * Gets the minimum of three {@code double} values.
1131 *
1132 * <p>If any value is {@code NaN}, {@code NaN} is
1133 * returned. Infinity is handled.</p>
1134 *
1135 * @param a value 1
1136 * @param b value 2
1137 * @param c value 3
1138 * @return the smallest of the values
1139 * @see IEEE754rUtils#min(double, double, double) for a version of this method that handles NaN differently
1140 */
1141 public static double min(final double a, final double b, final double c) {
1142 return Math.min(Math.min(a, b), c);
1143 }
1144
1145 /**
1146 * Returns the minimum value in an array.
1147 *
1148 * @param array an array, must not be null or empty
1149 * @return the minimum value in the array
1150 * @throws NullPointerException if {@code array} is {@code null}
1151 * @throws IllegalArgumentException if {@code array} is empty
1152 * @see IEEE754rUtils#min(float[]) IEEE754rUtils for a version of this method that handles NaN differently
1153 * @since 3.4 Changed signature from min(float[]) to min(float...)
1154 */
1155 public static float min(final float... array) {
1156 // Validates input
1157 validateArray(array);
1158
1159 // Finds and returns min
1160 float min = array[0];
1161 for (int i = 1; i < array.length; i++) {
1162 if (Float.isNaN(array[i])) {
1163 return Float.NaN;
1164 }
1165 if (array[i] < min) {
1166 min = array[i];
1167 }
1168 }
1169
1170 return min;
1171 }
1172
1173 /**
1174 * Gets the minimum of three {@code float} values.
1175 *
1176 * <p>If any value is {@code NaN}, {@code NaN} is
1177 * returned. Infinity is handled.</p>
1178 *
1179 * @param a value 1
1180 * @param b value 2
1181 * @param c value 3
1182 * @return the smallest of the values
1183 * @see IEEE754rUtils#min(float, float, float) for a version of this method that handles NaN differently
1184 */
1185 public static float min(final float a, final float b, final float c) {
1186 return Math.min(Math.min(a, b), c);
1187 }
1188
1189 /**
1190 * Returns the minimum value in an array.
1191 *
1192 * @param array an array, must not be null or empty
1193 * @return the minimum value in the array
1194 * @throws NullPointerException if {@code array} is {@code null}
1195 * @throws IllegalArgumentException if {@code array} is empty
1196 * @since 3.4 Changed signature from min(int[]) to min(int...)
1197 */
1198 public static int min(final int... array) {
1199 // Validates input
1200 validateArray(array);
1201
1202 // Finds and returns min
1203 int min = array[0];
1204 for (int j = 1; j < array.length; j++) {
1205 if (array[j] < min) {
1206 min = array[j];
1207 }
1208 }
1209
1210 return min;
1211 }
1212
1213 /**
1214 * Gets the minimum of three {@code int} values.
1215 *
1216 * @param a value 1
1217 * @param b value 2
1218 * @param c value 3
1219 * @return the smallest of the values
1220 */
1221 public static int min(int a, final int b, final int c) {
1222 if (b < a) {
1223 a = b;
1224 }
1225 if (c < a) {
1226 a = c;
1227 }
1228 return a;
1229 }
1230
1231 /**
1232 * Returns the minimum value in an array.
1233 *
1234 * @param array an array, must not be null or empty
1235 * @return the minimum value in the array
1236 * @throws NullPointerException if {@code array} is {@code null}
1237 * @throws IllegalArgumentException if {@code array} is empty
1238 * @since 3.4 Changed signature from min(long[]) to min(long...)
1239 */
1240 public static long min(final long... array) {
1241 // Validates input
1242 validateArray(array);
1243
1244 // Finds and returns min
1245 long min = array[0];
1246 for (int i = 1; i < array.length; i++) {
1247 if (array[i] < min) {
1248 min = array[i];
1249 }
1250 }
1251
1252 return min;
1253 }
1254
1255 // 3 param min
1256 /**
1257 * Gets the minimum of three {@code long} values.
1258 *
1259 * @param a value 1
1260 * @param b value 2
1261 * @param c value 3
1262 * @return the smallest of the values
1263 */
1264 public static long min(long a, final long b, final long c) {
1265 if (b < a) {
1266 a = b;
1267 }
1268 if (c < a) {
1269 a = c;
1270 }
1271 return a;
1272 }
1273
1274 /**
1275 * Returns the minimum value in an array.
1276 *
1277 * @param array an array, must not be null or empty
1278 * @return the minimum value in the array
1279 * @throws NullPointerException if {@code array} is {@code null}
1280 * @throws IllegalArgumentException if {@code array} is empty
1281 * @since 3.4 Changed signature from min(short[]) to min(short...)
1282 */
1283 public static short min(final short... array) {
1284 // Validates input
1285 validateArray(array);
1286
1287 // Finds and returns min
1288 short min = array[0];
1289 for (int i = 1; i < array.length; i++) {
1290 if (array[i] < min) {
1291 min = array[i];
1292 }
1293 }
1294
1295 return min;
1296 }
1297
1298 /**
1299 * Gets the minimum of three {@code short} values.
1300 *
1301 * @param a value 1
1302 * @param b value 2
1303 * @param c value 3
1304 * @return the smallest of the values
1305 */
1306 public static short min(short a, final short b, final short c) {
1307 if (b < a) {
1308 a = b;
1309 }
1310 if (c < a) {
1311 a = c;
1312 }
1313 return a;
1314 }
1315
1316 /**
1317 * Convert a {@link String} to a {@code byte}, returning
1318 * {@code zero} if the conversion fails.
1319 *
1320 * <p>If the string is {@code null}, {@code zero} is returned.</p>
1321 *
1322 * <pre>
1323 * NumberUtils.toByte(null) = 0
1324 * NumberUtils.toByte("") = 0
1325 * NumberUtils.toByte("1") = 1
1326 * </pre>
1327 *
1328 * @param str the string to convert, may be null
1329 * @return the byte represented by the string, or {@code zero} if
1330 * conversion fails
1331 * @since 2.5
1332 */
1333 public static byte toByte(final String str) {
1334 return toByte(str, (byte) 0);
1335 }
1336
1337 /**
1338 * Convert a {@link String} to a {@code byte}, returning a
1339 * default value if the conversion fails.
1340 *
1341 * <p>If the string is {@code null}, the default value is returned.</p>
1342 *
1343 * <pre>
1344 * NumberUtils.toByte(null, 1) = 1
1345 * NumberUtils.toByte("", 1) = 1
1346 * NumberUtils.toByte("1", 0) = 1
1347 * </pre>
1348 *
1349 * @param str the string to convert, may be null
1350 * @param defaultValue the default value
1351 * @return the byte represented by the string, or the default if conversion fails
1352 * @since 2.5
1353 */
1354 public static byte toByte(final String str, final byte defaultValue) {
1355 if (str == null) {
1356 return defaultValue;
1357 }
1358 try {
1359 return Byte.parseByte(str);
1360 } catch (final NumberFormatException nfe) {
1361 return defaultValue;
1362 }
1363 }
1364
1365 /**
1366 * Convert a {@link BigDecimal} to a {@code double}.
1367 *
1368 * <p>If the {@link BigDecimal} {@code value} is
1369 * {@code null}, then the specified default value is returned.</p>
1370 *
1371 * <pre>
1372 * NumberUtils.toDouble(null) = 0.0d
1373 * NumberUtils.toDouble(BigDecimal.valueOf(8.5d)) = 8.5d
1374 * </pre>
1375 *
1376 * @param value the {@link BigDecimal} to convert, may be {@code null}.
1377 * @return the double represented by the {@link BigDecimal} or
1378 * {@code 0.0d} if the {@link BigDecimal} is {@code null}.
1379 * @since 3.8
1380 */
1381 public static double toDouble(final BigDecimal value) {
1382 return toDouble(value, 0.0d);
1383 }
1384
1385 /**
1386 * Convert a {@link BigDecimal} to a {@code double}.
1387 *
1388 * <p>If the {@link BigDecimal} {@code value} is
1389 * {@code null}, then the specified default value is returned.</p>
1390 *
1391 * <pre>
1392 * NumberUtils.toDouble(null, 1.1d) = 1.1d
1393 * NumberUtils.toDouble(BigDecimal.valueOf(8.5d), 1.1d) = 8.5d
1394 * </pre>
1395 *
1396 * @param value the {@link BigDecimal} to convert, may be {@code null}.
1397 * @param defaultValue the default value
1398 * @return the double represented by the {@link BigDecimal} or the
1399 * defaultValue if the {@link BigDecimal} is {@code null}.
1400 * @since 3.8
1401 */
1402 public static double toDouble(final BigDecimal value, final double defaultValue) {
1403 return value == null ? defaultValue : value.doubleValue();
1404 }
1405
1406 /**
1407 * Convert a {@link String} to a {@code double}, returning
1408 * {@code 0.0d} if the conversion fails.
1409 *
1410 * <p>If the string {@code str} is {@code null},
1411 * {@code 0.0d} is returned.</p>
1412 *
1413 * <pre>
1414 * NumberUtils.toDouble(null) = 0.0d
1415 * NumberUtils.toDouble("") = 0.0d
1416 * NumberUtils.toDouble("1.5") = 1.5d
1417 * </pre>
1418 *
1419 * @param str the string to convert, may be {@code null}
1420 * @return the double represented by the string, or {@code 0.0d}
1421 * if conversion fails
1422 * @since 2.1
1423 */
1424 public static double toDouble(final String str) {
1425 return toDouble(str, 0.0d);
1426 }
1427
1428 /**
1429 * Convert a {@link String} to a {@code double}, returning a
1430 * default value if the conversion fails.
1431 *
1432 * <p>If the string {@code str} is {@code null}, the default
1433 * value is returned.</p>
1434 *
1435 * <pre>
1436 * NumberUtils.toDouble(null, 1.1d) = 1.1d
1437 * NumberUtils.toDouble("", 1.1d) = 1.1d
1438 * NumberUtils.toDouble("1.5", 0.0d) = 1.5d
1439 * </pre>
1440 *
1441 * @param str the string to convert, may be {@code null}
1442 * @param defaultValue the default value
1443 * @return the double represented by the string, or defaultValue
1444 * if conversion fails
1445 * @since 2.1
1446 */
1447 public static double toDouble(final String str, final double defaultValue) {
1448 if (str == null) {
1449 return defaultValue;
1450 }
1451 try {
1452 return Double.parseDouble(str);
1453 } catch (final NumberFormatException nfe) {
1454 return defaultValue;
1455 }
1456 }
1457
1458 /**
1459 * Convert a {@link String} to a {@code float}, returning
1460 * {@code 0.0f} if the conversion fails.
1461 *
1462 * <p>If the string {@code str} is {@code null},
1463 * {@code 0.0f} is returned.</p>
1464 *
1465 * <pre>
1466 * NumberUtils.toFloat(null) = 0.0f
1467 * NumberUtils.toFloat("") = 0.0f
1468 * NumberUtils.toFloat("1.5") = 1.5f
1469 * </pre>
1470 *
1471 * @param str the string to convert, may be {@code null}
1472 * @return the float represented by the string, or {@code 0.0f}
1473 * if conversion fails
1474 * @since 2.1
1475 */
1476 public static float toFloat(final String str) {
1477 return toFloat(str, 0.0f);
1478 }
1479
1480 /**
1481 * Convert a {@link String} to a {@code float}, returning a
1482 * default value if the conversion fails.
1483 *
1484 * <p>If the string {@code str} is {@code null}, the default
1485 * value is returned.</p>
1486 *
1487 * <pre>
1488 * NumberUtils.toFloat(null, 1.1f) = 1.0f
1489 * NumberUtils.toFloat("", 1.1f) = 1.1f
1490 * NumberUtils.toFloat("1.5", 0.0f) = 1.5f
1491 * </pre>
1492 *
1493 * @param str the string to convert, may be {@code null}
1494 * @param defaultValue the default value
1495 * @return the float represented by the string, or defaultValue
1496 * if conversion fails
1497 * @since 2.1
1498 */
1499 public static float toFloat(final String str, final float defaultValue) {
1500 if (str == null) {
1501 return defaultValue;
1502 }
1503 try {
1504 return Float.parseFloat(str);
1505 } catch (final NumberFormatException nfe) {
1506 return defaultValue;
1507 }
1508 }
1509
1510 /**
1511 * Convert a {@link String} to an {@code int}, returning
1512 * {@code zero} if the conversion fails.
1513 *
1514 * <p>If the string is {@code null}, {@code zero} is returned.</p>
1515 *
1516 * <pre>
1517 * NumberUtils.toInt(null) = 0
1518 * NumberUtils.toInt("") = 0
1519 * NumberUtils.toInt("1") = 1
1520 * </pre>
1521 *
1522 * @param str the string to convert, may be null
1523 * @return the int represented by the string, or {@code zero} if
1524 * conversion fails
1525 * @since 2.1
1526 */
1527 public static int toInt(final String str) {
1528 return toInt(str, 0);
1529 }
1530
1531 /**
1532 * Convert a {@link String} to an {@code int}, returning a
1533 * default value if the conversion fails.
1534 *
1535 * <p>If the string is {@code null}, the default value is returned.</p>
1536 *
1537 * <pre>
1538 * NumberUtils.toInt(null, 1) = 1
1539 * NumberUtils.toInt("", 1) = 1
1540 * NumberUtils.toInt("1", 0) = 1
1541 * </pre>
1542 *
1543 * @param str the string to convert, may be null
1544 * @param defaultValue the default value
1545 * @return the int represented by the string, or the default if conversion fails
1546 * @since 2.1
1547 */
1548 public static int toInt(final String str, final int defaultValue) {
1549 if (str == null) {
1550 return defaultValue;
1551 }
1552 try {
1553 return Integer.parseInt(str);
1554 } catch (final NumberFormatException nfe) {
1555 return defaultValue;
1556 }
1557 }
1558
1559 /**
1560 * Convert a {@link String} to a {@code long}, returning
1561 * {@code zero} if the conversion fails.
1562 *
1563 * <p>If the string is {@code null}, {@code zero} is returned.</p>
1564 *
1565 * <pre>
1566 * NumberUtils.toLong(null) = 0L
1567 * NumberUtils.toLong("") = 0L
1568 * NumberUtils.toLong("1") = 1L
1569 * </pre>
1570 *
1571 * @param str the string to convert, may be null
1572 * @return the long represented by the string, or {@code 0} if
1573 * conversion fails
1574 * @since 2.1
1575 */
1576 public static long toLong(final String str) {
1577 return toLong(str, 0L);
1578 }
1579
1580 /**
1581 * Convert a {@link String} to a {@code long}, returning a
1582 * default value if the conversion fails.
1583 *
1584 * <p>If the string is {@code null}, the default value is returned.</p>
1585 *
1586 * <pre>
1587 * NumberUtils.toLong(null, 1L) = 1L
1588 * NumberUtils.toLong("", 1L) = 1L
1589 * NumberUtils.toLong("1", 0L) = 1L
1590 * </pre>
1591 *
1592 * @param str the string to convert, may be null
1593 * @param defaultValue the default value
1594 * @return the long represented by the string, or the default if conversion fails
1595 * @since 2.1
1596 */
1597 public static long toLong(final String str, final long defaultValue) {
1598 if (str == null) {
1599 return defaultValue;
1600 }
1601 try {
1602 return Long.parseLong(str);
1603 } catch (final NumberFormatException nfe) {
1604 return defaultValue;
1605 }
1606 }
1607
1608 /**
1609 * Convert a {@link BigDecimal} to a {@link BigDecimal} with a scale of
1610 * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
1611 * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
1612 *
1613 * <p>Note, the scale of a {@link BigDecimal} is the number of digits to the right of the
1614 * decimal point.</p>
1615 *
1616 * @param value the {@link BigDecimal} to convert, may be null.
1617 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1618 * @since 3.8
1619 */
1620 public static BigDecimal toScaledBigDecimal(final BigDecimal value) {
1621 return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
1622 }
1623
1624 /**
1625 * Convert a {@link BigDecimal} to a {@link BigDecimal} whose scale is the
1626 * specified value with a {@link RoundingMode} applied. If the input {@code value}
1627 * is {@code null}, we simply return {@code BigDecimal.ZERO}.
1628 *
1629 * @param value the {@link BigDecimal} to convert, may be null.
1630 * @param scale the number of digits to the right of the decimal point.
1631 * @param roundingMode a rounding behavior for numerical operations capable of
1632 * discarding precision.
1633 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1634 * @since 3.8
1635 */
1636 public static BigDecimal toScaledBigDecimal(final BigDecimal value, final int scale, final RoundingMode roundingMode) {
1637 if (value == null) {
1638 return BigDecimal.ZERO;
1639 }
1640 return value.setScale(
1641 scale,
1642 roundingMode == null ? RoundingMode.HALF_EVEN : roundingMode
1643 );
1644 }
1645
1646 /**
1647 * Convert a {@link Double} to a {@link BigDecimal} with a scale of
1648 * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
1649 * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
1650 *
1651 * <p>Note, the scale of a {@link BigDecimal} is the number of digits to the right of the
1652 * decimal point.</p>
1653 *
1654 * @param value the {@link Double} to convert, may be null.
1655 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1656 * @since 3.8
1657 */
1658 public static BigDecimal toScaledBigDecimal(final Double value) {
1659 return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
1660 }
1661
1662 /**
1663 * Convert a {@link Double} to a {@link BigDecimal} whose scale is the
1664 * specified value with a {@link RoundingMode} applied. If the input {@code value}
1665 * is {@code null}, we simply return {@code BigDecimal.ZERO}.
1666 *
1667 * @param value the {@link Double} to convert, may be null.
1668 * @param scale the number of digits to the right of the decimal point.
1669 * @param roundingMode a rounding behavior for numerical operations capable of
1670 * discarding precision.
1671 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1672 * @since 3.8
1673 */
1674 public static BigDecimal toScaledBigDecimal(final Double value, final int scale, final RoundingMode roundingMode) {
1675 if (value == null) {
1676 return BigDecimal.ZERO;
1677 }
1678 return toScaledBigDecimal(
1679 BigDecimal.valueOf(value),
1680 scale,
1681 roundingMode
1682 );
1683 }
1684
1685 /**
1686 * Convert a {@link Float} to a {@link BigDecimal} with a scale of
1687 * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
1688 * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
1689 *
1690 * <p>Note, the scale of a {@link BigDecimal} is the number of digits to the right of the
1691 * decimal point.</p>
1692 *
1693 * @param value the {@link Float} to convert, may be null.
1694 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1695 * @since 3.8
1696 */
1697 public static BigDecimal toScaledBigDecimal(final Float value) {
1698 return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
1699 }
1700
1701 /**
1702 * Convert a {@link Float} to a {@link BigDecimal} whose scale is the
1703 * specified value with a {@link RoundingMode} applied. If the input {@code value}
1704 * is {@code null}, we simply return {@code BigDecimal.ZERO}.
1705 *
1706 * @param value the {@link Float} to convert, may be null.
1707 * @param scale the number of digits to the right of the decimal point.
1708 * @param roundingMode a rounding behavior for numerical operations capable of
1709 * discarding precision.
1710 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1711 * @since 3.8
1712 */
1713 public static BigDecimal toScaledBigDecimal(final Float value, final int scale, final RoundingMode roundingMode) {
1714 if (value == null) {
1715 return BigDecimal.ZERO;
1716 }
1717 return toScaledBigDecimal(
1718 BigDecimal.valueOf(value),
1719 scale,
1720 roundingMode
1721 );
1722 }
1723
1724 /**
1725 * Convert a {@link String} to a {@link BigDecimal} with a scale of
1726 * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
1727 * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
1728 *
1729 * <p>Note, the scale of a {@link BigDecimal} is the number of digits to the right of the
1730 * decimal point.</p>
1731 *
1732 * @param value the {@link String} to convert, may be null.
1733 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1734 * @since 3.8
1735 */
1736 public static BigDecimal toScaledBigDecimal(final String value) {
1737 return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
1738 }
1739
1740 /**
1741 * Convert a {@link String} to a {@link BigDecimal} whose scale is the
1742 * specified value with a {@link RoundingMode} applied. If the input {@code value}
1743 * is {@code null}, we simply return {@code BigDecimal.ZERO}.
1744 *
1745 * @param value the {@link String} to convert, may be null.
1746 * @param scale the number of digits to the right of the decimal point.
1747 * @param roundingMode a rounding behavior for numerical operations capable of
1748 * discarding precision.
1749 * @return the scaled, with appropriate rounding, {@link BigDecimal}.
1750 * @since 3.8
1751 */
1752 public static BigDecimal toScaledBigDecimal(final String value, final int scale, final RoundingMode roundingMode) {
1753 if (value == null) {
1754 return BigDecimal.ZERO;
1755 }
1756 return toScaledBigDecimal(
1757 createBigDecimal(value),
1758 scale,
1759 roundingMode
1760 );
1761 }
1762
1763 /**
1764 * Convert a {@link String} to a {@code short}, returning
1765 * {@code zero} if the conversion fails.
1766 *
1767 * <p>If the string is {@code null}, {@code zero} is returned.</p>
1768 *
1769 * <pre>
1770 * NumberUtils.toShort(null) = 0
1771 * NumberUtils.toShort("") = 0
1772 * NumberUtils.toShort("1") = 1
1773 * </pre>
1774 *
1775 * @param str the string to convert, may be null
1776 * @return the short represented by the string, or {@code zero} if
1777 * conversion fails
1778 * @since 2.5
1779 */
1780 public static short toShort(final String str) {
1781 return toShort(str, (short) 0);
1782 }
1783
1784 /**
1785 * Convert a {@link String} to an {@code short}, returning a
1786 * default value if the conversion fails.
1787 *
1788 * <p>If the string is {@code null}, the default value is returned.</p>
1789 *
1790 * <pre>
1791 * NumberUtils.toShort(null, 1) = 1
1792 * NumberUtils.toShort("", 1) = 1
1793 * NumberUtils.toShort("1", 0) = 1
1794 * </pre>
1795 *
1796 * @param str the string to convert, may be null
1797 * @param defaultValue the default value
1798 * @return the short represented by the string, or the default if conversion fails
1799 * @since 2.5
1800 */
1801 public static short toShort(final String str, final short defaultValue) {
1802 if (str == null) {
1803 return defaultValue;
1804 }
1805 try {
1806 return Short.parseShort(str);
1807 } catch (final NumberFormatException nfe) {
1808 return defaultValue;
1809 }
1810 }
1811
1812 /**
1813 * Checks if the specified array is neither null nor empty.
1814 *
1815 * @param array the array to check
1816 * @throws IllegalArgumentException if {@code array} is empty
1817 * @throws NullPointerException if {@code array} is {@code null}
1818 */
1819 private static void validateArray(final Object array) {
1820 Objects.requireNonNull(array, "array");
1821 Validate.isTrue(Array.getLength(array) != 0, "Array cannot be empty.");
1822 }
1823
1824 private static boolean withDecimalsParsing(final String str, final int beginIdx) {
1825 int decimalPoints = 0;
1826 for (int i = beginIdx; i < str.length(); i++) {
1827 final boolean isDecimalPoint = str.charAt(i) == '.';
1828 if (isDecimalPoint) {
1829 decimalPoints++;
1830 }
1831 if (decimalPoints > 1) {
1832 return false;
1833 }
1834 if (!isDecimalPoint && !Character.isDigit(str.charAt(i))) {
1835 return false;
1836 }
1837 }
1838 return true;
1839 }
1840
1841 /**
1842 * {@link NumberUtils} instances should NOT be constructed in standard programming.
1843 * Instead, the class should be used as {@code NumberUtils.toInt("6");}.
1844 *
1845 * <p>This constructor is public to permit tools that require a JavaBean instance
1846 * to operate.</p>
1847 */
1848 public NumberUtils() {
1849 }
1850 }