javolution.text

Class TypeFormat

java.lang.Object

javolution.text.TypeFormat

public final class TypeFormat
extends java.lang.Object

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

Methods from this class do not create temporary objects and are typically faster than standard library methods (see benchmark).

The number of digits when formatting floating point numbers can be specified. The default setting for double is 17 digits or even 16 digits when the conversion is lossless back and forth (mimic the standard library formatting). For example:

         TypeFormat.format(0.2, a) = "0.2" // 17 or 16 digits (as long as lossless conversion), remove trailing zeros.
         TypeFormat.format(0.2, 17, false, false, a) = "0.20000000000000001" // Closest 17 digits number.
         TypeFormat.format(0.2, 19, false, false, a) = "0.2000000000000000111" // Closest 19 digits.
         TypeFormat.format(0.2, 4, false, false, a) = "0.2" // Fixed-point notation, remove trailing zeros.
         TypeFormat.format(0.2, 4, false, true, a) = "0.2000" // Fixed-point notation, fixed number of digits.
         TypeFormat.format(0.2, 4, true, false, a) = "2.0E-1" // Scientific notation, remove trailing zeros.
         TypeFormat.format(0.2, 4, true, true, a) = "2.000E-1" // Scientific notation, fixed number of digits.
         

For non-primitive objects, formatting is typically performed using specialized TextFormat instances.

Version:

5.3, February 15, 2009

Author:

Jean-Marie Dautelle

Method Summary

Modifier and Type	Method and Description
static java.lang.Appendable	format(boolean b, java.lang.Appendable a) Formats the specified boolean and appends the resulting text to the Appendable argument.
static java.lang.Appendable	format(double d, java.lang.Appendable a) Formats the specified double value (16 or 17 digits output).
static java.lang.Appendable	format(double d, int digits, boolean scientific, boolean showZero, java.lang.Appendable a) Formats the specified double value according to the specified formatting arguments.
static java.lang.Appendable	format(float f, java.lang.Appendable a) Formats the specified float value.
static java.lang.Appendable	format(int i, java.lang.Appendable a) Formats the specified int and appends the resulting text (decimal representation) to the Appendable argument.
static java.lang.Appendable	format(int i, int radix, java.lang.Appendable a) Formats the specified int in the specified radix and appends the resulting text to the Appendable argument.
static java.lang.Appendable	format(long l, java.lang.Appendable a) Formats the specified long and appends the resulting text (decimal representation) to the Appendable argument.
static java.lang.Appendable	format(long l, int radix, java.lang.Appendable a) Formats the specified long in the specified radix and appends the resulting text to the Appendable argument.
static boolean	parseBoolean(java.lang.CharSequence csq) Parses the specified character sequence as a boolean.
static boolean	parseBoolean(java.lang.CharSequence csq, Cursor cursor) Parses the specified character sequence from the specified position as a boolean.
static boolean	parseBoolean(java.lang.String str) Equivalent to parseBoolean(CharSequence) (for J2ME compatibility).
static byte	parseByte(java.lang.CharSequence csq) Parses the specified character sequence as a signed decimal byte.
static byte	parseByte(java.lang.CharSequence csq, int radix) Parses the specified character sequence as a signed byte in the specified radix.
static byte	parseByte(java.lang.CharSequence csq, int radix, Cursor cursor) Parses the specified character sequence from the specified position as a signed byte in the specified radix.
static double	parseDouble(java.lang.CharSequence csq) Parses the specified character sequence as a double.
static double	parseDouble(java.lang.CharSequence csq, Cursor cursor) Parses the specified character sequence from the specified position as a double.
static double	parseDouble(java.lang.String str) Equivalent to parseDouble(CharSequence) (for J2ME compatibility).
static float	parseFloat(java.lang.CharSequence csq) Parses the specified character sequence as a float.
static float	parseFloat(java.lang.CharSequence csq, Cursor cursor) Parses the specified character sequence from the specified position as a float.
static float	parseFloat(java.lang.String str) Equivalent to parseFloat(CharSequence) (for J2ME compatibility).
static int	parseInt(java.lang.CharSequence csq) Parses the specified character sequence as a signed int.
static int	parseInt(java.lang.CharSequence csq, int radix) Parses the specified character sequence as a signed int in the specified radix.
static int	parseInt(java.lang.CharSequence csq, int radix, Cursor cursor) Parses the specified character sequence from the specified position as a signed int in the specified radix.
static int	parseInt(java.lang.String str) Equivalent to parseInt(CharSequence) (for J2ME compatibility).
static int	parseInt(java.lang.String str, int radix) Equivalent to parseInt(CharSequence, int) (for J2ME compatibility).
static long	parseLong(java.lang.CharSequence csq) Parses the specified character sequence as a decimal long.
static long	parseLong(java.lang.CharSequence csq, int radix) Parses the specified character sequence as a signed long in the specified radix.
static long	parseLong(java.lang.CharSequence csq, int radix, Cursor cursor) Parses the specified character sequence from the specified position as a signed long in the specified radix.
static long	parseLong(java.lang.String str) Equivalent to parseLong(CharSequence) (for J2ME compatibility).
static long	parseLong(java.lang.String str, int radix) Equivalent to parseLong(CharSequence, int) (for J2ME compatibility).
static short	parseShort(java.lang.CharSequence csq) Parses the specified character sequence as a signed decimal short.
static short	parseShort(java.lang.CharSequence csq, int radix) Parses the specified character sequence as a signed short in the specified radix.
static short	parseShort(java.lang.CharSequence csq, int radix, Cursor cursor) Parses the specified character sequence from the specified position as a signed short in the specified radix.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

