Package org.apache.commons.lang3.math

# Class NumberUtils

java.lang.Object
org.apache.commons.lang3.math.NumberUtils

public class NumberUtils extends Object
Provides extra functionality for Java Number classes.

Since:
  2.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Byte`
  `BYTE_MINUS_ONE`
  Reusable Byte constant for minus one.
  `static final Byte`
  `BYTE_ONE`
  Reusable Byte constant for one.
  `static final Byte`
  `BYTE_ZERO`
  Reusable Byte constant for zero.
  `static final Double`
  `DOUBLE_MINUS_ONE`
  Reusable Double constant for minus one.
  `static final Double`
  `DOUBLE_ONE`
  Reusable Double constant for one.
  `static final Double`
  `DOUBLE_ZERO`
  Reusable Double constant for zero.
  `static final Float`
  `FLOAT_MINUS_ONE`
  Reusable Float constant for minus one.
  `static final Float`
  `FLOAT_ONE`
  Reusable Float constant for one.
  `static final Float`
  `FLOAT_ZERO`
  Reusable Float constant for zero.
  `static final Integer`
  `INTEGER_MINUS_ONE`
  Reusable Integer constant for minus one.
  `static final Integer`
  `INTEGER_ONE`
  Reusable Integer constant for one.
  `static final Integer`
  `INTEGER_TWO`
  Reusable Integer constant for two
  `static final Integer`
  `INTEGER_ZERO`
  Reusable Integer constant for zero.
  `static final Long`
  `LONG_INT_MAX_VALUE`
  `Integer.MAX_VALUE` as a `Long`.
  `static final Long`
  `LONG_INT_MIN_VALUE`
  `Integer.MIN_VALUE` as a `Long`.
  `static final Long`
  `LONG_MINUS_ONE`
  Reusable Long constant for minus one.
  `static final Long`
  `LONG_ONE`
  Reusable Long constant for one.
  `static final Long`
  `LONG_ZERO`
  Reusable Long constant for zero.
  `static final Short`
  `SHORT_MINUS_ONE`
  Reusable Short constant for minus one.
  `static final Short`
  `SHORT_ONE`
  Reusable Short constant for one.
  `static final Short`
  `SHORT_ZERO`
  Reusable Short constant for zero.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NumberUtils()`
  `NumberUtils` instances should NOT be constructed in standard programming.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `compare(byte x, byte y)`
  Compares two `byte` values numerically.
  `static int`
  `compare(int x, int y)`
  Compares two `int` values numerically.
  `static int`
  `compare(long x, long y)`
  Compares to `long` values numerically.
  `static int`
  `compare(short x, short y)`
  Compares to `short` values numerically.
  `static BigDecimal`
  `createBigDecimal(String str)`
  Convert a `String` to a `BigDecimal`.
  `static BigInteger`
  `createBigInteger(String str)`
  Convert a `String` to a `BigInteger`; since 3.2 it handles hexadecimal (0x or #) and octal (0) notations.
  `static Double`
  `createDouble(String str)`
  Convert a `String` to a `Double`.
  `static Float`
  `createFloat(String str)`
  Convert a `String` to a `Float`.
  `static Integer`
  `createInteger(String str)`
  Convert a `String` to a `Integer`, handling hexadecimal (0xhhhh) and octal (0dddd) notations.
  `static Long`
  `createLong(String str)`
  Convert a `String` to a `Long`; since 3.1 it handles hexadecimal (0Xhhhh) and octal (0ddd) notations.
  `static Number`
  `createNumber(String str)`
  Turns a string value into a java.lang.Number.
  `static boolean`
  `isCreatable(String str)`
  Checks whether the String is a valid Java number.
  `static boolean`
  `isDigits(String str)`
  Checks whether the `String` contains only digit characters.
  `static boolean`
  `isNumber(String str)`
  Deprecated.
  This feature will be removed in Lang 4, use `isCreatable(String)` instead
  `static boolean`
  `isParsable(String str)`
  Checks whether the given String is a parsable number.
  `static byte`
  `max(byte... array)`
  Returns the maximum value in an array.
  `static byte`
  `max(byte a, byte b, byte c)`
  Gets the maximum of three `byte` values.
  `static double`
  `max(double... array)`
  Returns the maximum value in an array.
  `static double`
  `max(double a, double b, double c)`
  Gets the maximum of three `double` values.
  `static float`
  `max(float... array)`
  Returns the maximum value in an array.
  `static float`
  `max(float a, float b, float c)`
  Gets the maximum of three `float` values.
  `static int`
  `max(int... array)`
  Returns the maximum value in an array.
  `static int`
  `max(int a, int b, int c)`
  Gets the maximum of three `int` values.
  `static long`
  `max(long... array)`
  Returns the maximum value in an array.
  `static long`
  `max(long a, long b, long c)`
  Gets the maximum of three `long` values.
  `static short`
  `max(short... array)`
  Returns the maximum value in an array.
  `static short`
  `max(short a, short b, short c)`
  Gets the maximum of three `short` values.
  `static byte`
  `min(byte... array)`
  Returns the minimum value in an array.
  `static byte`
  `min(byte a, byte b, byte c)`
  Gets the minimum of three `byte` values.
  `static double`
  `min(double... array)`
  Returns the minimum value in an array.
  `static double`
  `min(double a, double b, double c)`
  Gets the minimum of three `double` values.
  `static float`
  `min(float... array)`
  Returns the minimum value in an array.
  `static float`
  `min(float a, float b, float c)`
  Gets the minimum of three `float` values.
  `static int`
  `min(int... array)`
  Returns the minimum value in an array.
  `static int`
  `min(int a, int b, int c)`
  Gets the minimum of three `int` values.
  `static long`
  `min(long... array)`
  Returns the minimum value in an array.
  `static long`
  `min(long a, long b, long c)`
  Gets the minimum of three `long` values.
  `static short`
  `min(short... array)`
  Returns the minimum value in an array.
  `static short`
  `min(short a, short b, short c)`
  Gets the minimum of three `short` values.
  `static byte`
  `toByte(String str)`
  Convert a `String` to a `byte`, returning `zero` if the conversion fails.
  `static byte`
  `toByte(String str, byte defaultValue)`
  Convert a `String` to a `byte`, returning a default value if the conversion fails.
  `static double`
  `toDouble(String str)`
  Convert a `String` to a `double`, returning `0.0d` if the conversion fails.
  `static double`
  `toDouble(String str, double defaultValue)`
  Convert a `String` to a `double`, returning a default value if the conversion fails.
  `static double`
  `toDouble(BigDecimal value)`
  Convert a `BigDecimal` to a `double`.
  `static double`
  `toDouble(BigDecimal value, double defaultValue)`
  Convert a `BigDecimal` to a `double`.
  `static float`
  `toFloat(String str)`
  Convert a `String` to a `float`, returning `0.0f` if the conversion fails.
  `static float`
  `toFloat(String str, float defaultValue)`
  Convert a `String` to a `float`, returning a default value if the conversion fails.
  `static int`
  `toInt(String str)`
  Convert a `String` to an `int`, returning `zero` if the conversion fails.
  `static int`
  `toInt(String str, int defaultValue)`
  Convert a `String` to an `int`, returning a default value if the conversion fails.
  `static long`
  `toLong(String str)`
  Convert a `String` to a `long`, returning `zero` if the conversion fails.
  `static long`
  `toLong(String str, long defaultValue)`
  Convert a `String` to a `long`, returning a default value if the conversion fails.
  `static BigDecimal`
  `toScaledBigDecimal(Double value)`
  Convert a `Double` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`.
  `static BigDecimal`
  `toScaledBigDecimal(Double value, int scale, RoundingMode roundingMode)`
  Convert a `Double` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied.
  `static BigDecimal`
  `toScaledBigDecimal(Float value)`
  Convert a `Float` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`.
  `static BigDecimal`
  `toScaledBigDecimal(Float value, int scale, RoundingMode roundingMode)`
  Convert a `Float` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied.
  `static BigDecimal`
  `toScaledBigDecimal(String value)`
  Convert a `String` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`.
  `static BigDecimal`
  `toScaledBigDecimal(String value, int scale, RoundingMode roundingMode)`
  Convert a `String` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied.
  `static BigDecimal`
  `toScaledBigDecimal(BigDecimal value)`
  Convert a `BigDecimal` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`.
  `static BigDecimal`
  `toScaledBigDecimal(BigDecimal value, int scale, RoundingMode roundingMode)`
  Convert a `BigDecimal` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied.
  `static short`
  `toShort(String str)`
  Convert a `String` to a `short`, returning `zero` if the conversion fails.
  `static short`
  `toShort(String str, short defaultValue)`
  Convert a `String` to an `short`, returning a default value if the conversion fails.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### LONG_ZERO

    public static final Long LONG_ZERO
    Reusable Long constant for zero.

  - ### LONG_ONE

    public static final Long LONG_ONE
    Reusable Long constant for one.

  - ### LONG_MINUS_ONE

    public static final Long LONG_MINUS_ONE
    Reusable Long constant for minus one.

  - ### INTEGER_ZERO

    public static final Integer INTEGER_ZERO
    Reusable Integer constant for zero.

  - ### INTEGER_ONE

    public static final Integer INTEGER_ONE
    Reusable Integer constant for one.

  - ### INTEGER_TWO

    public static final Integer INTEGER_TWO
    Reusable Integer constant for two

  - ### INTEGER_MINUS_ONE

    public static final Integer INTEGER_MINUS_ONE
    Reusable Integer constant for minus one.

  - ### SHORT_ZERO

    public static final Short SHORT_ZERO
    Reusable Short constant for zero.

  - ### SHORT_ONE

    public static final Short SHORT_ONE
    Reusable Short constant for one.

  - ### SHORT_MINUS_ONE

    public static final Short SHORT_MINUS_ONE
    Reusable Short constant for minus one.

  - ### BYTE_ZERO

    public static final Byte BYTE_ZERO
    Reusable Byte constant for zero.

  - ### BYTE_ONE

    public static final Byte BYTE_ONE
    Reusable Byte constant for one.

  - ### BYTE_MINUS_ONE

    public static final Byte BYTE_MINUS_ONE
    Reusable Byte constant for minus one.

  - ### DOUBLE_ZERO

    public static final Double DOUBLE_ZERO
    Reusable Double constant for zero.

  - ### DOUBLE_ONE

    public static final Double DOUBLE_ONE
    Reusable Double constant for one.

  - ### DOUBLE_MINUS_ONE

    public static final Double DOUBLE_MINUS_ONE
    Reusable Double constant for minus one.

  - ### FLOAT_ZERO

    public static final Float FLOAT_ZERO
    Reusable Float constant for zero.

  - ### FLOAT_ONE

    public static final Float FLOAT_ONE
    Reusable Float constant for one.

  - ### FLOAT_MINUS_ONE

    public static final Float FLOAT_MINUS_ONE
    Reusable Float constant for minus one.

  - ### LONG_INT_MAX_VALUE

    public static final Long LONG_INT_MAX_VALUE
    `Integer.MAX_VALUE` as a `Long`.
    Since:
      3.12.0

  - ### LONG_INT_MIN_VALUE

    public static final Long LONG_INT_MIN_VALUE
    `Integer.MIN_VALUE` as a `Long`.
    Since:
      3.12.0

- ## Constructor Details

  - ### NumberUtils

    public NumberUtils()
    `NumberUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `NumberUtils.toInt("6");`.

    This constructor is public to permit tools that require a JavaBean instance to operate.

- ## Method Details

  - ### compare

    public static int compare(byte x, byte y)
    Compares two `byte` values numerically. This is the same functionality as provided in Java 7.
    Parameters:
      `x` - the first `byte` to compare
      `y` - the second `byte` to compare
    Returns:
      the value `0` if `x == y`; a value less than `0` if `x < y`; and a value greater than `0` if `x > y`
    Since:
      3.4

  - ### compare

    public static int compare(int x, int y)
    Compares two `int` values numerically. This is the same functionality as provided in Java 7.
    Parameters:
      `x` - the first `int` to compare
      `y` - the second `int` to compare
    Returns:
      the value `0` if `x == y`; a value less than `0` if `x < y`; and a value greater than `0` if `x > y`
    Since:
      3.4

  - ### compare

    public static int compare(long x, long y)
    Compares to `long` values numerically. This is the same functionality as provided in Java 7.
    Parameters:
      `x` - the first `long` to compare
      `y` - the second `long` to compare
    Returns:
      the value `0` if `x == y`; a value less than `0` if `x < y`; and a value greater than `0` if `x > y`
    Since:
      3.4

  - ### compare

    public static int compare(short x, short y)
    Compares to `short` values numerically. This is the same functionality as provided in Java 7.
    Parameters:
      `x` - the first `short` to compare
      `y` - the second `short` to compare
    Returns:
      the value `0` if `x == y`; a value less than `0` if `x < y`; and a value greater than `0` if `x > y`
    Since:
      3.4

  - ### createBigDecimal

    public static BigDecimal createBigDecimal(String str)
    Convert a `String` to a `BigDecimal`.

    Returns `null` if the string is `null`.

    Parameters:
      `str` - a `String` to convert, may be null
    Returns:
      converted `BigDecimal` (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### createBigInteger

    public static BigInteger createBigInteger(String str)
    Convert a `String` to a `BigInteger`; since 3.2 it handles hexadecimal (0x or #) and octal (0) notations.

    Returns `null` if the string is `null`.

    Parameters:
      `str` - a `String` to convert, may be null
    Returns:
      converted `BigInteger` (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### createDouble

    public static Double createDouble(String str)
    Convert a `String` to a `Double`.

    Returns `null` if the string is `null`.

    Parameters:
      `str` - a `String` to convert, may be null
    Returns:
      converted `Double` (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### createFloat

    public static Float createFloat(String str)
    Convert a `String` to a `Float`.

    Returns `null` if the string is `null`.

    Parameters:
      `str` - a `String` to convert, may be null
    Returns:
      converted `Float` (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### createInteger

    public static Integer createInteger(String str)
    Convert a `String` to a `Integer`, handling hexadecimal (0xhhhh) and octal (0dddd) notations. N.B. a leading zero means octal; spaces are not trimmed.

    Returns `null` if the string is `null`.

    Parameters:
      `str` - a `String` to convert, may be null
    Returns:
      converted `Integer` (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### createLong

    public static Long createLong(String str)
    Convert a `String` to a `Long`; since 3.1 it handles hexadecimal (0Xhhhh) and octal (0ddd) notations. N.B. a leading zero means octal; spaces are not trimmed.

    Returns `null` if the string is `null`.

    Parameters:
      `str` - a `String` to convert, may be null
    Returns:
      converted `Long` (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### createNumber

    public static Number createNumber(String str)
    Turns a string value into a java.lang.Number.

    If the string starts with `0x` or `-0x` (lower or upper case) or `#` or `-#`, it will be interpreted as a hexadecimal Integer - or Long, if the number of digits after the prefix is more than 8 - or BigInteger if there are more than 16 digits.

    Then, the value is examined for a type qualifier on the end, i.e. one of `'f', 'F', 'd', 'D', 'l', 'L'`. If it is found, it starts trying to create successively larger types from the type specified until one is found that can represent the value.

    If a type specifier is not found, it will check for a decimal point and then try successively larger types from `Integer` to `BigInteger` and from `Float` to `BigDecimal`.

    Integral values with a leading `0` will be interpreted as octal; the returned number will be Integer, Long or BigDecimal as appropriate.

    Returns `null` if the string is `null`.

    This method does not trim the input string, i.e., strings with leading or trailing spaces will generate NumberFormatExceptions.

    Parameters:
      `str` - String containing a number, may be null
    Returns:
      Number created from the string (or null if the input is null)
    Throws:
      `NumberFormatException` - if the value cannot be converted

  - ### isCreatable

    public static boolean isCreatable(String str)
    Checks whether the String is a valid Java number.

    Valid numbers include hexadecimal marked with the `0x` or `0X` qualifier, octal numbers, scientific notation and numbers marked with a type qualifier (e.g. 123L).

    Non-hexadecimal strings beginning with a leading zero are treated as octal values. Thus the string `09` will return `false`, since `9` is not a valid octal value. However, numbers beginning with `0.` are treated as decimal.

    `null` and empty/blank `String` will return `false`.

    Note, `createNumber(String)` should return a number for every input resulting in `true`.

    Parameters:
      `str` - the `String` to check
    Returns:
      `true` if the string is a correctly formatted number
    Since:
      3.5

  - ### isDigits

    public static boolean isDigits(String str)
    Checks whether the `String` contains only digit characters.

    `null` and empty String will return `false`.

    Parameters:
      `str` - the `String` to check
    Returns:
      `true` if str contains only Unicode numeric

  - ### isNumber

    @Deprecated public static boolean isNumber(String str)
    Deprecated.
    This feature will be removed in Lang 4, use `isCreatable(String)` instead
    Checks whether the String is a valid Java number.

    Valid numbers include hexadecimal marked with the `0x` or `0X` qualifier, octal numbers, scientific notation and numbers marked with a type qualifier (e.g. 123L).

    Non-hexadecimal strings beginning with a leading zero are treated as octal values. Thus the string `09` will return `false`, since `9` is not a valid octal value. However, numbers beginning with `0.` are treated as decimal.

    `null` and empty/blank `String` will return `false`.

    Note, `createNumber(String)` should return a number for every input resulting in `true`.

    Parameters:
      `str` - the `String` to check
    Returns:
      `true` if the string is a correctly formatted number
    Since:
      3.3 the code supports hexadecimal `0Xhhh` an octal `0ddd` validation

  - ### isParsable

    public static boolean isParsable(String str)
    Checks whether the given String is a parsable number.

    Parsable numbers include those Strings understood by `Integer.parseInt(String)`, `Long.parseLong(String)`, `Float.parseFloat(String)` or `Double.parseDouble(String)`. This method can be used instead of catching `ParseException` when calling one of those methods.

    Hexadecimal and scientific notations are not considered parsable. See `isCreatable(String)` on those cases.

    `null` and empty String will return `false`.

    Parameters:
      `str` - the String to check.
    Returns:
      `true` if the string is a parsable number.
    Since:
      3.4

  - ### max

    public static byte max(byte... array)
    Returns the maximum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the maximum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from max(byte[]) to max(byte...)

  - ### max

    public static byte max(byte a, byte b, byte c)
    Gets the maximum of three `byte` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the largest of the values

  - ### max

    public static double max(double... array)
    Returns the maximum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the maximum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from max(double[]) to max(double...)
    See Also:
      - `IEEE754rUtils for a version of this method that handles NaN differently`

  - ### max

    public static double max(double a, double b, double c)
    Gets the maximum of three `double` values.

    If any value is `NaN`, `NaN` is returned. Infinity is handled.

    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the largest of the values
    See Also:
      - `for a version of this method that handles NaN differently`

  - ### max

    public static float max(float... array)
    Returns the maximum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the maximum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from max(float[]) to max(float...)
    See Also:
      - `IEEE754rUtils for a version of this method that handles NaN differently`

  - ### max

    public static float max(float a, float b, float c)
    Gets the maximum of three `float` values.

    If any value is `NaN`, `NaN` is returned. Infinity is handled.

    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the largest of the values
    See Also:
      - `for a version of this method that handles NaN differently`

  - ### max

    public static int max(int... array)
    Returns the maximum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the maximum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from max(int[]) to max(int...)

  - ### max

    public static int max(int a, int b, int c)
    Gets the maximum of three `int` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the largest of the values

  - ### max

    public static long max(long... array)
    Returns the maximum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the maximum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from max(long[]) to max(long...)

  - ### max

    public static long max(long a, long b, long c)
    Gets the maximum of three `long` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the largest of the values

  - ### max

    public static short max(short... array)
    Returns the maximum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the maximum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from max(short[]) to max(short...)

  - ### max

    public static short max(short a, short b, short c)
    Gets the maximum of three `short` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the largest of the values

  - ### min

    public static byte min(byte... array)
    Returns the minimum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the minimum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from min(byte[]) to min(byte...)

  - ### min

    public static byte min(byte a, byte b, byte c)
    Gets the minimum of three `byte` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the smallest of the values

  - ### min

    public static double min(double... array)
    Returns the minimum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the minimum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from min(double[]) to min(double...)
    See Also:
      - `IEEE754rUtils for a version of this method that handles NaN differently`

  - ### min

    public static double min(double a, double b, double c)
    Gets the minimum of three `double` values.

    If any value is `NaN`, `NaN` is returned. Infinity is handled.

    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the smallest of the values
    See Also:
      - `for a version of this method that handles NaN differently`

  - ### min

    public static float min(float... array)
    Returns the minimum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the minimum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from min(float[]) to min(float...)
    See Also:
      - `IEEE754rUtils for a version of this method that handles NaN differently`

  - ### min

    public static float min(float a, float b, float c)
    Gets the minimum of three `float` values.

    If any value is `NaN`, `NaN` is returned. Infinity is handled.

    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the smallest of the values
    See Also:
      - `for a version of this method that handles NaN differently`

  - ### min

    public static int min(int... array)
    Returns the minimum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the minimum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from min(int[]) to min(int...)

  - ### min

    public static int min(int a, int b, int c)
    Gets the minimum of three `int` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the smallest of the values

  - ### min

    public static long min(long... array)
    Returns the minimum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the minimum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from min(long[]) to min(long...)

  - ### min

    public static long min(long a, long b, long c)
    Gets the minimum of three `long` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the smallest of the values

  - ### min

    public static short min(short... array)
    Returns the minimum value in an array.
    Parameters:
      `array` - an array, must not be null or empty
    Returns:
      the minimum value in the array
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty
    Since:
      3.4 Changed signature from min(short[]) to min(short...)

  - ### min

    public static short min(short a, short b, short c)
    Gets the minimum of three `short` values.
    Parameters:
      `a` - value 1
      `b` - value 2
      `c` - value 3
    Returns:
      the smallest of the values

  - ### toByte

    public static byte toByte(String str)
    Convert a `String` to a `byte`, returning `zero` if the conversion fails.

    If the string is `null`, `zero` is returned.

           NumberUtils.toByte(null) = 0
           NumberUtils.toByte("")   = 0
           NumberUtils.toByte("1")  = 1

    Parameters:
      `str` - the string to convert, may be null
    Returns:
      the byte represented by the string, or `zero` if conversion fails
    Since:
      2.5

  - ### toByte

    public static byte toByte(String str, byte defaultValue)
    Convert a `String` to a `byte`, returning a default value if the conversion fails.

    If the string is `null`, the default value is returned.

           NumberUtils.toByte(null, 1) = 1
           NumberUtils.toByte("", 1)   = 1
           NumberUtils.toByte("1", 0)  = 1

    Parameters:
      `str` - the string to convert, may be null
      `defaultValue` - the default value
    Returns:
      the byte represented by the string, or the default if conversion fails
    Since:
      2.5

  - ### toDouble

    public static double toDouble(BigDecimal value)
    Convert a `BigDecimal` to a `double`.

    If the `BigDecimal` `value` is `null`, then the specified default value is returned.

           NumberUtils.toDouble(null)                     = 0.0d
           NumberUtils.toDouble(BigDecimal.valueOf(8.5d)) = 8.5d

    Parameters:
      `value` - the `BigDecimal` to convert, may be `null`.
    Returns:
      the double represented by the `BigDecimal` or `0.0d` if the `BigDecimal` is `null`.
    Since:
      3.8

  - ### toDouble

    public static double toDouble(BigDecimal value, double defaultValue)
    Convert a `BigDecimal` to a `double`.

    If the `BigDecimal` `value` is `null`, then the specified default value is returned.

           NumberUtils.toDouble(null, 1.1d)                     = 1.1d
           NumberUtils.toDouble(BigDecimal.valueOf(8.5d), 1.1d) = 8.5d

    Parameters:
      `value` - the `BigDecimal` to convert, may be `null`.
      `defaultValue` - the default value
    Returns:
      the double represented by the `BigDecimal` or the defaultValue if the `BigDecimal` is `null`.
    Since:
      3.8

  - ### toDouble

    public static double toDouble(String str)
    Convert a `String` to a `double`, returning `0.0d` if the conversion fails.

    If the string `str` is `null`, `0.0d` is returned.

           NumberUtils.toDouble(null)   = 0.0d
           NumberUtils.toDouble("")     = 0.0d
           NumberUtils.toDouble("1.5")  = 1.5d

    Parameters:
      `str` - the string to convert, may be `null`
    Returns:
      the double represented by the string, or `0.0d` if conversion fails
    Since:
      2.1

  - ### toDouble

    public static double toDouble(String str, double defaultValue)
    Convert a `String` to a `double`, returning a default value if the conversion fails.

    If the string `str` is `null`, the default value is returned.

           NumberUtils.toDouble(null, 1.1d)   = 1.1d
           NumberUtils.toDouble("", 1.1d)     = 1.1d
           NumberUtils.toDouble("1.5", 0.0d)  = 1.5d

    Parameters:
      `str` - the string to convert, may be `null`
      `defaultValue` - the default value
    Returns:
      the double represented by the string, or defaultValue if conversion fails
    Since:
      2.1

  - ### toFloat

    public static float toFloat(String str)
    Convert a `String` to a `float`, returning `0.0f` if the conversion fails.

    If the string `str` is `null`, `0.0f` is returned.

           NumberUtils.toFloat(null)   = 0.0f
           NumberUtils.toFloat("")     = 0.0f
           NumberUtils.toFloat("1.5")  = 1.5f

    Parameters:
      `str` - the string to convert, may be `null`
    Returns:
      the float represented by the string, or `0.0f` if conversion fails
    Since:
      2.1

  - ### toFloat

    public static float toFloat(String str, float defaultValue)
    Convert a `String` to a `float`, returning a default value if the conversion fails.

    If the string `str` is `null`, the default value is returned.

           NumberUtils.toFloat(null, 1.1f)   = 1.0f
           NumberUtils.toFloat("", 1.1f)     = 1.1f
           NumberUtils.toFloat("1.5", 0.0f)  = 1.5f

    Parameters:
      `str` - the string to convert, may be `null`
      `defaultValue` - the default value
    Returns:
      the float represented by the string, or defaultValue if conversion fails
    Since:
      2.1

  - ### toInt

    public static int toInt(String str)
    Convert a `String` to an `int`, returning `zero` if the conversion fails.

    If the string is `null`, `zero` is returned.

           NumberUtils.toInt(null) = 0
           NumberUtils.toInt("")   = 0
           NumberUtils.toInt("1")  = 1

    Parameters:
      `str` - the string to convert, may be null
    Returns:
      the int represented by the string, or `zero` if conversion fails
    Since:
      2.1

  - ### toInt

    public static int toInt(String str, int defaultValue)
    Convert a `String` to an `int`, returning a default value if the conversion fails.

    If the string is `null`, the default value is returned.

           NumberUtils.toInt(null, 1) = 1
           NumberUtils.toInt("", 1)   = 1
           NumberUtils.toInt("1", 0)  = 1

    Parameters:
      `str` - the string to convert, may be null
      `defaultValue` - the default value
    Returns:
      the int represented by the string, or the default if conversion fails
    Since:
      2.1

  - ### toLong

    public static long toLong(String str)
    Convert a `String` to a `long`, returning `zero` if the conversion fails.

    If the string is `null`, `zero` is returned.

           NumberUtils.toLong(null) = 0L
           NumberUtils.toLong("")   = 0L
           NumberUtils.toLong("1")  = 1L

    Parameters:
      `str` - the string to convert, may be null
    Returns:
      the long represented by the string, or `0` if conversion fails
    Since:
      2.1

  - ### toLong

    public static long toLong(String str, long defaultValue)
    Convert a `String` to a `long`, returning a default value if the conversion fails.

    If the string is `null`, the default value is returned.

           NumberUtils.toLong(null, 1L) = 1L
           NumberUtils.toLong("", 1L)   = 1L
           NumberUtils.toLong("1", 0L)  = 1L

    Parameters:
      `str` - the string to convert, may be null
      `defaultValue` - the default value
    Returns:
      the long represented by the string, or the default if conversion fails
    Since:
      2.1

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(BigDecimal value)
    Convert a `BigDecimal` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`. If the supplied `value` is null, then `BigDecimal.ZERO` is returned.

    Note, the scale of a `BigDecimal` is the number of digits to the right of the decimal point.

    Parameters:
      `value` - the `BigDecimal` to convert, may be null.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(BigDecimal value, int scale, RoundingMode roundingMode)
    Convert a `BigDecimal` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied. If the input `value` is `null`, we simply return `BigDecimal.ZERO`.
    Parameters:
      `value` - the `BigDecimal` to convert, may be null.
      `scale` - the number of digits to the right of the decimal point.
      `roundingMode` - a rounding behavior for numerical operations capable of discarding precision.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(Double value)
    Convert a `Double` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`. If the supplied `value` is null, then `BigDecimal.ZERO` is returned.

    Note, the scale of a `BigDecimal` is the number of digits to the right of the decimal point.

    Parameters:
      `value` - the `Double` to convert, may be null.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(Double value, int scale, RoundingMode roundingMode)
    Convert a `Double` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied. If the input `value` is `null`, we simply return `BigDecimal.ZERO`.
    Parameters:
      `value` - the `Double` to convert, may be null.
      `scale` - the number of digits to the right of the decimal point.
      `roundingMode` - a rounding behavior for numerical operations capable of discarding precision.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(Float value)
    Convert a `Float` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`. If the supplied `value` is null, then `BigDecimal.ZERO` is returned.

    Note, the scale of a `BigDecimal` is the number of digits to the right of the decimal point.

    Parameters:
      `value` - the `Float` to convert, may be null.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(Float value, int scale, RoundingMode roundingMode)
    Convert a `Float` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied. If the input `value` is `null`, we simply return `BigDecimal.ZERO`.
    Parameters:
      `value` - the `Float` to convert, may be null.
      `scale` - the number of digits to the right of the decimal point.
      `roundingMode` - a rounding behavior for numerical operations capable of discarding precision.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(String value)
    Convert a `String` to a `BigDecimal` with a scale of two that has been rounded using `RoundingMode.HALF_EVEN`. If the supplied `value` is null, then `BigDecimal.ZERO` is returned.

    Note, the scale of a `BigDecimal` is the number of digits to the right of the decimal point.

    Parameters:
      `value` - the `String` to convert, may be null.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toScaledBigDecimal

    public static BigDecimal toScaledBigDecimal(String value, int scale, RoundingMode roundingMode)
    Convert a `String` to a `BigDecimal` whose scale is the specified value with a `RoundingMode` applied. If the input `value` is `null`, we simply return `BigDecimal.ZERO`.
    Parameters:
      `value` - the `String` to convert, may be null.
      `scale` - the number of digits to the right of the decimal point.
      `roundingMode` - a rounding behavior for numerical operations capable of discarding precision.
    Returns:
      the scaled, with appropriate rounding, `BigDecimal`.
    Since:
      3.8

  - ### toShort

    public static short toShort(String str)
    Convert a `String` to a `short`, returning `zero` if the conversion fails.

    If the string is `null`, `zero` is returned.

           NumberUtils.toShort(null) = 0
           NumberUtils.toShort("")   = 0
           NumberUtils.toShort("1")  = 1

    Parameters:
      `str` - the string to convert, may be null
    Returns:
      the short represented by the string, or `zero` if conversion fails
    Since:
      2.5

  - ### toShort

    public static short toShort(String str, short defaultValue)
    Convert a `String` to an `short`, returning a default value if the conversion fails.

    If the string is `null`, the default value is returned.

           NumberUtils.toShort(null, 1) = 1
           NumberUtils.toShort("", 1)   = 1
           NumberUtils.toShort("1", 0)  = 1

    Parameters:
      `str` - the string to convert, may be null
      `defaultValue` - the default value
    Returns:
      the short represented by the string, or the default if conversion fails
    Since:
      2.5