Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.util
Class PrintfFormat

    java.lang.Object
      umontreal.iro.lecuyer.util.PrintfFormat

All Implemented Interfaces:
  Appendable, CharSequence

    public class PrintfFormat

extends Object
implements CharSequence, Appendable

This class acts like a `StringBuffer` which defines new types of `append` methods. It defines certain functionalities of the ANSI C `printf` function that also can be accessed through static methods. The information given here is strongly inspired from the `man` page of the C `printf` function.

Most methods of this class format numbers for the English US locale only. One can use the `Formatter` class available in the Java 5 API for performing locale-independent formatting.

Field Summary
`static String` | `LINE_SEPARATOR` End-of-line symbol or line separator.

Constructor Summary
`PrintfFormat()` Constructs a new buffer object containing an empty string.
`PrintfFormat(int length)` Constructs a new buffer object with an initial capacity of `length`.
`PrintfFormat(String str)` Constructs a new buffer object containing the initial string `str`.

Method Summary
`PrintfFormat` | `append(char c)` Appends a single character to the buffer.
`Appendable` | `append(CharSequence csq)`
`Appendable` | `append(CharSequence csq, int start, int end)`
`PrintfFormat` | `append(double x)` Appends `x` to the buffer.
`PrintfFormat` | `append(int x)` Appends `x` to the buffer.
`PrintfFormat` | `append(int fieldwidth, double x)` Uses the `f` static method to append `x` to the buffer.
`PrintfFormat` | `append(int fieldwidth, int x)` Uses the `d` static method to append `x` to the buffer.
`PrintfFormat` | `append(int fieldwidth, int precision, double x)` Uses the `f` static method to append `x` to the buffer.
`PrintfFormat` | `append(int fieldwidth, int accuracy, int precision, double x)` Uses the `format` static method with the same four arguments to append `x` to the buffer.
`PrintfFormat` | `append(int fieldwidth, long x)` Uses the `d` static method to append `x` to the buffer.
`PrintfFormat` | `append(int fieldwidth, String str)` Uses the `s` static method to append `str` to the buffer.
`PrintfFormat` | `append(long x)` Appends `x` to the buffer.
`PrintfFormat` | `append(String str)` Appends `str` to the buffer.
`char` | `charAt(int index)`
`void` | `clear()` Clears the contents of the buffer.
`static String` | `d(int fieldwidth, int precision, long x)` Formats the long integer `x` into a string like `%d` in the C `printf` function.
`static String` | `d(int fieldwidth, long x)` Same as `d` `(fieldwidth, 1, x)`.
`static String` | `d(long x)` Same as `d` `(0, 1, x)`.
`static String` | `e(double x)` Same as `e` `(0, 6, x)`.
`static String` | `E(double x)` Same as `E` `(0, 6, x)`.
`static String` | `e(int fieldwidth, double x)` Same as `e` `(fieldwidth, 6, x)`.
`static String` | `E(int fieldwidth, double x)` Same as `E` `(fieldwidth, 6, x)`.
`static String` | `e(int fieldwidth, int precision, double x)` The same as `E`, except that ``e'` is used as the exponent character instead of ``E'`.
`static String` | `E(int fieldwidth, int precision, double x)` Formats a double-precision number `x` like `%E` in C `printf`.
`static String` | `f(double x)` Same as `f` `(0, 6, x)`.
`static String` | `f(int fieldwidth, double x)` Same as `f` `(fieldwidth, 6, x)`.
`static String` | `f(int fieldwidth, int precision, double x)` Formats the double-precision `x` into a string like `%f` in C `printf`.
`static String` | `format(int fieldwidth, int accuracy, int precision, double x)` Returns a `String` containing `x`.
`static String` | `format(int fieldwidth, long x)` Converts a long integer to a `String` with a minimum length of `fieldwidth`, the result is right-padded with spaces if necessary but it is not truncated.
`static String` | `format(Locale locale, int fieldwidth, int accuracy, int precision, double x)` This method is equivalent to `format`, except it formats the given value for the locale `locale`.
`static String` | `format(long x)` Same as `d` `(0, 1, x)`.
`static String` | `formatBase(int fieldwidth, int b, long x)` Converts the integer `x` to a `String` representation in base `b`.
`static String` | `formatBase(int b, long x)` Same as `formatBase` `(0, b, x)`.
`static void` | `formatWithError(int fieldwidth, int fieldwidtherr, int precision, double x, double error, String[] res)` Stores a string containing `x` into `res[0]`, and a string containing `error` into `res[1]`, both strings being formatted with the same notation.
`static void` | `formatWithError(int fieldwidth, int fieldwidtherr, int accuracy, int precision, double x, double error, String[] res)` Stores a string containing `x` into `res[0]`, and a string containing `error` into `res[1]`, both strings being formatted with the same notation.
`static void` | `formatWithError(Locale locale, int fieldwidth, int fieldwidtherr, int precision, double x, double error, String[] res)` This method is equivalent to `formatWithError`, except that it formats the given value and error for the locale `locale`.
`static void` | `formatWithError(Locale locale, int fieldwidth, int fieldwidtherr, int accuracy, int precision, double x, double error, String[] res)` This method is equivalent to `formatWithError`, except that it formats the given value and error for the locale `locale`.
`static String` | `g(double x)` Same as `g` `(0, 6, x)`.
`static String` | `G(double x)` Same as `G` `(0, 6, x)`.
`static String` | `g(int fieldwidth, double x)` Same as `g` `(fieldwidth, 6, x)`.
`static String` | `G(int fieldwidth, double x)` Same as `G` `(fieldwidth, 6, x)`.
`static String` | `g(int fieldwidth, int precision, double x)` The same as `G`, except that ``e'` is used in the scientific notation.
`static String` | `G(int fieldwidth, int precision, double x)` Formats the double-precision `x` into a string like `%G` in C `printf`.
`StringBuffer` | `getBuffer()` Returns the `StringBuffer` associated with that object.
`int` | `length()`
`static String` | `s(int fieldwidth, String str)` Formats the string `str` like the `%s` in the C `printf` function.
`static String` | `s(String str)` Same as `s` `(0, str)`.
`CharSequence` | `subSequence(int start, int end)`
`String` | `toString()` Converts the buffer into a `String`.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### LINE_SEPARATOR

    public static final String LINE_SEPARATOR

  End-of-line symbol or line separator. It is '' \n'' for Unix/Linux, " \r \n" for MS-DOS/MS-Windows, and '' \r '' for Apple OSX.

