com.sharkysoft.printf
Class PrintfTemplate

java.lang.Object
  com.sharkysoft.printf.PrintfTemplate

public final class PrintfTemplate

extends java.lang.Object

Precompiled formatting template.

Details: A PrintfTemplate is a preparsed representation of a Printf for Java format string. The constructor for this class accepts a regular String and parses it into a representation that is ready for use in Printf's formatting methods.

All Printf calls eventually require an instance of this class in order to generate output. The instance can either be created explicitly by the programmer or automatically by Printf for Java. In other words, when the caller passes a format string to Printf, it can be sent as a either a String or a PrintfTemplate. This is demonstrated in the examples below:

Declarations:

String name = "Sharky";
int age = 27;
Object[] data = new Object[] {name, new Integer(age)};

Example 1: Sending the printf format string as a String:

Printf.out("My friend %s is %d years old.\n", data);

Example 2: Sending the printf format string as a PrintfTemplate:

Printf.out
( new PrintfTemplate("My friend %s is %d years old.\n"), 
  data
);

Examples 1 and 2 produce exactly the same output, and require approximately the same amount of execution time and system resources. The only difference between the two is that the first example requires Printf to automatically generate a PrintfTemplate 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 Printf is inside a loop, where multiple lines of output are produced using exactly the same formatting template, then it is probably more efficient to parse the format string just once, prior to entering the loop, and then reuse the parsed result. The only way to accomplish this is to explicitely initialize the PrintfTemplate outside of the loop.

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

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

Preliminary measurements have shown that using precompiled format strings can speed up printf loops by 10-20%, but this of course depends on the complexity of the format string.

For the complete specification governing the syntax of valid printf format strings, see Printf for Java Specification 2.0.

Author:

Sharky

See Also:

Printf

Constructor Summary

PrintfTemplate(java.lang.String isFormat)
Parses format string.

Method Summary

int	argsRequired() Determines data vector length.
java.lang.String	toString() Returns original format string.

Methods inherited from class java.lang.Object

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

Constructor Detail

PrintfTemplate

public PrintfTemplate(java.lang.String isFormat)

Parses format string.

Details: This constructor parses the given format string and assembles a corresponding formatting engine. If the format string is invalid, a PrintfTemplateException will be thrown.

Parameters:

isFormat - the format string

Throws:

PrintfTemplateException - if the format string is invalid

Method Detail

argsRequired

public int argsRequired()

Determines data vector length.

Details: argsRequired determines and returns the minimum length of a suitable data vector.

Returns:

the minimum length

toString

public java.lang.String toString()

Returns original format string.

Details: toString returns the original format string used to initialize this instance.

Returns:

the format string