com.sharkysoft.printf
Class Printf

java.lang.Object
  com.sharkysoft.printf.Printf

public final class Printf

extends java.lang.Object

Main Printf For Java interface.

Details: Printf is the primary interface to Printf For Java. This singleton class includes methods for outputing printf-formatted text and data to the console, file streams, and buffers.

The formatting template for a printf request must be given as a String or a PrintfTemplate. The data to format in a printf request must be given as an Object array or a PrintfData.

For more information on both of these data structures, see the Printf for Java Specification 2.0.

Any of the formating methods in this class may throw the following exceptions:

• PrintfTemplateException - If the format template is invalid. Or, if the format template includes a variable width or precision, and the value supplied is negative.
• ClassCastException - If a converstion type requires a certain type of data, but the wrong data type is offered.
• NullPointerException - If the data vector is null, but the format template calls for data. Or, if a conversion type requires non-null data, but the data being converted is null.

Quick tip for C programmers: Programmers familiar with printf in C may find the following idiom translations useful.

C idiom	Printf for Java idiom
printf(fmt, arg1, arg2, ...)	Printf.out(fmt, new Object[] {arg1, arg2, ...})
sprintf(buff, fmt, arg1, arg2, ...)	buff = Printf.format(fmt, new Object[] {arg1, arg2, ...})
fprintf(out, fmt, arg1, arg2, ...)	Printf.write(out, fmt, new Object[] {arg1, arg2, ...})

Author:

Sharky

Method Summary

static java.lang.String	format(PrintfTemplate ipTemplate, java.lang.Object[] ioapData) Formats data to string.
static java.lang.String	format(java.lang.String isTemplate) Formats template to stdout.
static java.lang.String	format(java.lang.String isTemplate, java.lang.Object[] ioapData) Formats data to string.
static java.lang.String	format(java.lang.String isTemplate, PrintfData ipData) Formats data to string.
static int	out(PrintfTemplate ipTemplate, java.lang.Object[] ioapData) Formats data to stdout.
static int	out(java.lang.String isTemplate) Formats template to stdout.
static int	out(java.lang.String isTemplate, java.lang.Object[] ioapData) Formats data to stdout.
static int	out(java.lang.String isTemplate, PrintfData ipData) Formats data to stdout.
static int	write(java.io.Writer ipWriter, PrintfTemplate ipTemplate, java.lang.Object[] ioapData) Formats data to stream.
static int	write(java.io.Writer ipWriter, java.lang.String isTemplate) Formats template to stream.
static int	write(java.io.Writer ipWriter, java.lang.String isTemplate, java.lang.Object[] ioapData) Formats data to stream.
static int	write(java.io.Writer ipWriter, java.lang.String isTemplate, PrintfData ipData) Formats data to stream.

Methods inherited from class java.lang.Object

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

Method Detail

format

public static java.lang.String format(PrintfTemplate ipTemplate,
                                      java.lang.Object[] ioapData)

Formats data to string.

Details: format converts the given data into a string using the provided template. Elements in the data vector may be overwritten if the character counting format specifier is used. The template is pre-compiled for efficiency.

Parameters:

ipTemplate - the template

ioapData - the data

Returns:

the formatted string

See Also:

format(String, Object[]), format(String, PrintfData)

format

public static java.lang.String format(java.lang.String isTemplate,
                                      java.lang.Object[] ioapData)

Formats data to string.

Details: format converts the given data into a string using the provided template. Elements in the data vector may be overwritten if the character counting format specifier is used.

Parameters:

isTemplate - the template

ioapData - the data

Returns:

the formatted text

See Also:

format(PrintfTemplate, Object[]), format(String, PrintfData)

format

public static java.lang.String format(java.lang.String isTemplate,
                                      PrintfData ipData)

Formats data to string.

Details: format converts the given data into a string using the provided template. The data is given in a growable vector for convenience.

Parameters:

isTemplate - the template

ipData - the data

Returns:

the formatted string

See Also:

format(PrintfTemplate, Object[]), format(String, Object[])

format

public static java.lang.String format(java.lang.String isTemplate)

Formats template to stdout.

Details: format converts the given template to a string. Only format strings which do not require a data vector can be used with this method.

Parameters:

isTemplate - the template

Returns:

the formatted string

See Also:

format(PrintfTemplate, Object[]), format(String, Object[]), format(String, PrintfData)

