org.codehaus.plexus.util

Class TypeFormat

public final class TypeFormat extends Object

This class provides utility methods to parse CharSequence into primitive types and to format primitive types into StringBuffer.

Methods from this utility class do not create temporary objects and are typically faster than standard library methods (e.g TypeFormat is up to 15x faster than Double.parseDouble).

For class instances, formatting is typically performed using specialized java.text.Format (Locale sensitive) and/or using conventional methods (class sensitive). For example:

     public class Foo {
         public static Foo valueOf(CharSequence chars) {...} // Parses.
         public StringBuffer appendTo(StringBuffer sb) {...} // Formats.
         public String toString() {
             return appendTo(new StringBuffer()).toString();
         }
     }

This class is public domain (not copyrighted).

Version: 4.6, June 22, 2003

Author: Jean-Marie Dautelle

Field Summary
static char[]	DIGITS Holds the characters used to represent numbers.
static double[]	DOUBLE_POW_10
static double	DOUBLE_RELATIVE_ERROR
static float	FLOAT_RELATIVE_ERROR
static int[]	INT_POW_10
static String[]	LEADING_ZEROS
static double	LOG_10
static long[]	LONG_POW_10

Constructor Summary
	TypeFormat() Default constructor (forbids derivation).

Method Summary
static StringBuffer	format(boolean b, StringBuffer sb) Formats the specified `boolean` and appends the resulting text to the `StringBuffer` argument.
static StringBuffer	format(short s, StringBuffer sb) Formats the specified `short` and appends the resulting text (decimal representation) to the `StringBuffer` argument.
static StringBuffer	format(short s, int radix, StringBuffer sb) Formats the specified `short` in the specified radix and appends the resulting text to the `StringBuffer` argument.
static StringBuffer	format(int i, StringBuffer sb) Formats the specified `int` and appends the resulting text (decimal representation) to the `StringBuffer` argument.
static StringBuffer	format(int i, int radix, StringBuffer sb) Formats the specified `int` in the specified radix and appends the resulting text to the `StringBuffer` argument.
static StringBuffer	format(long l, StringBuffer sb) Formats the specified `long` and appends the resulting text (decimal representation) to the `StringBuffer` argument.
static StringBuffer	format(long l, int radix, StringBuffer sb) Formats the specified `long` in the specified radix and appends the resulting text to the `StringBuffer` argument.
static StringBuffer	format(float f, StringBuffer sb) Formats the specified `float` and appends the resulting text to the `StringBuffer` argument.
static StringBuffer	format(float f, float precision, StringBuffer sb) Formats the specified `float` and appends the resulting text to the `StringBuffer` argument; the number of significative digits is deduced from the specifed precision.
static StringBuffer	format(double d, StringBuffer sb) Formats the specified `double` and appends the resulting text to the `StringBuffer` argument.
static StringBuffer	format(double d, int digits, StringBuffer sb) Formats the specified `double` and appends the resulting text to the `StringBuffer` argument; the number of significand digits is specified as integer argument.
static StringBuffer	format(double d, double precision, StringBuffer sb) Formats the specified `double` and appends the resulting text to the `StringBuffer` argument; the number of significative digits is deduced from the specifed precision.
static StringBuffer	format(double d, double precision, boolean precisionOnLastDigit, StringBuffer sb) Formats the specified `double` and appends the resulting text to the `StringBuffer` argument; the number of significative digits is deduced from the specifed precision.
static void	format2(int i, int radix, StringBuffer sb)
static void	format2(long l, int radix, StringBuffer sb)
static int	indexOf(CharSequence pattern, CharSequence chars, int fromIndex) Searches for a particular sequence within a character sequence (general purpose parsing function).
static double	multE(double value, int E) Returns the product of the specified value with `10` raised at the specified power exponent.
static boolean	parseBoolean(CharSequence chars) Parses the specified `CharSequence` as a `boolean`.
static double	parseDouble(CharSequence chars) Parses this `CharSequence` as a `double`.
static float	parseFloat(CharSequence chars) Parses this `CharSequence` as a `float`.
static int	parseInt(CharSequence chars) Parses the specified `CharSequence` as a signed decimal `int`.
static int	parseInt(CharSequence chars, int radix) Parses the specified `CharSequence` as a signed `int` in the specified radix.
static long	parseLong(CharSequence chars) Parses the specified `CharSequence` as a signed decimal `long`.
static long	parseLong(CharSequence chars, int radix) Parses the specified `CharSequence` as a signed `long` in the specified radix.
static short	parseShort(CharSequence chars) Parses the specified `CharSequence` as a signed decimal `short`.
static short	parseShort(CharSequence chars, int radix) Parses the specified `CharSequence` as a signed `short` in the specified radix.

