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 Java class Formatter for performing locale-independent formatting.

Field Summary

static String	LINE_SEPARATOR End-of-line symbol or line separator.
static String	NEWLINE 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 accuracy, int b, double x) Converts x to a String representation in base b using formatting similar to the f methods.
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

NEWLINE

public static final String NEWLINE

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

LINE_SEPARATOR

public static final String LINE_SEPARATOR

End-of-line symbol or line separator. Same as NEWLINE.

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.

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.

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.

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.

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

formatBase

public static String formatBase(int fieldwidth,
                                int accuracy,
                                int b,
                                double x)

Converts x to a String representation in base b using formatting similar to the f methods. Uses a total of at least fieldwidth positions (including the sign and point when they appear) and accuracy digits after the decimal point. If fieldwidth is negative, the number is printed left-justified, otherwise right-justified. Restrictions: 2 <= b <= 10 and | x| < 2⁶³.

Parameters:

fieldwidth - minimum length of the returned string

accuracy - number of digits after the decimal point

b - base

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