Title: A Text Formatting Class

I note that the Draft C++ Standard will provide a Standard Library which I presume will include the existing iostream classes. I do not know whether additional text formatting classes have been added but, just in case they have not, I have outlined the features of a class I have developed from ostream and its related classes.

The class, which I have called Formatter, provides for a formatting string to specify how a sequence of object values is to be formatting as text. It is based on a similar facility which I developed in Ada 83 and presented at the Ada UK 93 Conference. The implementation in C++ is much simpler (~250 lines of C++) thanks to the support already provided by the ostream class hierarchy.

The class interprets a formatting string based on the conventions used by printf() in C, but applies them in a totally type-safe way, as described below.

Whilst the class provides little functionality that is not already supported by ostream it allows this functionality to be much more concisely, conveniently and obviously utilised (tabulated output is easy!). I know that most people, familiar with printf() in C, hanker after a similarly powerful and concise formatting notation for use in C++.

Well here it is!

The class has been compiled and used with CenterLine C++ on a Sparc. It no doubt could be refined and I believe a comparable class could be developed for reading formatted input.

The significant features of the Formatter class are shown in the abbreviated class declaration that follows:

// -------- Formatter class declaration -----------
#include <iostream.h>
#include <strstream.h>

class Formatter {
  ostream& dest;
// other private data members
  Formatter () : dest(cout) {};
  Formatter (const Formatter&) :dest(cout) {};
  Formatter (ostream & os, char *form);
  ~Formatter ();
  void * operator new (size_t) {return NULL;};
  void operator delete (void*, size_t) {};
// other private methods
public:
friend Formatter operator % (ostream& os, char *form); // convert an ostream into a Formatter
  Formatter& operator % (char *defaults) ; // change the default formats
  Formatter& operator << (ostrstream *); // format the text from a memory buffer
  Formatter& operator << (int); // convert basic data values
  Formatter& operator << (int *); // into formatted text
  Formatter& operator << (float);
  Formatter& operator << (char);
  Formatter& operator << (char *);
// other member functions that correspond to ostream::operator <<() member functions

  // manipulators that convert a Formatter object back into the ostream object
  // from which it was constructed
friend ostream& endf (Formatter&); // output to end of formatting string
friend ostream& stopf (Formatter&); // stop use of formatting string
friend ostream& endl (Formatter&); // as endf + output of newline
friend ostream& stopl (Formatter&); // as stopf + output of newline
  ostream& operator << (ostream& (*f) (Formatter&)) {return (*f)(*this);}
static char one_space[2];
};

#define SP Formatter::one_space // default formatting string of a single space separator

// --end of Formatter class declaration --------------------------

Each '%' character in the formatting string acts as a placeholder in the generated text for the value which will replace it (unless immediately followed by another '%' when it represents itself). The characters following a '%' character constitute a formatting control pattern which determines how the value will be translated and formatted. A format control pattern is always terminated by a character which determines the mode of translation that is to be applied to a value, as defined below.

When the translation mode character does not correspond to the type of the value to be translated the default translation is applied to the value.

The user can control the layout of the generated text by specifying:

These layout controls must appear between the '%' character and the translation mode character in the format: '%WJPFs' where 's' in one of the above translation mode characters. The allowable representation for WPJF is summarised below:

The default values of W, J, P and F may be changed on a per-object basis by the application of the "Formatter& Formatter::operator % (char *defaults)" operation.

In this context the parameter "defaults" is a formatting string where each format control pattern is interpreted as setting the defaults for the type of value specified by its translation mode character; any other characters are ignored.

Alternatively, %W may be followed by a substring enclosed by '{' and '}'. to specify that the substring is to be interpreted W times. For example, the format string:

"abc%s %4{xy%16ez} %x" 

is equivalent to:

"abc%s xy%16ezxy%16ezxy%16ezxy%16ez %x"

Given the object declarations:

int i = 123;
float f = 4567.89;
char s[] = "Format this";

and the following format strings:

static char ft1[] = "Formatted: %d %s %f %U <<\n";
static char ft2[] = "%s||";
static char ft3[] = "%15_,s";

the following C++ expression will produce the text shown to their right:

cout % ft1 << i << i << f << s << endf;  Formatted: 123 123 4567.890137 FORMAT THIS? <<
cout % ft1 << i << f << s << i << endf;  Formatted: 123 4567.89 Format this? 123 <<
cout % ft2 << s << f << i << endl;       Format this||4567.89||123||
cout % ft2 << s << f << i << stopl;      Format this||4567.89||123
cout % SP << f << i << s;                4567.89 123 Format this
cout % ft3 << f << i << s;               ,,,,,,,,4567.89,,,,,,,,,,,,123,,,,Format this

The C++ code:

Formatter& fmt = cout % "Prefix: %2{%7s: }Suffix: %5s:\n";
int i = 123;
for (int j = 0; j < 100; j += 10 ) fmt << i+j;
for (int k = 100; k < 2000; k += 200 ) fmt << i+k;

will produce:

Prefix: 123: 133: Suffix: 143:
Prefix: 153: 163: Suffix: 173:
Prefix: 183: 193: Suffix: 203:
Prefix: 213: 223: Suffix: 423:
Prefix: 623: 823: Suffix: 1023:
Prefix: 1223: 1423: Suffix: 1623:
Prefix: 1823: 2023