ucb.io
Class FormatWriter

java.lang.Object
  |
  +--java.io.Writer
        |
        +--java.io.FilterWriter
              |
              +--ucb.io.FormatWriter

public class FormatWriter

extends java.io.FilterWriter

Provides for printf-like formatted output of text. A typical use of this class for formatted output:

     stream.format("%s's age is %d\n").put(name).put(age);
 

The format command establishes the format for next two calls of the put member functions. For convenience, format and put return the FormatWriter from which they are called to allow the composition shown. It would have the same effect to write

     stream.format("%s's age is %d\n");
     stream.put(name);
     stream.put(age);
 

In the absence of a format, or when all items in the last format are exhausted, output is printed in a default format, depending on the type of the input item: %d for integer types and boolean, %g for floating-point types, and %s for all other types.

Thus, in the absence of a format, the package behaves similarly to the iostream package in the standard C++ library, with the put functions playing the role of the << operator. The member functions width, precision, and fill set formatting parameters for the next item sent to put; this handles the functionality of both the member functions with those names in C++ and also of '*' used as a width or precision in a C format string.

Fields inherited from class java.io.FilterWriter

out

Fields inherited from class java.io.Writer

lock

Constructor Summary

FormatWriter(java.io.OutputStream out)

FormatWriter(java.io.OutputStream out, boolean flush)

FormatWriter(java.io.Writer out)
Create a new FormatWriter that sends output to a given stream.

FormatWriter(java.io.Writer out, boolean flush)
Create a new FormatWriter that sends output to a given stream, and optionally set to flush on each format and put operation.

Method Summary

boolean	checkError() Reports I/O errors other than a FormatException.
void	close() Flush and close output stream.
int	count() Reports the number of characters sent to the stream since the latest call to format (or the construction of this FormatWriter, if there has been no such call).
void	disconnect() Flush the underlying stream and then disassociate it from THIS without closing that stream.
FormatWriter	fill(char c) Set the fill character for the next call to put.
protected void	finalize() At finish, flush all pending output.
void	flush() Flush all pending output, insuring that it gets written.
FormatWriter	format(java.lang.String s) Set the current format.
FormatWriter	precision(int n) Set the precision for the next call to put.
FormatWriter	put(boolean x) Output a boolean as if it were the integer 1 for true, or 0 for false.
FormatWriter	put(char c) Output C as a single character.
FormatWriter	put(char[] s) Output an array of characters as for a string of the same length.
FormatWriter	put(double x) Output a floating-point value according to the current format directive.
FormatWriter	put(int x) Output an int value according to the current format directive.
FormatWriter	put(long x) Output a long value according to the current format directive.
FormatWriter	put(java.lang.Object obj) Output an arbitrary Object as a string.
FormatWriter	put(java.lang.String s) Output a String according to the current format item.
void	reopen(java.io.Writer out, boolean flush) Reopen THIS to write to OUT, setting automatic flushing of pending output on each operation iff FLUSH.
FormatWriter	width(int n) Set the field width for the next call to put.

Methods inherited from class java.io.FilterWriter

write, write, write

Methods inherited from class java.io.Writer

write, write

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormatWriter

public FormatWriter(java.io.Writer out)

Create a new FormatWriter that sends output to a given stream.

Parameters:

out - the stream that receives formatted output

FormatWriter

public FormatWriter(java.io.Writer out,
                    boolean flush)

Create a new FormatWriter that sends output to a given stream, and optionally set to flush on each format and put operation.

Parameters:

out - the stream that receives formatted output

flush - if true, flush pending output on each operation.

FormatWriter

public FormatWriter(java.io.OutputStream out)

FormatWriter

public FormatWriter(java.io.OutputStream out,
                    boolean flush)

Method Detail

reopen

public void reopen(java.io.Writer out,
                   boolean flush)

Reopen THIS to write to OUT, setting automatic flushing of pending output on each operation iff FLUSH. Closes THIS first, if needed.

flush

public void flush()

Flush all pending output, insuring that it gets written.

Overrides:

flush in class java.io.FilterWriter

close

public void close()

Flush and close output stream. All further operations invalid until a subsequent reopen.

Overrides:

close in class java.io.FilterWriter

disconnect

public void disconnect()

Flush the underlying stream and then disassociate it from THIS without closing that stream. THIS is closed and cannot be used again unless reopened.

finalize

protected void finalize()

At finish, flush all pending output.

Overrides:

finalize in class java.lang.Object

checkError

public boolean checkError()

Reports I/O errors other than a FormatException. FormatWriter does not throw exceptions as a result of I/O errors on its OutputStream. Instead, it sets an internal, sticky flag that is reported by this function.

Returns:

True iff an error (other than FormatException and other RuntimeExceptions) has occurred.

count

public int count()

Reports the number of characters sent to the stream since the latest call to format (or the construction of this FormatWriter, if there has been no such call).

format

public FormatWriter format(java.lang.String s)
                    throws java.lang.NullPointerException

Set the current format. Outputs the portion of the new format up to the first format item that requires data. Any previous formatting string is discarded.

The format consists of ordinary characters interspersed with formatting directives, introduced with the '%' character. Characters not included in the formatting directives are output as soon as they are encountered. A '%' character may be included by writing it as '%%'.

Each formatting directive consists of

• Zero or more flags.
• An optional decimal number specifying a minimum field width. The converted string, if shorter than the field width, is padded to that width---usually with blanks---on the left, or, in the presence of the '-' flag, on the right. If the first digit of the field width is 0 and the output is right-justified, then the fill character is '0'. Otherwise, the default fill character is used (usually blank). If a field width is not supplied, the default is used (usually 0).
• A precision, consisting of a period ('.') followed by a decimal number (a null digit string counts as 0).
• An optional 'l' (ell) character, which is ignored (it is included for compatibility with the C library, where it is intended to distinguish long and double arguments from int and float arguments).
• A format code, indicating the conversion desired.

The possible flag characters are as follows:

-

Left-justify the result of conversion.

+

Always begin a signed conversion with a sign (+ or -). Ignored for unsigned or non-numeric conversions.

blank

If the first character of a signed conversion is not + or -, insert a blank. Ignored for unsigned or non-numeric conversions, or in the presence of the + flag.

#

Use an alternate form, where applicable (see individual conversion codes.)

The conversion codes are as follows:

d, i, o, u, x, X

Expect an integral or boolean argument, treating boolean true as 1 and false as 0. Convert to signed decimal (d, i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x, X, p). x uses lower-case 'abcdef' for digits beyond 9 and X uses upper-case 'ABCDEF.' The precision gives a minimum number of digits to print; the number will be padded on the left with 0s if needed to get this size. The effective default is 1. Printing 0 with a precision of 0 gives the null string. With the '#' flag, x and X conversions precede the digits with 0x or 0X, and o conversions force a 0 as the first digit. Treats arguments of type Boolean, Character, Integer, or Long as booleans, chars, ints, or longs.

s

Expect a String, a char[] array, a byte[] array, or any other kind of Object for which toString yields a value without throwing an exception. Prints the character or byte string represented (or returned by toString) as a byte stream (throwing away the high-order byte of any char values). If a precision, p is specified, then at most the first p characters of the string will be printed.

c

Expect an integral quantity as for d, i, etc. Convert to the ASCII character represented by the lower 8 bits of the value. Treats arguments of type Boolean, Character, Integer, or Long as booleans, chars, ints, or longs.

f

Expect a floating-point quantity: types float, double, Float, or Double. Converts to a fixed-format decimal number that always has at least a units position, and has the number of digits after the decimal point as given by the precision (default 6). When the precision is 0, there is no decimal point unless the '#' flag is present. NaN (Not a Number) prints as "NaN" and infinities print as "[-]Infinity". Treats types Float and Double as float or double.

e, E

Expect a floating-point quantity: types float, double, Float, or Double. Converts to a format [-]x.xxx...e+-yyy (or [-]x.xxx...E+-yyy for E format), where '+-yyy' is an exponent of 10. The exponent always has two or three digits, and there is always at least one digit before the point (there are more only if the number is 0-padded; the first significant digit is always in the units place). The number of digits after the decimal point is given by the precision (default 5). When the precision is 0, there is no decimal point unless the '#' flag is present. NaN (Not a Number) prints as "NaN" and infinities print as "[-]Infinity". Treats types Float and Double as float or double.

