Xavax C++ Library Class Index   FAQ   Overview

Class xavax::Format

Format parses a format string into a compiled format consisting of a list of format nodes, each representing a string literal or a format specification. A compiled format can be used by the Formatter classes to format output in a manner similar to the printf function in the standard C library. Using a compiled format in a loop or code fragment which is called repeatedly is much more efficient than using a format string since the Formatter classes only parse the format string once.

The format string contains three types of objects: plain characters and escape sequences, which are converted to string literals, and format specifications, which specify the type and formatting of a value from a parameter list. Escape sequences are in backslash notation as defined in X3.159-1989 (ANSI C). The escape sequences and their meanings are described in the following table.

Escape
Sequence		 Description
\\ output a backslash character
\' output a single quote character
\a output a bell character
\b output a backspace character
\e output an escape character
\f output a form feed character
\n output a new line character
\r output a carriage return character
\t output a tab character
\v output a vertical tab character
\num output a character whose ASCII value is the 1-, 2-, or 3-digit octal number num

Each format specification begins with a % character. The remainder of the specification consists of zero or more of the following flags in the following order.

Flag Description
- A minus sign specifies left adjustment of the output for this field.
+ A plus sign specifies that there should always be a sign character placed before the number when using signed formats.
space A space specifies that a blank should be left before a positive number for a signed field. A '+' overrides a space if both are used.
0 A zero specifies that zero-padding should be used rather than space-padding. A '-' overrides a zero if both are used.
param An optional digit string specifying a parameter number followed by a '$' character.
width An optional digit string specifying a field width. If the output string has fewer characters than the field width it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width.
precision An optional period followed by an optional digit string which specifies the number of digits to be output after the decimal point, for floating point fields, or the maximum number of characters to be output for a string field. If the digit string is omitted, the precision defaults to zero.
format One of the characters [%bdefgosuxEG] which specifies the type of format to use.

The format characters have the following meaning.

Format Description
% Output a '%' character.
b Output a boolean value as "true" or "false".
d Output an integer as a decimal number.
e Output a double precision floating point parameter in the style [-]d.ddde+dd where there is one digit before the decimal point and the number of digits after the decimal point is equal to the precision specification. When the precision specification is missing, 6 digits are produced. With the E format, an upper-case E is used for the exponent.
E
f Output a double precision floating point parameter in the style [-]ddd.ddd where the number of digits after the decimal point is equal to the precision specification.
g Output a double precision floating point parameter in the format style f or e (E), whichever gives full precision in minimum space.
G
o Output an unsigned integer as an octal number.
s Output a string.
u Output an unsigned integer as a decimal number.
x Output an unsigned integer as a hexadecimal number.

Constructor Summary
Format()
         Construct an empty Format object.
Format(const char* s)
         Construct a Format object with an initial format.

Method Summary
void parse(const char* s)
         Parse the format string s and save the results as a precompiled format.

Related Classes
CStringFormatter, Formatter, StreamFormatter, StringFormatter.

Constructor Detail

Format

Format()
Construct an empty Format object. The parse method may be used later to compile a format.

Format

Format(const char* s)
Construct a Format object with an initial compiled format created by parsing the format string s.
Parameters:
s - the format string.

Method Detail

parse

void parse(const char* s)
Parse the format string s producing a compiled format consisting of format nodes, each represending a string literal or format specification contained in the format string. Any previous compiled format is deleted.
Parameters:
s - the format string.

Example Code

The following examples demonstrates using a compiled format in conjunction with the CStringFormatter class. 

#include Headers_h
#include Cx_Headers_h
#include Cx_Format_h
#include Cx_CStringFormatter_h
#include 

int main(int argc, char **argv)
{
  const char* fstring =
    "bool    b = %b;\\n"
    "int     i = %d;\\n"
    "uint   ui = %u;\\n"
    "uint   ui = %x;\\n"
    "double  d = %f;\\n"
    "char*   s = \"%s\";\\n";
  bool b = true;
  int i = 1234;
  unsigned int ui = 32767;
  double d = 1.2345;
  const char* s = "Hello World";
  const int bufSize = 512;
  char buffer[512];

  CStringFormatter cstf(buffer, sizeof(buffer));
  Format format(fstring);
  cstf.print(format, b, i, ui, ui, d, s);
  cout << "result: " << endl << buffer;
  return 0;
}

This example produces the following output. 

bool    b = true;
int     i = 1234;
uint   ui = 32767;
uint   ui = 7FFF;
double  d = 1.234500;
char*   s = "Hello World";

Copyright © 2003,2005 Xavax Inc. -- All Rights Reserved