Class NumberUtils

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:

  • IEEE754rUtils 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:

  IllegalArgumentException - if array is null

  IllegalArgumentException - if array is empty

  See Also:

  • IEEE754rUtils for a version of this method that handles NaN differently

• 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:

  • IEEE754rUtils 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 minimum value in the array

  Throws:

  IllegalArgumentException - if array is null

  IllegalArgumentException - if array is empty

  See Also:

  • IEEE754rUtils for a version of this method that handles NaN differently

• 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:

  • 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

• 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:

  • 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

• 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