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