org.apache.commons.lang
Class NumberUtils

java.lang.Object
  |
  +--org.apache.commons.lang.NumberUtils

public final class NumberUtils

extends Object

Provides extra functionality for Java Number classes.

Version:

$Id: NumberUtils.java,v 1.3 2002/09/28 10:34:54 scolebourne Exp $

Author:

Henri Yandell, Rand McNeely, Stephen Colebourne, Steve Downey

Constructor Summary

NumberUtils()
NumberUtils instances should NOT be constructed in standard programming.

Method Summary

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	createBigDecimal(String val) Convert a String to a BigDecimal
static BigInteger	createBigInteger(String val) Convert a String to a BigInteger
static Double	createDouble(String val) Convert a String to a Double
static Float	createFloat(String val) Convert a String to a Float
static Integer	createInteger(String val) Convert a String to a Integer, handling hex and octal notations.
static Long	createLong(String val) Convert a String to a Long
static Number	createNumber(String val) Turns a string value into a java.lang.Number.
private static boolean	isAllZeros(String s) Utility method for createNumber.
static boolean	isDigits(String str) Checks whether the String contains only digit characters.
static boolean	isNumber(String str) Checks whether the String a valid Java number.
static int	maximum(int a, int b, int c) Gets the maximum of three int values.
static long	maximum(long a, long b, long c) Gets the maximum of three long values.
static int	minimum(int a, int b, int c) Gets the minimum of three int values.
static long	minimum(long a, long b, long c) Gets the minimum of three long values.
static int	stringToInt(String str) Convert a String to an int, returning zero if the conversion fails
static int	stringToInt(String str, int defaultValue) Convert a String to an int, 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

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

stringToInt

public static int stringToInt(String str)

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

Parameters:

str - the string to convert

Returns:

the int represented by the string, or zero if conversion fails

stringToInt

public static int stringToInt(String str,
                              int defaultValue)

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

Parameters:

str - the string to convert

defaultValue - the default value

Returns:

the int represented by the string, or the default if conversion fails

createNumber

public static Number createNumber(String val)
                           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 succissively larger types from the type specified until one is found that can hold 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.

Parameters:

val - String containing a number

Returns:

Number created from the string

Throws:

NumberFormatException - if the value cannot be converted

isAllZeros

private static boolean isAllZeros(String s)

Utility method for createNumber. Returns true if s is null

Parameters:

s - the String to check

Returns:

if it is all zeros or null

createFloat

public static Float createFloat(String val)

Convert a String to a Float

Parameters:

val - a String to convert

Returns:

converted Float

Throws:

NumberFormatException - if the value cannot be converted

createDouble

public static Double createDouble(String val)

Convert a String to a Double

Parameters:

val - a String to convert

Returns:

converted Double

Throws:

NumberFormatException - if the value cannot be converted

createInteger

public static Integer createInteger(String val)

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

Parameters:

val - a String to convert

Returns:

converted Integer

Throws:

NumberFormatException - if the value cannot be converted

createLong

public static Long createLong(String val)

Convert a String to a Long

Parameters:

val - a String to convert

Returns:

converted Long

Throws:

NumberFormatException - if the value cannot be converted

createBigInteger

public static BigInteger createBigInteger(String val)

Convert a String to a BigInteger

Parameters:

val - a String to convert

Returns:

converted BigInteger

Throws:

NumberFormatException - if the value cannot be converted

createBigDecimal

public static BigDecimal createBigDecimal(String val)

Convert a String to a BigDecimal

Parameters:

val - a String to convert

Returns:

converted BigDecimal

Throws:

NumberFormatException - if the value cannot be converted

minimum

public static long minimum(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 largest of the values

minimum

public static int minimum(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 largest of the values

maximum

public static long maximum(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

maximum

public static int maximum(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

compare

public static int compare(double lhs,
                          double rhs)

Compares two doubles for order.

This method is more comprhensive 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 positve 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 comprhensive 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 positve 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 blank string will return false.

Parameters:

str - the string to check

Returns:

boolean 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 blank string will return false.

Parameters:

str - the string to check

Returns:

true if the string is a correctly formatted number