Constructor Detail

### PrintfFormat

    public PrintfFormat()

  Constructs a new buffer object containing an empty string.

### PrintfFormat

    public PrintfFormat(int length)

  Constructs a new buffer object with an initial capacity of `length`.

  Parameters:
    `length` - initial length of the buffer

### PrintfFormat

    public PrintfFormat(String str)

  Constructs a new buffer object containing the initial string `str`.

  Parameters:
    `str` - initial contents of the buffer

Method Detail

### append

    public PrintfFormat append(String str)

  Appends `str` to the buffer.

  Parameters:
    `str` - string to append to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int fieldwidth,
                               String str)

  Uses the `s` static method to append `str` to the buffer. A minimum of `fieldwidth` characters will be used.

  Parameters:
    `fieldwidth` - minimum number of characters that will be added to the buffer
    `str` - string to append to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(double x)

  Appends `x` to the buffer.

  Parameters:
    `x` - value being added to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int fieldwidth,
                               double x)

  Uses the `f` static method to append `x` to the buffer. A minimum of `fieldwidth` characters will be used.

  Parameters:
    `fieldwidth` - minimum length of the converted string to be appended
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int fieldwidth,
                               int precision,
                               double x)

  Uses the `f` static method to append `x` to the buffer. A minimum of `fieldwidth` characters will be used with the given `precision`.

  Parameters:
    `fieldwidth` - minimum length of the converted string to be appended
    `precision` - number of digits after the decimal point of the converted value
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int x)

  Appends `x` to the buffer.

  Parameters:
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int fieldwidth,
                               int x)

  Uses the `d` static method to append `x` to the buffer. A minimum of `fieldwidth` characters will be used.

  Parameters:
    `fieldwidth` - minimum length of the converted string to be appended
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(long x)

  Appends `x` to the buffer.

  Parameters:
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int fieldwidth,
                               long x)

  Uses the `d` static method to append `x` to the buffer. A minimum of `fieldwidth` characters will be used.

  Parameters:
    `fieldwidth` - minimum length of the converted string to be appended
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(int fieldwidth,
                               int accuracy,
                               int precision,
                               double x)

  Uses the `format` static method with the same four arguments to append `x` to the buffer.

  Parameters:
    `fieldwidth` - minimum length of the converted string to be appended
    `accuracy` - number of digits after the decimal point
    `precision` - number of significant digits
    `x` - value to be appended to the buffer
  Returns:
    this object

