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

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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+).