Field Detail

DIGITS

private static final char[] DIGITS

Holds the characters used to represent numbers.

DOUBLE_POW_10

private static final double[] DOUBLE_POW_10

DOUBLE_RELATIVE_ERROR

private static final double DOUBLE_RELATIVE_ERROR

FLOAT_RELATIVE_ERROR

private static final float FLOAT_RELATIVE_ERROR

Constructor Detail

TypeFormat

private TypeFormat()

Default constructor (forbids derivation).

Method Detail

format

public static StringBuffer format(boolean b, StringBuffer sb)

Formats the specified boolean and appends the resulting text to the StringBuffer argument.

Parameters: b a boolean. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

See Also: TypeFormat

format

public static StringBuffer format(short s, StringBuffer sb)

Formats the specified short and appends the resulting text (decimal representation) to the StringBuffer argument.

Note: This method is preferred to StringBuffer.append(short) as it does not create temporary String objects (several times faster for small numbers).

Parameters: s the short number. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

See Also: TypeFormat

format

public static StringBuffer format(short s, int radix, StringBuffer sb)

Formats the specified short in the specified radix and appends the resulting text to the StringBuffer argument.

Parameters: s the short number. radix the radix. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

format

public static StringBuffer format(int i, StringBuffer sb)

Formats the specified int and appends the resulting text (decimal representation) to the StringBuffer argument.

Note: This method is preferred to StringBuffer.append(int) as it does not create temporary String objects (several times faster for small numbers).

Parameters: i the int number. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

See Also: TypeFormat

format

public static StringBuffer format(int i, int radix, StringBuffer sb)

Formats the specified int in the specified radix and appends the resulting text to the StringBuffer argument.

Parameters: i the int number. radix the radix. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

format

public static StringBuffer format(long l, StringBuffer sb)

Formats the specified long and appends the resulting text (decimal representation) to the StringBuffer argument.

Note: This method is preferred to StringBuffer.append(long) as it does not create temporary String objects (several times faster for small numbers).

Parameters: l the long number. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

See Also: TypeFormat

format

public static StringBuffer format(long l, int radix, StringBuffer sb)

Formats the specified long in the specified radix and appends the resulting text to the StringBuffer argument.

Parameters: l the long number. radix the radix. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

format

public static StringBuffer format(float f, StringBuffer sb)

Formats the specified float and appends the resulting text to the StringBuffer argument.

Parameters: f the float number. sb the StrinBuffer to append.

Returns: format(f, 0.0f, sb)

See Also: TypeFormat

format

public static StringBuffer format(float f, float precision, StringBuffer sb)

Formats the specified float and appends the resulting text to the StringBuffer argument; the number of significative digits is deduced from the specifed precision. All digits at least as significant as the specified precision are represented. For example:

format(5.6f, 0.01f, sb) appends "5.60"
format(5.6f, 0.1f, sb) appends "5.6"
format(5.6f, 1f, sb) appends "6"

If the precision is 0.0f, the precision is assumed to be the intrinsic float precision (64 bits IEEE 754 format); no formatting is performed, all significant digits are displayed and trailing zeros are removed.

Parameters: f the float number. precision the maximum weight of the last digit represented. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

Throws: IllegalArgumentException if the specified precision is negative or would result in too many digits (19+).

format

public static StringBuffer format(double d, StringBuffer sb)

Formats the specified double and appends the resulting text to the StringBuffer argument.

Note : This method is preferred to StringBuffer.append(double) or even String.valueOf(double) as it does not create temporary String or FloatingDecimal objects (several times faster, e.g. 15x faster for Double.MAX_VALUE).

Parameters: d the double number. sb the StrinBuffer to append.

Returns: format(d, 0.0, sb)

See Also: TypeFormat

format

public static StringBuffer format(double d, int digits, StringBuffer sb)

Formats the specified double and appends the resulting text to the StringBuffer argument; the number of significand digits is specified as integer argument.

Parameters: d the double number. digits the number of significand digits (excludes exponent). sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

Throws: IllegalArgumentException if the number of digits is not in range [1..19].

format

public static StringBuffer format(double d, double precision, StringBuffer sb)

Formats the specified double and appends the resulting text to the StringBuffer argument; the number of significative digits is deduced from the specifed precision. All digits at least as significant as the specified precision are represented. For example:

