org.apache.commons.lang.math
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,v 1.10 2003/08/18 02:22:24 bayard Exp $

Author:

Henri Yandell, Rand McNeely, Stephen Colebourne, Steve Downey, Eric Pugh, Phil Steitz, Matthew Hawthorne, Gary Gregory

Field Summary

static Byte	BYTE_MINUS_ONE Reusable Byte constant for minus one.
static Byte	BYTE_ONE Reusable Byte constant for one.
static Byte	BYTE_ZERO Reusable Byte constant for zero.
static Double	DOUBLE_MINUS_ONE Reusable Double constant for minus one.
static Double	DOUBLE_ONE Reusable Double constant for one.
static Double	DOUBLE_ZERO Reusable Double constant for zero.
static Float	FLOAT_MINUS_ONE Reusable Float constant for minus one.
static Float	FLOAT_ONE Reusable Float constant for one.
static Float	FLOAT_ZERO Reusable Float constant for zero.
static Integer	INTEGER_MINUS_ONE Reusable Integer constant for minus one.
static Integer	INTEGER_ONE Reusable Integer constant for one.
static Integer	INTEGER_ZERO Reusable Integer constant for zero.
static Long	LONG_MINUS_ONE Reusable Long constant for minus one.
static Long	LONG_ONE Reusable Long constant for one.
static Long	LONG_ZERO Reusable Long constant for zero.
static Short	SHORT_MINUS_ONE Reusable Short constant for minus one.
static Short	SHORT_ONE Reusable Short constant for one.
static Short	SHORT_ZERO Reusable Short constant for zero.

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 str) Convert a String to a BigDecimal.
static BigInteger	createBigInteger(String str) Convert a String to a BigInteger.
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 hex and octal notations.
static Long	createLong(String str) Convert a String to a Long.
static Number	createNumber(String str) Turns a string value into a java.lang.Number.
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 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 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	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

Field Detail

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

If the string is null, zero is returned.

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)

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

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

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

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

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

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

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

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

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

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

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

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