org.codehaus.plexus.util

## Class TypeFormat

- java.lang.Object
- - org.codehaus.plexus.util.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 `StringBuffer`.

Methods from this utility class do not create temporary objects and are typically faster than standard library methods (e.g `parseDouble(java.lang.CharSequence)` 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

### Method Summary

Methods
`static java.lang.StringBuffer` `format(boolean b, java.lang.StringBuffer sb)` Formats the specified `boolean` and appends the resulting text to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(double d, double precision, java.lang.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 java.lang.StringBuffer` `format(double d, int digits, java.lang.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 java.lang.StringBuffer` `format(double d, java.lang.StringBuffer sb)` Formats the specified `double` and appends the resulting text to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(float f, float precision, java.lang.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 java.lang.StringBuffer` `format(float f, java.lang.StringBuffer sb)` Formats the specified `float` and appends the resulting text to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(int i, int radix, java.lang.StringBuffer sb)` Formats the specified `int` in the specified radix and appends the resulting text to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(int i, java.lang.StringBuffer sb)` Formats the specified `int` and appends the resulting text (decimal representation) to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(long l, int radix, java.lang.StringBuffer sb)` Formats the specified `long` in the specified radix and appends the resulting text to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(long l, java.lang.StringBuffer sb)` Formats the specified `long` and appends the resulting text (decimal representation) to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(short s, int radix, java.lang.StringBuffer sb)` Formats the specified `short` in the specified radix and appends the resulting text to the `StringBuffer` argument.
`static java.lang.StringBuffer` `format(short s, java.lang.StringBuffer sb)` Formats the specified `short` and appends the resulting text (decimal representation) to the `StringBuffer` argument.
`static int` `indexOf(java.lang.CharSequence pattern, java.lang.CharSequence chars, int fromIndex)` Searches for a particular sequence within a character sequence (general purpose parsing function).
`static boolean` `parseBoolean(java.lang.CharSequence chars)` Parses the specified `CharSequence` as a `boolean`.
`static double` `parseDouble(java.lang.CharSequence chars)` Parses this `CharSequence` as a `double`.
`static float` `parseFloat(java.lang.CharSequence chars)` Parses this `CharSequence` as a `float`.
`static int` `parseInt(java.lang.CharSequence chars)` Parses the specified `CharSequence` as a signed decimal `int`.
`static int` `parseInt(java.lang.CharSequence chars, int radix)` Parses the specified `CharSequence` as a signed `int` in the specified radix.
`static long` `parseLong(java.lang.CharSequence chars)` Parses the specified `CharSequence` as a signed decimal `long`.
`static long` `parseLong(java.lang.CharSequence chars, int radix)` Parses the specified `CharSequence` as a signed `long` in the specified radix.
`static short` `parseShort(java.lang.CharSequence chars)` Parses the specified `CharSequence` as a signed decimal `short`.
`static short` `parseShort(java.lang.CharSequence chars, int radix)` Parses the specified `CharSequence` 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

#### indexOf

    public static int indexOf(java.lang.CharSequence pattern,
              java.lang.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.

#### parseBoolean

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

Parses the specified `CharSequence` as a `boolean`.

Parameters:
  `chars` - the character sequence to parse.
Returns:
  the corresponding `boolean`.

#### parseShort

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

Parses the specified `CharSequence` as a signed decimal `short`.

Parameters:
  `chars` - the character sequence to parse.
Returns:
  `parseShort(chars, 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 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:
  `java.lang.NumberFormatException` - if the specified character sequence does not contain a parsable `short`.

#### parseInt

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

Parses the specified `CharSequence` as a signed decimal `int`.

Parameters:
  `chars` - the character sequence to parse.
Returns:
  `parseInt(chars, 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.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:
  `java.lang.NumberFormatException` - if the specified character sequence does not contain a parsable `int`.

#### parseLong

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

Parses the specified `CharSequence` as a signed decimal `long`.

Parameters:
  `chars` - the character sequence to parse.
Returns:
  `parseLong(chars, 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.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:
  `java.lang.NumberFormatException` - if the specified character sequence does not contain a parsable `long`.

#### parseFloat

    public static float parseFloat(java.lang.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:
  `java.lang.NumberFormatException` - if the character sequence does not contain a parsable `float`.

#### parseDouble

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

Parses this `CharSequence` as a `double`.

Parameters:
  `chars` - 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`.

#### format

    public static java.lang.StringBuffer format(boolean b,
                                java.lang.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:
  `parseBoolean(java.lang.CharSequence)`

#### format

    public static java.lang.StringBuffer format(short s,
                                java.lang.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:
  `parseShort(java.lang.CharSequence)`

#### format

    public static java.lang.StringBuffer format(short s,
                                int radix,
                                java.lang.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.
See Also:
  `throws IllegalArgumentException if radix is not in [2 .. 36] range.`

#### format

    public static java.lang.StringBuffer format(int i,
                                java.lang.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:
  `parseInt(java.lang.CharSequence)`

#### format

    public static java.lang.StringBuffer format(int i,
                                int radix,
                                java.lang.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.
See Also:
  `throws IllegalArgumentException if radix is not in [2 .. 36] range.`

#### format

    public static java.lang.StringBuffer format(long l,
                                java.lang.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:
  `parseLong(java.lang.CharSequence)`

#### format

    public static java.lang.StringBuffer format(long l,
                                int radix,
                                java.lang.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.
See Also:
  `throws IllegalArgumentException if radix is not in [2 .. 36] range.`

#### format

    public static java.lang.StringBuffer format(float f,
                                java.lang.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:
  `format(float, float, StringBuffer)`

#### format

    public static java.lang.StringBuffer format(float f,
                                float precision,
                                java.lang.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:
  `java.lang.IllegalArgumentException` - if the specified precision is negative or would result in too many digits (19+).

#### format

    public static java.lang.StringBuffer format(double d,
                                java.lang.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:
  `format(double, double, StringBuffer)`

#### format

    public static java.lang.StringBuffer format(double d,
                                int digits,
                                java.lang.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:
  `java.lang.IllegalArgumentException` - if the number of digits is not in range `[1..19]`.

#### format

    public static java.lang.StringBuffer format(double d,
                                double precision,
                                java.lang.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:
  `java.lang.IllegalArgumentException` - if the specified precision is negative or would result in too many digits (19+).