g, G

Expect a floating-point quantity: types float, double, Float, or Double. Converts either as for f format or e format (E for G), depending on the magnitude of the value converted. Non-zero values with absolute magnitudes less than 1e-4 or greater than 1e+p, where p is the precision (default 6) print in e or E format with precision p-1. Other values print in f format, with the precision indicating the number of significant digits. Normally, trailing 0 digits in the fraction are suppressed and there is no decimal point printed if there are no fractional digits printed. Both of these conventions are overridden when the '#' flag is supplied.

Parameters:

s - the new format string

Returns:

this.

Throws:

java.lang.NullPointerException - the argument is null.

put

public FormatWriter put(int x)
                 throws FormatException

Output an int value according to the current format directive. Use the default integer format if no format is current. If there is a format, it must specify one of the integer format directives: d, i, o, u, x, X. Resets the formatting parameters to their defaults.

Parameters:

x - the value to format

Returns:

this

Throws:

FormatException - if the next format directive is not a valid integral format directive.

put

public FormatWriter put(long x)
                 throws FormatException

Output a long value according to the current format directive. Use the default integer format if no format is current. If there is a format, it must specify one of the integer format directives: d, i, o, u, x, X. Resets the formatting parameters to their defaults.

Parameters:

x - the value to format

Returns:

this

Throws:

FormatException - if the next format directive is not a valid integral format directive.

put

public FormatWriter put(double x)
                 throws FormatException

Output a floating-point value according to the current format directive. Use the default %g format if no format is current. If there is a format, it must specify one of the floating-point format directives: e, f, g. Resets the formatting parameters to their defaults.

Parameters:

x - the value to format

Returns:

this

Throws:

FormatException - if the next format directive is not a valid floating-point format directive.

put

public FormatWriter put(boolean x)
                 throws FormatException

Output a boolean as if it were the integer 1 for true, or 0 for false.

See Also:

put(int)

put

public FormatWriter put(char c)
                 throws FormatException

Output C as a single character.

Returns:

this.

Throws:

FormatException - if the next format directive is not valid for outputing characters.

put

public FormatWriter put(java.lang.String s)
                 throws FormatException

Output a String according to the current format item. Use the default string format if no format is current. If there is a format, it must specify a %s item. Resets the formatting parameters to their defaults.

Parameters:

s - the string to output

Returns:

this

Throws:

FormatException - if the next format directive is not a valid string format directive.

put

public FormatWriter put(char[] s)
                 throws java.lang.NullPointerException,
                        FormatException

Output an array of characters as for a string of the same length.

Parameters:

s - the array to output.

Returns:

this

Throws:

FormatException - if the next format directive is not a valid string format directive.

See Also:

put(java.lang.String)

put

public FormatWriter put(java.lang.Object obj)
                 throws FormatException

Output an arbitrary Object as a string. This makes a special case of objects whose dynamic type is derived from one of the special boxed types Integer, Long, Character, Boolean, Float, Double: if the corresponding format item is appropriate for the unboxed value, the value is formatted accordingly. Otherwise, this is the same as performing put on obj.toString().

See Also:

put(java.lang.String)

width

public FormatWriter width(int n)

Set the field width for the next call to put. Sets the default field width for the next call to one of the put member functions (an explicit field width in a format item thus overrides this call). The default field width is reset to 0 after each call on put.

Parameters:

n - the default field width

Returns:

this

See Also:

format(java.lang.String)

precision

public FormatWriter precision(int n)

Set the precision for the next call to put. Sets the default precision for the next call to one of the put member functions (an explicit precision in a format item thus overrides this call). The default precision is reset after each call on put.

Parameters:

n - the default precision

Returns:

this

See Also:

format(java.lang.String)

fill

public FormatWriter fill(char c)

Set the fill character for the next call to put. Sets the default fill character for the next call to one of the put member functions (an '0' at the beginning of a field width in a format directive thus overrides this call). The default fill character is reset to blank after each call on put.

Parameters:

c - the default fill character

Returns:

this

See Also:

format(java.lang.String)