8.6 QuickFormat

The QuickFormat class provides a convenient interface for the combined functionality of TextPicture, TextAlignment, NumericPicture, and NumericFormat. Typically, you should start with a picture string, then set formatting parameters and substitute in values. For example, this code:

QuickFormat format = new QuickFormat(
  "<tr><td> _ </td><td> _ </td><td> _ </td></tr>\n"); 
format.nfmt(0,2).arg(1.2).arg("2.4").npic("( N)").arg
  (-4.8).print(System.out);

produces:

<tr><td> 1.20 </td><td> 2.4 </td><td> ( 4.80) </td></tr>

Writing code to produce formatted output using the four classes separately can require a lot of typing. The QuickFormat class is a simply wrapper for these classes that provides a more terse output syntax:

QuickFormat format = 
  new QuickFormat("| ________ | ________ | ________ |").pre(2);
if(d < 0)
  format.arg("").arg(-d).npic("(N)").arg(balance).println(System.out);
else
  format.arg(d).arg("").npic("(N)").arg(balance).println(System.out);

The QuickFormat class interface is a mixture of C and C++ output styles. TextPicture provides the intuitive readability of printf, while the chaining of methods is reminiscent of C++'s overloaded shift operator. Each method returns a QuickFormat object on which the subsequent method is invoked.

A QuickFormat object is usually created using a TextPicture picture string; the specifics of formatting and the substitution of values is then done with method calls.

There are a number of arg methods that correspond to those in the TextPicture class, with the exception that numeric values are formatted according to a NumericPicture object kept internally in QuickFormat objects. A NumericFormat object is also held by QuickFormat for determining the width and precision of numeric arguments.

The npic(NumericPicture nl) method can be used to substitute a new NumericPicture object for the one in use. The nfmt(int width, int precision) method changes the width and precision of the current NumericFormat in use, while pre(int precision) changes only the precision.

Note that to make use of the most advanced features of NumericFormat, you have to create your own NumericFormat object separate from QuickFormat and use the NumericFormat.format(n) method to obtain a string. That string can then be used with the QuickFormat.arg(String) method.

The following program, QuickFormatExample2.java, prints another bank statement, this one based on the QuickFormat class.

NOTE: Complete code for this example is located in the examples directory created for your installation of Tools.h++ Professional. The "Examples" chapter in Part V, "Resources," describes the location of that directory, or you can check the online build guide for your installation media.

import java.io.PrintStream;
import com.roguewave.format.QuickFormat;

public class QuickFormatExample2
{
  /**
   * Print a series of credits/debits in a bankbook style table.
   */
  public static void print(PrintStream out, double[] transactions )
    {
    String hline =   "----------------------------------";
    String headers = "| Credits  |  Debits  | Balance  |";
    String row =     "| ________ | ________ | ________ |";

    /*
     * Create a new QuickFormat object with precision set to 2.
     */
    QuickFormat fmt = new QuickFormat(row).pre(2);
    out.println(hline);
    out.println(headers);
    out.println(hline);

    double balance = 0;
    for(int i = 0; i < transactions.length; i++)
 {
  double d = transactions[i];
  balance += transactions[i];
  if(d < 0)
    fmt.arg("").arg(-d).npic("(N)").arg(balance).println(out);
  else
    fmt.arg(d).arg("").npic("(N)").arg(balance).println(out);
}
    System.out.println(hline);
 }

  public static void main(String args[])
    {
    double[] transactions = new double[6];
     transactions[0] = 50.00;
     transactions[1] = -4.95;
     transactions[2] = -49.99;
     transactions[3] = -8.50;
     transactions[4] = 50.00;
     transactions[5] = -37.50;

     print(System.out, transactions );
    }
}

Note that the NumericPicture has been modified to use parentheses for negative balances, giving as output:

----------------------------------
| Credits  |  Debits  | Balance  |
----------------------------------
|    50.00 |          |   50.00  |
|          |     4.95 |   45.05  |
|          |    49.99 |   (4.94) |
|          |     8.50 |  (13.44) |
|    50.00 |          |   36.56  |
|          |    37.50 |   (0.94) |
----------------------------------