### append

    public PrintfFormat append(char c)

  Appends a single character to the buffer.

  Specified by:
    `append` in interface `Appendable`
  Parameters:
    `c` - character to be appended to the buffer
  Returns:
    this object

### clear

    public void clear()

  Clears the contents of the buffer.

### getBuffer

    public StringBuffer getBuffer()

  Returns the `StringBuffer` associated with that object.

  Returns:
    the internal `StringBuffer` object

### toString

    public String toString()

  Converts the buffer into a `String`.

  Specified by:
    `toString` in interface `CharSequence`
  Overrides:
    `toString` in class `Object`
  Returns:
    the `String` conversion of the internal buffer

### s

    public static String s(String str)

  Same as `s` `(0, str)`. If the string `str` is null, it returns the string ``null''.

  Parameters:
    `str` - the string to process
  Returns:
    the same string

### s

    public static String s(int fieldwidth,
                           String str)

  Formats the string `str` like the `%s` in the C `printf` function. The `fieldwidth` argument gives the minimum length of the resulting string. If `str` is shorter than `fieldwidth`, it is left-padded with spaces. If `fieldwidth` is negative, the string is right-padded with spaces if necessary. The `String` will never be truncated. If `str` is null, it calls `s` `(fieldwidth, ``null'')`.

  The `fieldwidth` argument has the same effect for the other methods in this class.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `str` - the string to process
  Returns:
    the same string padded with spaces if necessary

### d

    public static String d(long x)

  Same as `d` `(0, 1, x)`.

  Parameters:
    `x` - the string to process
  Returns:
    the same string, padded with spaces or zeros if appropriate

### d

    public static String d(int fieldwidth,
                           long x)

  Same as `d` `(fieldwidth, 1, x)`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the string to process
  Returns:
    the same string, padded with spaces or zeros if appropriate

### d

    public static String d(int fieldwidth,
                           int precision,
                           long x)

  Formats the long integer `x` into a string like `%d` in the C `printf` function. It converts its argument to decimal notation, `precision` gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. When zero is printed with an explicit precision 0, the output is empty.

  If the one-argument form is used, a `fieldwidth` of 0 is assumed and a `precision` of 1 is used. If the two-arguments method is used, a `precision` of 1 is assumed.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `precision` - number of digits in the returned string
    `x` - the string to process
  Returns:
    the same string, padded with spaces or zeros if appropriate

### format

    public static String format(long x)

  Same as `d` `(0, 1, x)`.

  Parameters:
    `x` - the value to be processed
  Returns:
    the string resulting from the conversion

### format

    public static String format(int fieldwidth,
                                long x)

  Converts a long integer to a `String` with a minimum length of `fieldwidth`, the result is right-padded with spaces if necessary but it is not truncated. If only one argument is specified, a `fieldwidth` of 0 is assumed.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the value to be processed
  Returns:
    the string resulting from the conversion

### formatBase

    public static String formatBase(int b,
                                    long x)

  Same as `formatBase` `(0, b, x)`.

  Parameters:
    `b` - the base used for conversion
    `x` - the value to be processed
  Returns:
    a string representing `x` in base `b`

### formatBase

    public static String formatBase(int fieldwidth,
                                    int b,
                                    long x)

  Converts the integer `x` to a `String` representation in base `b`.

  Restrictions: 2 <= `b` <= 10

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `b` - the base used for conversion
    `x` - the value to be processed
  Returns:
    a string representing `x` in base `b`

