lava.clib.stdio
Class PrintfFormatString

java.lang.Object
  |
  +--lava.clib.stdio.PrintfFormatString

public final class PrintfFormatString

extends java.lang.Object

Precompiled text and data formatting template.

Details: A PrintfFormatString is a preparsed representation of a Lava printf format string. The constructor for this class accepts a regular String object and parses it into a representation that is ready for use in other printf-related classes and methods.

All printf-related methods and classes in the lava.* packages eventually require an instance of PrintfFormatString in order to generate output. This instance can be created manually by the programmer or automatically by Lava. In other words, when the caller passes a format string to Stdio.printf, it can be pass as a String object or a PrintfFormatString object. This is demonstrated in the examples below:

Declarations for the following examples:

String friend_name = "Sharky";
int friend_age = 27;
Object[] subst_args = new Object[]
{
	friend_name,
	new Integer (friend_age)
};

Example 1: Sending the printf formatting information as a String object:

Stdio.printf
(
	"My friend %s is %d years old.\n",
	subst_args
);

Example 2: Sending the printf formatting information as a PrintfFormatString object:

Stdio.printf
(
	new PrintfFormatString ("My friend %s is %d years old.\n"),
	subst_args
);

Examples 1 and 2 produce exactly the same output, and require exactly the same amount of execution time and system resources. The only difference between the two is that the first example requires Stdio.printf to "automatically" generate a PrintfFormatString during the call, whereas the second example creates one prior to the call. Other factors being equal, the first example is preferred simply because it is more readable.

However, if the call to Stdio.printf is inside a loop, where multiple lines of output are produced using exactly the same formatting template, then it is more efficient to parse the format string just once, prior to entering the loop, and reuse the parsed result. The only way to do this is to explicitely initialize the PrintfFormatString yourself.

Example 3: Optimizing a print loop by compiling the format string outside the loop:

PrintfFormatString format_string = new PrintfFormatString
(
	"%d bottles of beer on the wall.\n"
);
for (int i = 99; i > 0; -- i)
{
	Stdio.printf
	(
		format_string,
		new Object[]
		{
			new Integer (i)
		}
	);
}

Preliminary measurements have shown that using precompiled format strings can speed up printf loops by 10-20%. For a complete description of properly formed printf format strings, see the Printf for Java format string specification.

See Also:

Stdio, Printf

Constructor Summary

PrintfFormatString(java.lang.String fmt)
Constructs a "digested" representation of the supplied format string.

Method Summary

lava.clib.stdio.Args	arg(byte b) Applies a byte to this format string.
lava.clib.stdio.Args	arg(char c) Applies a char to this format string.
lava.clib.stdio.Args	arg(double d) Applies a double to this format string.
lava.clib.stdio.Args	arg(float f) Applies a float to this format string.
lava.clib.stdio.Args	arg(int i) Applies an int to this format string.
lava.clib.stdio.Args	arg(long l) Applies a long to this format string.
lava.clib.stdio.Args	arg(java.lang.Object o) Applies an Object to this format string.
lava.clib.stdio.Args	arg(short s) Applies a short to this format string.
int	argsRequired() Returns the length of the argument list required by this format string.
java.lang.String	toString() Returns the string used to construct this instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

PrintfFormatString

public PrintfFormatString(java.lang.String fmt)

Constructs a "digested" representation of the supplied format string.

Parameters:

fmt - the format string

Throws:

PrintfFormatException - if the format string contains syntax errors

Method Detail

argsRequired

public int argsRequired()

Returns the length of the argument list required by this format string.

Returns:

the length

toString

public java.lang.String toString()

Returns the string used to construct this instance.

Overrides:

toString in class java.lang.Object

Returns:

the original format string

arg

public lava.clib.stdio.Args arg(java.lang.Object o)

Applies an Object to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(double d)

Applies a double to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(float f)

Applies a float to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(long l)

Applies a long to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(int i)

Applies an int to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(short s)

Applies a short to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(byte b)

Applies a byte to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above

arg

public lava.clib.stdio.Args arg(char c)

Applies a char to this format string. The return value is an object for which you can either call arg again with an additional argument, or if all necessary arguments have been applied, an object that is ready to produce formatted output when the toString() method is called.

Parameters:

o - the Object

Returns:

see description above