format(5.6, 0.01, sb) appends "5.60"
format(5.6, 0.1, sb) appends "5.6"
format(5.6, 1, sb) appends "6"

If the precision is 0.0, the precision is assumed to be the intrinsic double precision (64 bits IEEE 754 format); no formatting is performed, all significant digits are displayed and trailing zeros are removed.

Parameters: d the double number. precision the maximum weight of the last digit represented. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

Throws: IllegalArgumentException if the specified precision is negative or would result in too many digits (19+).

format

private static StringBuffer format(double d, double precision, boolean precisionOnLastDigit, StringBuffer sb)

Formats the specified double and appends the resulting text to the StringBuffer argument; the number of significative digits is deduced from the specifed precision.

Parameters: d the double number. precision the maximum weight of the last digit represented. precisionOnLastDigit indicates if the number of digits is deduced from the specified precision. sb the StrinBuffer to append.

Returns: the specified StringBuffer object.

format2

private static void format2(int i, int radix, StringBuffer sb)

format2

private static void format2(long l, int radix, StringBuffer sb)

indexOf

public static int indexOf(CharSequence pattern, CharSequence chars, int fromIndex)

Searches for a particular sequence within a character sequence (general purpose parsing function).

Parameters: pattern the character sequence to search for. chars the character sequence being searched. fromIndex the index in chars to start the search from.

Returns: the index in the range [fromIndex, chars.length()-pattern.length()] or -1 if the character sequence is not found.

multE

private static final double multE(double value, int E)

Returns the product of the specified value with 10 raised at the specified power exponent.

Parameters: value the value. E the exponent.

Returns: value * 10^E

parseBoolean

public static boolean parseBoolean(CharSequence chars)

Parses the specified CharSequence as a boolean.

Parameters: chars the character sequence to parse.

Returns: the corresponding boolean.

parseDouble

public static double parseDouble(CharSequence chars)

Parses this CharSequence as a double.

Parameters: chars the character sequence to parse.

Returns: the double number represented by this character sequence.

Throws: NumberFormatException if the character sequence does not contain a parsable double.

parseFloat

public static float parseFloat(CharSequence chars)

Parses this CharSequence as a float.

Parameters: chars the character sequence to parse.

Returns: the float number represented by the specified character sequence.

Throws: NumberFormatException if the character sequence does not contain a parsable float.

parseInt

public static int parseInt(CharSequence chars)

Parses the specified CharSequence as a signed decimal int.

Parameters: chars the character sequence to parse.

Returns: parseInt(chars, 10)

Throws: NumberFormatException if the specified character sequence does not contain a parsable int.

See Also: TypeFormat

parseInt

public static int parseInt(CharSequence chars, int radix)

Parses the specified CharSequence as a signed int in the specified radix. The characters in the string must all be digits of the specified radix, except the first character which may be a plus sign '+' or a minus sign '-'.

Parameters: chars the character sequence to parse. radix the radix to be used while parsing.

Returns: the corresponding int.

Throws: NumberFormatException if the specified character sequence does not contain a parsable int.

parseLong

public static long parseLong(CharSequence chars)

Parses the specified CharSequence as a signed decimal long.

Parameters: chars the character sequence to parse.

Returns: parseLong(chars, 10)

Throws: NumberFormatException if the specified character sequence does not contain a parsable long.

See Also: TypeFormat

parseLong

public static long parseLong(CharSequence chars, int radix)

Parses the specified CharSequence as a signed long in the specified radix. The characters in the string must all be digits of the specified radix, except the first character which may be a plus sign '+' or a minus sign '-'.

Parameters: chars the character sequence to parse. radix the radix to be used while parsing.

Returns: the corresponding long.

Throws: NumberFormatException if the specified character sequence does not contain a parsable long.

parseShort

public static short parseShort(CharSequence chars)

Parses the specified CharSequence as a signed decimal short.

Parameters: chars the character sequence to parse.

Returns: parseShort(chars, 10)

Throws: NumberFormatException if the specified character sequence does not contain a parsable short.

See Also: TypeFormat

parseShort

public static short parseShort(CharSequence chars, int radix)

Parses the specified CharSequence as a signed short in the specified radix. The characters in the string must all be digits of the specified radix, except the first character which may be a plus sign '+' or a minus sign '-'.

Parameters: chars the character sequence to parse. radix the radix to be used while parsing.

Returns: the corresponding short.

Throws: NumberFormatException if the specified character sequence does not contain a parsable short.