### E

    public static String E(double x)

  Same as `E` `(0, 6, x)`.

  Parameters:
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### E

    public static String E(int fieldwidth,
                           double x)

  Same as `E` `(fieldwidth, 6, x)`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### E

    public static String E(int fieldwidth,
                           int precision,
                           double x)

  Formats a double-precision number `x` like `%E` in C `printf`. The double argument is rounded and converted in the style `[-]d.dddE+-dd` where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is 0, no decimal-point character appears. The exponent always contains at least two digits; if the value is zero, the exponent is `00`.

  If the one-argument form is used, a `fieldwidth` of 0 and a `precision` of 6 are used. If the two-arguments form is used, a `precision` of 6 is assumed.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `precision` - number of digits after the decimal point
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### e

    public static String e(double x)

  Same as `e` `(0, 6, x)`.

  Parameters:
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### e

    public static String e(int fieldwidth,
                           double x)

  Same as `e` `(fieldwidth, 6, x)`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### e

    public static String e(int fieldwidth,
                           int precision,
                           double x)

  The same as `E`, except that ``e'` is used as the exponent character instead of ``E'`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `precision` - number of digits after the decimal point
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### f

    public static String f(double x)

  Same as `f` `(0, 6, x)`.

  Parameters:
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### f

    public static String f(int fieldwidth,
                           double x)

  Same as `f` `(fieldwidth, 6, x)`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### f

    public static String f(int fieldwidth,
                           int precision,
                           double x)

  Formats the double-precision `x` into a string like `%f` in C `printf`. The argument is rounded and converted to decimal notation in the style `[-]ddd.ddd`, where the number of digits after the decimal-point character is equal to the precision specification. If the precision is explicitly 0, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.

  If the one-argument form is used, a `fieldwidth` of 0 and a `precision` of 6 are used. If the two-arguments form is used, a `precision` of 6 is assumed.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `precision` - number of digits after the decimal point
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### G

    public static String G(double x)

  Same as `G` `(0, 6, x)`.

  Parameters:
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### G

    public static String G(int fieldwidth,
                           double x)

  Same as `G` `(fieldwidth, 6, x)`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### G

    public static String G(int fieldwidth,
                           int precision,
                           double x)

  Formats the double-precision `x` into a string like `%G` in C `printf`. The argument is converted in style `%f` or `%E`. `precision` specifies the number of significant digits. If it is 0, it is treated as 1. Style `%E` is used if the exponent from its conversion is less than -4 or greater than or equal to `precision`. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.

  If the one-argument form is used, a `fieldwidth` of 0 and a `precision` of 6 are used. If the two-arguments form is used, a `precision` of 6 is assumed.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `precision` - number of significant digits
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### g

    public static String g(double x)

  Same as `g` `(0, 6, x)`.

  Parameters:
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### g

    public static String g(int fieldwidth,
                           double x)

  Same as `g` `(fieldwidth, 6, x)`.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### g

    public static String g(int fieldwidth,
                           int precision,
                           double x)

  The same as `G`, except that ``e'` is used in the scientific notation.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `precision` - number of significant digits
    `x` - the value to be converted to string
  Returns:
    the converted value as a string

### format

    public static String format(int fieldwidth,
                                int accuracy,
                                int precision,
                                double x)

  Returns a `String` containing `x`. Uses a total of at least `fieldwidth` positions (including the sign and point when they appear), `accuracy` digits after the decimal point and at least `precision` significant digits. `accuracy` and `precision` must be strictly smaller than `fieldwidth`. The number is rounded if necessary. If there is not enough space to format the number in decimal notation with at least `precision` significant digits (`accuracy` or `fieldwidth` is too small), it will be converted to scientific notation with at least `precision` significant digits. In that case, `fieldwidth` is increased if necessary.

  Parameters:
    `fieldwidth` - minimum length of the returned string
    `accuracy` - number of digits after the decimal point
    `precision` - number of significant digits
    `x` - the value to be processed
  Returns:
    the converted value as a string

### format

    public static String format(Locale locale,
                                int fieldwidth,
                                int accuracy,
                                int precision,
                                double x)

  This method is equivalent to `format`, except it formats the given value for the locale `locale`.

  Parameters:
    `locale` - the locale being used for formatting
    `fieldwidth` - minimum length of the returned string
    `accuracy` - number of digits after the decimal point
    `precision` - number of significant digits
    `x` - the value to be processed
  Returns:
    the converted value as a string