parseBoolean

public static boolean parseBoolean(java.lang.CharSequence csq)

Parses the specified character sequence as a boolean.

Parameters:

csq - the character sequence to parse.

Returns:

parseBoolean(csq, null)

Throws:

java.lang.IllegalArgumentException - if the specified character sequence is different from "true" or "false" ignoring cases.

parseBoolean

public static boolean parseBoolean(java.lang.String str)

Equivalent to parseBoolean(CharSequence) (for J2ME compatibility).

parseBoolean

public static boolean parseBoolean(java.lang.CharSequence csq,
                                   Cursor cursor)

Parses the specified character sequence from the specified position as a boolean.

Parameters:

csq - the character sequence to parse.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the next boolean value.

Throws:

java.lang.IllegalArgumentException - if the character sequence from the specified position is different from "true" or "false" ignoring cases.

parseByte

public static byte parseByte(java.lang.CharSequence csq)

Parses the specified character sequence as a signed decimal byte.

Parameters:

csq - the character sequence to parse.

Returns:

parseByte(csq, 10)

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable byte.

See Also:

parseByte(CharSequence, int)

parseByte

public static byte parseByte(java.lang.CharSequence csq,
                             int radix)

Parses the specified character sequence as a signed byte in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

Returns:

the corresponding byte.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable byte.

parseByte

public static byte parseByte(java.lang.CharSequence csq,
                             int radix,
                             Cursor cursor)

Parses the specified character sequence from the specified position as a signed byte in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the corresponding byte.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable byte.

parseShort

public static short parseShort(java.lang.CharSequence csq)

Parses the specified character sequence as a signed decimal short.

Parameters:

csq - the character sequence to parse.

Returns:

parseShort(csq, 10)

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable short.

See Also:

parseShort(CharSequence, int)

parseShort

public static short parseShort(java.lang.CharSequence csq,
                               int radix)

Parses the specified character sequence as a signed short in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

Returns:

the corresponding short.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable short.

parseShort

public static short parseShort(java.lang.CharSequence csq,
                               int radix,
                               Cursor cursor)

Parses the specified character sequence from the specified position as a signed short in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the corresponding short.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable short.

parseInt

public static int parseInt(java.lang.CharSequence csq)

Parses the specified character sequence as a signed int.

Parameters:

csq - the character sequence to parse.

Returns:

parseInt(csq, 10)

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable int.

See Also:

parseInt(CharSequence, int)

parseInt

public static int parseInt(java.lang.String str)

Equivalent to parseInt(CharSequence) (for J2ME compatibility).

parseInt

public static int parseInt(java.lang.CharSequence csq,
                           int radix)

Parses the specified character sequence as a signed int in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

Returns:

the corresponding int.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable int.

parseInt

public static int parseInt(java.lang.String str,
                           int radix)

Equivalent to parseInt(CharSequence, int) (for J2ME compatibility).

parseInt

public static int parseInt(java.lang.CharSequence csq,
                           int radix,
                           Cursor cursor)

Parses the specified character sequence from the specified position as a signed int in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the corresponding int.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable int.

parseLong

public static long parseLong(java.lang.CharSequence csq)

Parses the specified character sequence as a decimal long.

Parameters:

csq - the character sequence to parse.

Returns:

parseLong(csq, 10)

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable long.

See Also:

parseLong(CharSequence, int)

parseLong

public static long parseLong(java.lang.String str)

Equivalent to parseLong(CharSequence) (for J2ME compatibility).

parseLong

public static long parseLong(java.lang.CharSequence csq,
                             int radix)

Parses the specified character sequence as a signed long in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

Returns:

the corresponding long.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable long.

parseLong

public static long parseLong(java.lang.String str,
                             int radix)

Equivalent to parseLong(CharSequence, int) (for J2ME compatibility).

parseLong

public static long parseLong(java.lang.CharSequence csq,
                             int radix,
                             Cursor cursor)

Parses the specified character sequence from the specified position as a signed long in the specified radix.