out

public static int out(PrintfTemplate ipTemplate,
                      java.lang.Object[] ioapData)

Formats data to stdout.

Details: format converts the given data into a string using the provided template and then outputs it to System.out, which is usually the console. The number of characters output is returned. Elements in the data vector may be overwritten if the character counting format specifier is used. The template is pre-compiled for efficiency.

Parameters:

ipTemplate - the template

ioapData - the data

Returns:

the number of characters output

See Also:

out(String, Object[]), out(String, PrintfData), out(String)

out

public static int out(java.lang.String isTemplate,
                      java.lang.Object[] ioapData)

Formats data to stdout.

Details: format converts the given data into a string using the provided template and then outputs it to System.out, which is usually the console. The number of characters output is returned. Elements in the data vector may be overwritten if the character counting format specifier is used.

Parameters:

isTemplate - the template

ioapData - the data

Returns:

the number of characters output

See Also:

out(PrintfTemplate, Object[]), out(String, PrintfData), out(String)

out

public static int out(java.lang.String isTemplate,
                      PrintfData ipData)

Formats data to stdout.

Details: format converts the given data into a string using the provided template and then outputs it to System.out, which is usually the console. The number of characters output is returned. The data is given in a growable vector for convenience.

Parameters:

isTemplate - the template

ipData - the data

Returns:

the number of characters output

See Also:

out(PrintfTemplate, Object[]), out(String, Object[]), out(String)

out

public static int out(java.lang.String isTemplate)

Formats template to stdout.

Details: format converts the given template to a string and then outputs it to System.out, which is usually the console. The number of characters output is returned. Only format strings which do not require a data vector can be used with this method.

Parameters:

isTemplate - the template

Returns:

the number of characters output

See Also:

out(PrintfTemplate, Object[]), out(String, Object[]), out(String, PrintfData)

write

public static int write(java.io.Writer ipWriter,
                        PrintfTemplate ipTemplate,
                        java.lang.Object[] ioapData)
                 throws java.io.IOException

Formats data to stream.

Details: write converts the given data into a string using the provided template and then writes it to the given stream. The number of characters output is returned. Elements in the data vector may be overwritten if the character counting format specifier is used. The template is pre-compiled for efficiency.

Parameters:

ipWriter - the stream

ipTemplate - the template

ioapData - the data

Returns:

the number of characters output

Throws:

java.io.IOException - if writing to the stream causes an IOException

See Also:

write(Writer, String, Object[]), write(Writer, String, PrintfData), write(Writer, String)

write

public static int write(java.io.Writer ipWriter,
                        java.lang.String isTemplate,
                        java.lang.Object[] ioapData)
                 throws java.io.IOException

Formats data to stream.

Details: write converts the given data into a string using the provided template and then outputs it to the given stream. The number of characters output is returned. Elements in the data vector may be overwritten if the character counting format specifier is used.

Parameters:

ipWriter - the stream

isTemplate - the template

ioapData - the data

Returns:

the number of characters output

Throws:

java.io.IOException - if writing to the stream causes an IOException

See Also:

write(Writer, PrintfTemplate, Object[]), write(Writer, String, PrintfData), write(Writer, String)

write

public static int write(java.io.Writer ipWriter,
                        java.lang.String isTemplate,
                        PrintfData ipData)
                 throws java.io.IOException

Formats data to stream.

Details: write converts the given data into a string using the provided template and then outputs it to the given stream. The number of characters output is returned. The data is given in a growable vector for convenience.

Parameters:

ipWriter - the stream

isTemplate - the template

ipData - the data

Returns:

the number of characters output

Throws:

java.io.IOException - if writing to the stream causes an IOException

See Also:

write(Writer, PrintfTemplate, Object[]), write(Writer, String, Object[]), write(Writer, String)

write

public static int write(java.io.Writer ipWriter,
                        java.lang.String isTemplate)
                 throws java.io.IOException

Formats template to stream.

Details: write converts the given template into a string and then outputs it to the given stream. The number of characters output is returned. Only format strings which do not require a data vector can be used with this method.

Parameters:

ipWriter - the stream

isTemplate - the template

Returns:

the number of characters output

Throws:

java.io.IOException - if writing to the stream causes an IOException

See Also:

write(Writer, PrintfTemplate, Object[]), write(Writer, String, Object[]), write(Writer, String, PrintfData)