org.apache.commons.lang.math

Class NumberUtils

public class NumberUtils extends Object

Provides extra functionality for Java Number classes.

Since: 2.0

Version: $Id: NumberUtils.java 609475 2008-01-06 23:58:59Z bayard $

Author: Rand McNeely Stephen Colebourne Steve Downey Eric Pugh Phil Steitz Matthew Hawthorne Gary Gregory Fredrik Westermarck

Field Summary
static ByteBYTE_MINUS_ONE
Reusable Byte constant for minus one.
static ByteBYTE_ONE
Reusable Byte constant for one.
static ByteBYTE_ZERO
Reusable Byte constant for zero.
static DoubleDOUBLE_MINUS_ONE
Reusable Double constant for minus one.
static DoubleDOUBLE_ONE
Reusable Double constant for one.
static DoubleDOUBLE_ZERO
Reusable Double constant for zero.
static FloatFLOAT_MINUS_ONE
Reusable Float constant for minus one.
static FloatFLOAT_ONE
Reusable Float constant for one.
static FloatFLOAT_ZERO
Reusable Float constant for zero.
static IntegerINTEGER_MINUS_ONE
Reusable Integer constant for minus one.
static IntegerINTEGER_ONE
Reusable Integer constant for one.
static IntegerINTEGER_ZERO
Reusable Integer constant for zero.
static LongLONG_MINUS_ONE
Reusable Long constant for minus one.
static LongLONG_ONE
Reusable Long constant for one.
static LongLONG_ZERO
Reusable Long constant for zero.
static ShortSHORT_MINUS_ONE
Reusable Short constant for minus one.
static ShortSHORT_ONE
Reusable Short constant for one.
static ShortSHORT_ZERO
Reusable Short constant for zero.
Constructor Summary
NumberUtils()

NumberUtils instances should NOT be constructed in standard programming.

Method Summary
static intcompare(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.

static intcompare(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.
static BigDecimalcreateBigDecimal(String str)

Convert a String to a BigDecimal.

Returns null if the string is null.

static BigIntegercreateBigInteger(String str)

Convert a String to a BigInteger.

Returns null if the string is null.

static DoublecreateDouble(String str)

Convert a String to a Double.

Returns null if the string is null.

static FloatcreateFloat(String str)

Convert a String to a Float.

Returns null if the string is null.

static IntegercreateInteger(String str)

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

Returns null if the string is null.

static LongcreateLong(String str)

Convert a String to a Long.

Returns null if the string is null.

static NumbercreateNumber(String str)

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').

static booleanisDigits(String str)

Checks whether the String contains only digit characters.

Null and empty String will return false.

static booleanisNumber(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.

static longmax(long[] array)

Returns the maximum value in an array.

static intmax(int[] array)

Returns the maximum value in an array.

static shortmax(short[] array)

Returns the maximum value in an array.

static bytemax(byte[] array)

Returns the maximum value in an array.

static doublemax(double[] array)

Returns the maximum value in an array.

static floatmax(float[] array)

Returns the maximum value in an array.

static longmax(long a, long b, long c)

Gets the maximum of three long values.

static intmax(int a, int b, int c)

Gets the maximum of three int values.

static shortmax(short a, short b, short c)

Gets the maximum of three short values.

static bytemax(byte a, byte b, byte c)

Gets the maximum of three byte values.

static doublemax(double a, double b, double c)

Gets the maximum of three double values.

If any value is NaN, NaN is returned.

static floatmax(float a, float b, float c)

Gets the maximum of three float values.

If any value is NaN, NaN is returned.

static longmin(long[] array)

Returns the minimum value in an array.

static intmin(int[] array)

Returns the minimum value in an array.

static shortmin(short[] array)

Returns the minimum value in an array.

static bytemin(byte[] array)

Returns the minimum value in an array.

static doublemin(double[] array)

Returns the minimum value in an array.

static floatmin(float[] array)

Returns the minimum value in an array.

static longmin(long a, long b, long c)

Gets the minimum of three long values.

static intmin(int a, int b, int c)

Gets the minimum of three int values.

static shortmin(short a, short b, short c)

Gets the minimum of three short values.

static bytemin(byte a, byte b, byte c)

Gets the minimum of three byte values.

static doublemin(double a, double b, double c)

Gets the minimum of three double values.

If any value is NaN, NaN is returned.

static floatmin(float a, float b, float c)

Gets the minimum of three float values.

If any value is NaN, NaN is returned.

static intstringToInt(String str)

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
 
static intstringToInt(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.stringToInt(null, 1) = 1
   NumberUtils.stringToInt("", 1)   = 1
   NumberUtils.stringToInt("1", 0)  = 1
 
static doubletoDouble(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
 
static doubletoDouble(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
 
static floattoFloat(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
 
static floattoFloat(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
 
static inttoInt(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
 
static inttoInt(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
 
static longtoLong(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
 
static longtoLong(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
 

Field Detail

BYTE_MINUS_ONE

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

BYTE_ONE

public static final Byte BYTE_ONE
Reusable Byte constant for one.

BYTE_ZERO

public static final Byte BYTE_ZERO
Reusable Byte constant for zero.

DOUBLE_MINUS_ONE

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

DOUBLE_ONE

public static final Double DOUBLE_ONE
Reusable Double constant for one.

DOUBLE_ZERO

public static final Double DOUBLE_ZERO
Reusable Double constant for zero.

FLOAT_MINUS_ONE

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

FLOAT_ONE

public static final Float FLOAT_ONE
Reusable Float constant for one.

FLOAT_ZERO

public static final Float FLOAT_ZERO
Reusable Float constant for zero.

INTEGER_MINUS_ONE

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

INTEGER_ONE

public static final Integer INTEGER_ONE
Reusable Integer constant for one.

INTEGER_ZERO

public static final Integer INTEGER_ZERO
Reusable Integer constant for zero.

LONG_MINUS_ONE

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

LONG_ONE

public static final Long LONG_ONE
Reusable Long constant for one.

LONG_ZERO

public static final Long LONG_ZERO
Reusable Long constant for zero.

SHORT_MINUS_ONE

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

SHORT_ONE

public static final Short SHORT_ONE
Reusable Short constant for one.

SHORT_ZERO

public static final Short SHORT_ZERO
Reusable Short constant for zero.

Constructor Detail

NumberUtils

public NumberUtils()

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

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

Method Detail

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.

The ordering is as follows, largest to smallest:

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.

The ordering is as follows, largest to smallest:

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

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

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

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

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

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

createNumber

public static Number createNumber(String str)

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

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

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: (double[]) 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: (float[]) IEEE754rUtils 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

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: (double[]) 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: (float[]) 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

stringToInt

public static int stringToInt(String str)

Deprecated: Use toInt 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

stringToInt

public static int stringToInt(String str, int defaultValue)

Deprecated: Use NumberUtils 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

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

Copyright © 2001-2010 - Apache Software Foundation