Class NumberUtils

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

public class NumberUtils extends Object

Provides extra functionality for Java Number classes.

Since:
2.0
Version:
$Id: NumberUtils.java 1056853 2011-01-09 01:07:04Z niallp $
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Byte
    Reusable Byte constant for minus one.
    static final Byte
    Reusable Byte constant for one.
    static final Byte
    Reusable Byte constant for zero.
    static final Double
    Reusable Double constant for minus one.
    static final Double
    Reusable Double constant for one.
    static final Double
    Reusable Double constant for zero.
    static final Float
    Reusable Float constant for minus one.
    static final Float
    Reusable Float constant for one.
    static final Float
    Reusable Float constant for zero.
    static final Integer
    Reusable Integer constant for minus one.
    static final Integer
    Reusable Integer constant for one.
    static final Integer
    Reusable Integer constant for zero.
    static final Long
    Reusable Long constant for minus one.
    static final Long
    Reusable Long constant for one.
    static final Long
    Reusable Long constant for zero.
    static final Short
    Reusable Short constant for minus one.
    static final Short
    Reusable Short constant for one.
    static final Short
    Reusable Short constant for zero.
  • Constructor Summary

    Constructors
    Constructor
    Description
    NumberUtils instances should NOT be constructed in standard programming.
  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    compare(double lhs, double rhs)
    Compares two doubles for order.
    static int
    compare(float lhs, float rhs)
    Compares two floats for order.
    static BigDecimal
    Convert a String to a BigDecimal.
    static BigInteger
    Convert a String to a BigInteger.
    static Double
    Convert a String to a Double.
    static Float
    Convert a String to a Float.
    static Integer
    Convert a String to a Integer, handling hex and octal notations.
    static Long
    Convert a String to a Long.
    static Number
    Turns a string value into a java.lang.Number.
    static boolean
    Checks whether the String contains only digit characters.
    static boolean
    Checks whether the String a valid Java 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 int
    Deprecated.
    Use toInt(String) This method will be removed in Commons Lang 3.0
    static int
    stringToInt(String str, int defaultValue)
    Deprecated.
    Use toInt(String, int) This method will be removed in Commons Lang 3.0
    static byte
    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
    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 float
    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
    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
    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 short
    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_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.
  • 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

    • stringToInt

      public static int stringToInt(String str)
      Deprecated.
      Use toInt(String) This method will be removed in Commons Lang 3.0

      Convert a String to an int, returning zero if the conversion fails.

      If the string is null, zero is returned.

         NumberUtils.stringToInt(null) = 0
         NumberUtils.stringToInt("")   = 0
         NumberUtils.stringToInt("1")  = 1
       
      Parameters:
      str - the string to convert, may be null
      Returns:
      the int represented by the string, or zero if conversion fails
    • 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
    • stringToInt

      public static int stringToInt(String str, int defaultValue)
      Deprecated.
      Use toInt(String, int) This method will be removed in Commons Lang 3.0

      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.stringToInt(null, 1) = 1
         NumberUtils.stringToInt("", 1)   = 1
         NumberUtils.stringToInt("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
    • 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
    • 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
    • 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
    • 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
    • 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
    • createNumber

      public static Number createNumber(String str) throws NumberFormatException

      Turns a string value into a java.lang.Number.

      First, the value is examined for a type qualifier on the end ('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.

      If the string starts with 0x or -0x, it will be interpreted as a hexadecimal integer. Values with leading 0's will not be interpreted as octal.

      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
      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
      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
      Throws:
      NumberFormatException - if the value cannot be converted
    • createInteger

      public static Integer createInteger(String str)

      Convert a String to a Integer, handling hex and octal notations.

      Returns null if the string is null.

      Parameters:
      str - a String to convert, may be null
      Returns:
      converted Integer
      Throws:
      NumberFormatException - if the value cannot be converted
    • createLong

      public static Long createLong(String str)

      Convert a String to a Long.

      Returns null if the string is null.

      Parameters:
      str - a String to convert, may be null
      Returns:
      converted Long
      Throws:
      NumberFormatException - if the value cannot be converted
    • createBigInteger

      public static BigInteger createBigInteger(String str)

      Convert a String to a BigInteger.

      Returns null if the string is null.

      Parameters:
      str - a String to convert, may be null
      Returns:
      converted BigInteger
      Throws:
      NumberFormatException - if the value cannot be converted
    • 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
      Throws:
      NumberFormatException - if the value cannot be converted
    • 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:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
      See Also:
    • 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:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
      See Also:
    • 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 minimum value in the array
      Throws:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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 minimum value in the array
      Throws:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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 minimum value in the array
      Throws:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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 minimum value in the array
      Throws:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
    • 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 minimum value in the array
      Throws:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
      See Also:
    • 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 minimum value in the array
      Throws:
      IllegalArgumentException - if array is null
      IllegalArgumentException - if array is empty
      See Also:
    • 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 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 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
    • 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 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:
    • 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:
    • 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 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 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
    • 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 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:
    • 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:
    • compare

      public static int compare(double lhs, double rhs)

      Compares two doubles for order.

      This method is more comprehensive than the standard Java greater than, less than and equals operators.

      • It returns -1 if the first value is less than the second.
      • It returns +1 if the first value is greater than the second.
      • It returns 0 if the values are equal.

      The ordering is as follows, largest to smallest:

      • NaN
      • Positive infinity
      • Maximum double
      • Normal positive numbers
      • +0.0
      • -0.0
      • Normal negative numbers
      • Minimum double (-Double.MAX_VALUE)
      • Negative infinity

      Comparing NaN with NaN will return 0.

      Parameters:
      lhs - the first double
      rhs - the second double
      Returns:
      -1 if lhs is less, +1 if greater, 0 if equal to rhs
    • compare

      public static int compare(float lhs, float rhs)

      Compares two floats for order.

      This method is more comprehensive than the standard Java greater than, less than and equals operators.

      • It returns -1 if the first value is less than the second.
      • It returns +1 if the first value is greater than the second.
      • It returns 0 if the values are equal.

      The ordering is as follows, largest to smallest:

      • NaN
      • Positive infinity
      • Maximum float
      • Normal positive numbers
      • +0.0
      • -0.0
      • Normal negative numbers
      • Minimum float (-Float.MAX_VALUE)
      • Negative infinity

      Comparing NaN with NaN will return 0.

      Parameters:
      lhs - the first float
      rhs - the second float
      Returns:
      -1 if lhs is less, +1 if greater, 0 if equal to rhs
    • 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

      public static boolean isNumber(String str)

      Checks whether the String a valid Java number.

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

      Null and empty String will return false.

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