SSJ
V. 2.6.

umontreal.iro.lecuyer.util
Class PrintfFormat

java.lang.Object
  extended by 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, `` \r \n" 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| < 263.

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

SSJ
V. 2.6.

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