Parameters:

csq - the character sequence to parse.

radix - the radix to be used while parsing.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the corresponding long.

Throws:

java.lang.NumberFormatException - if the specified character sequence does not contain a parsable long.

parseFloat

public static float parseFloat(java.lang.CharSequence csq)

Parses the specified character sequence as a float.

Parameters:

csq - the character sequence to parse.

Returns:

the float number represented by the specified character sequence.

parseFloat

public static float parseFloat(java.lang.String str)

Equivalent to parseFloat(CharSequence) (for J2ME compatibility).

parseFloat

public static float parseFloat(java.lang.CharSequence csq,
                               Cursor cursor)

Parses the specified character sequence from the specified position as a float.

Parameters:

csq - the character sequence to parse.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the float number represented by the specified character sequence.

parseDouble

public static double parseDouble(java.lang.CharSequence csq)
                          throws java.lang.NumberFormatException

Parses the specified character sequence as a double. The format must be of the form: <decimal>{'.'<fraction>}{'E|e'<exponent>}.

Parameters:

csq - the character sequence to parse.

Returns:

the double number represented by this character sequence.

Throws:

java.lang.NumberFormatException - if the character sequence does not contain a parsable double.

parseDouble

public static double parseDouble(java.lang.String str)

Equivalent to parseDouble(CharSequence) (for J2ME compatibility).

parseDouble

public static double parseDouble(java.lang.CharSequence csq,
                                 Cursor cursor)
                          throws java.lang.NumberFormatException

Parses the specified character sequence from the specified position as a double.

Parameters:

csq - the character sequence to parse.

cursor - the cursor position (being maintained) or null> to parse the whole character sequence.

Returns:

the double number represented by this character sequence.

Throws:

java.lang.NumberFormatException - if the character sequence does not contain a parsable double.

format

public static java.lang.Appendable format(boolean b,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

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

Parameters:

b - a boolean.

a - the Appendable to append.

Returns:

the specified StringBuffer object.

Throws:

java.io.IOException - if an I/O exception occurs.

format

public static java.lang.Appendable format(int i,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

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

Parameters:

i - the int number.

a - the Appendable to append.

Returns:

the specified Appendable object.

Throws:

java.io.IOException - if an I/O exception occurs.

format

public static java.lang.Appendable format(int i,
                                          int radix,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

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

Parameters:

i - the int number.

radix - the radix.

a - the Appendable to append.

Returns:

the specified Appendable object.

Throws:

java.lang.IllegalArgumentException - if radix is not in [2 .. 36] range.

java.io.IOException - if an I/O exception occurs.

format

public static java.lang.Appendable format(long l,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

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

Parameters:

l - the long number.

a - the Appendable to append.

Returns:

the specified Appendable object.

Throws:

java.io.IOException - if an I/O exception occurs.

See Also:

parseLong(java.lang.CharSequence)

format

public static java.lang.Appendable format(long l,
                                          int radix,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

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

Parameters:

l - the long number.

radix - the radix.

a - the Appendable to append.

Returns:

the specified Appendable object.

Throws:

java.lang.IllegalArgumentException - if radix is not in [2 .. 36] range.

java.io.IOException - if an I/O exception occurs.

See Also:

parseLong(CharSequence, int)

format

public static java.lang.Appendable format(float f,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

Formats the specified float value.

Parameters:

f - the float value.

a - the Appendable to append.

Returns:

TypeFormat.format(f, 10, (MathLib.abs(f) >= 1E7) || (MathLib.abs(f) < 0.001), false, a)

Throws:

java.io.IOException - if an I/O exception occurs.

format

public static java.lang.Appendable format(double d,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

Formats the specified double value (16 or 17 digits output).

Parameters:

d - the double value.

a - the Appendable to append.

Returns:

TypeFormat.format(d, -1, (MathLib.abs(d) >= 1E7) || (MathLib.abs(d) < 0.001), false, a)

Throws:

java.io.IOException - if an I/O exception occurs.

See Also:

TextBuilder.append(double)

format

public static java.lang.Appendable format(double d,
                                          int digits,
                                          boolean scientific,
                                          boolean showZero,
                                          java.lang.Appendable a)
                                   throws java.io.IOException

Formats the specified double value according to the specified formatting arguments.

Parameters:

d - the double value.

digits - the number of significative digits (excludes exponent) or -1 to mimic the standard library (16 or 17 digits).

scientific - true to forces the use of the scientific notation (e.g. 1.23E3); false otherwise.

showZero - true if trailing fractional zeros are represented; false otherwise.

a - the Appendable to append.

Returns:

the specified Appendable object.

Throws:

java.lang.IllegalArgumentException - if (digits > 19))

java.io.IOException - if an I/O exception occurs.

See Also:

TextBuilder.append(double, int, boolean, boolean)