### charAt

    public char charAt(int index)

  Specified by:
    `charAt` in interface `CharSequence`

### length

    public int length()

  Specified by:
    `length` in interface `CharSequence`

### subSequence

    public CharSequence subSequence(int start,
                                    int end)

  Specified by:
    `subSequence` in interface `CharSequence`

### append

    public Appendable append(CharSequence csq)

  Specified by:
    `append` in interface `Appendable`

### append

    public Appendable append(CharSequence csq,
                             int start,
                             int end)

  Specified by:
    `append` in interface `Appendable`

### formatWithError

    public static void formatWithError(int fieldwidth,
                                       int fieldwidtherr,
                                       int accuracy,
                                       int precision,
                                       double x,
                                       double error,
                                       String[] res)

  Stores a string containing `x` into `res[0]`, and a string containing `error` into `res[1]`, both strings being formatted with the same notation. Uses a total of at least `fieldwidth` positions (including the sign and point when they appear) for `x`, `fieldwidtherr` positions for `error`, `accuracy` digits after the decimal point and at least `precision` significant digits. `accuracy` and `precision` must be strictly smaller than `fieldwidth`. The numbers are rounded if necessary. If there is not enough space to format `x` in decimal notation with at least `precision` significant digits (`accuracy` or `fieldwidth` are too small), it will be converted to scientific notation with at least `precision` significant digits. In that case, `fieldwidth` is increased if necessary, and the error is also formatted in scientific notation.

  Parameters:
    `fieldwidth` - minimum length of the value string
    `fieldwidtherr` - minimum length of the error string
    `accuracy` - number of digits after the decimal point for the value and error
    `precision` - number of significant digits for the value
    `x` - the value to be processed
    `error` - the error on the value to be processed
    `res` - an array that will be filled with the formatted value and formatted error

### formatWithError

    public static void formatWithError(int fieldwidth,
                                       int fieldwidtherr,
                                       int precision,
                                       double x,
                                       double error,
                                       String[] res)

  Stores a string containing `x` into `res[0]`, and a string containing `error` into `res[1]`, both strings being formatted with the same notation. This calls `formatWithError` with the minimal accuracy for which the formatted string for `error` is non-zero. If `error` is 0, the accuracy is 0. If this minimal accuracy causes the strings to be formatted using scientific notation, this method increases the accuracy until the decimal notation can be used.

  Parameters:
    `fieldwidth` - minimum length of the value string
    `fieldwidtherr` - minimum length of the error string
    `precision` - number of significant digits for the value
    `x` - the value to be processed
    `error` - the error on the value to be processed
    `res` - an array that will be filled with the formatted value and formatted error

### formatWithError

    public static void formatWithError(Locale locale,
                                       int fieldwidth,
                                       int fieldwidtherr,
                                       int accuracy,
                                       int precision,
                                       double x,
                                       double error,
                                       String[] res)

  This method is equivalent to `formatWithError`, except that it formats the given value and error for the locale `locale`.

  Parameters:
    `locale` - the locale being used
    `fieldwidth` - minimum length of the value string
    `fieldwidtherr` - minimum length of the error string
    `accuracy` - number of digits after the decimal point for the value and error
    `precision` - number of significant digits for the value
    `x` - the value to be processed
    `error` - the error on the value to be processed
    `res` - an array that will be filled with the formatted value and formatted error

### formatWithError

    public static void formatWithError(Locale locale,
                                       int fieldwidth,
                                       int fieldwidtherr,
                                       int precision,
                                       double x,
                                       double error,
                                       String[] res)

  This method is equivalent to `formatWithError`, except that it formats the given value and error for the locale `locale`.

  Parameters:
    `locale` - the locale being used
    `fieldwidth` - minimum length of the value string
    `fieldwidtherr` - minimum length of the error string
    `precision` - number of significant digits for the value
    `x` - the value to be processed
    `error` - the error on the value to be processed
    `res` - an array that will be filled with the formatted value and formatted error

Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

To submit a bug or ask questions, send an e-mail to Pierre L'Ecuyer.