This is the first of several headers I intend to present, in my implementation of the Standard C++ library, that define templates. Until recently, it was also arguably the trickiest use of templates in the Standard C++ library. (The Standard Template Library beats it cold, however.) I begin, therefore, by sketching the history that led to the templates in <iomanip). I also include here a general discussion of templates, current template technology, and how I have chosen to implement templates used by the Standard C++ library.

   cout << endl;

For all their power, however, these inserters share a common limitation. You have no way to convey any additional, variable information. The name of the function says what it does, but that's also all it says. The limitation is intrinsic in the operator notation:

ostream& operator<<(ostream& os, X x);

Or is there? Remember, X can be an arbitrary class. You can construct a class that stores both a function pointer and an extra argument, as in:

class X {
public:
   X(ostream& (*pf_arg)(ostream&, T),
     T val_arg)
      : pf(pf_arg), val(val_arg) {}
   friend ostream& operator<<
      (ostream&, X);
private:
   ostream& (*pf)(ostream&&, T);
   T val;
   };

ostream& operator<<(ostream& os,
                 X x)
   {        // assemble function
          // call and do it
   return ((*x.pf)(os, x.val));
   }

To use this machinery, you have to supply a pair of functions:

• the visible function, taking a single argument of type T, that you call to obtain the right operand of an insertion operator
• the hidden function, taking two arguments, that does the actual work

ostream& insert_hex(ostream& os, int val)
   {                // insert a hex integer
   ios::fmtflags old = os.setf(ios::hex, ios::basefield);
   os << val;
   os.setf(old, ios::basefield);
   return (os);
   }

X hex(int val)
   {                // save info to call insert_hex(val)
   return (X(&insert_hex, val));
   }

   cout << "mask is "<< hex(mask) << endl;

Neat, huh? Even neater is the fact that you can define manipulators that work just with inserters, as above, or just with extractors, or with both. In the last case, you probably want the left operand to be an object of the base class ios. A subobject of class ios captures what is common to objects of class ostream (the subject of inserters) and of class istream (the subject of extractors). You have lots of choices.

The problem is, you have too many choices. And you have too much tedious work to do for each choice you make. It's nuisance enough to have to write a pair of functions for each manipulator, but that's the most visible, problem-specific part. Just to prepare for writing this pair of functions, you need to define a class and overload one or two operators on that class. And you have to define a different class for each argument type you wish to pass, and for each object you wish to operate on (ios, istream, or ostream).

The modern approach in C++ is to define templates instead. A template class defines an open-ended set of classes with one or more parameters. Typically, a parameter specifies a type, which you write as class T, regardless of whether or not T is truly a class. That's the special power of templates that removes one more excuse to write messy macros. A parameter can also supply a value, however, such as the number of bits in a set (as with the library class bits<N>, to be described later).

The class X I defined earlier, for example, converts easily to a template class. All you need to do is add a prefix to the class definition:

template<class T> class X {
public:
   X(ostream& (*pf_arg)(ostream&, T), T val_arg)
      : pf(pf_arg), val(val_arg) {}
   friend ostream& operator<<(ostream&, X);
private:
   ostream& (*pf)(ostream&, T);
   T val;
   }

The point is, you can instantiate as many flavors of a given template class as your heart desires. The translator supplies whatever executable code that's necessary, on demand. If it can find clever ways to recycle existing code, so much the better for space efficiency. But in any event, you benefit from the coding convenience of writing something once and using it multiple times. And unlike macros, the translator can better check the sanity of template classes, both when they're defined and when they're instantiated.

You can also write template functions. Template parameters can supply types for the parameters of the function, as in:

template<class T> ostream& insert_hex(ostream& os, T val)
   {                 // insert a hex integer of type T
   ios:: fmtflags old = os. setf(ios::hex, ios::basefield);
   os << val;
   os.setf(old, ios::basefield);
   return (os);
   }

That's handy, but the machinery doesn't stop there. You can even write insert_hex(cout, (long)mask), or any call whose second argument is implicitly of type long, and the translator will instantiate the flavor insert_hex<long> for you(!) No need to spell out in advance the instantiations you expect to need. Just write the function call and leave it to the translator to guess which instantiation works best.

You can even count on a limited amount of argument type conversion, and back fitting, as part of the matching process. Here, for example, is the template function that accompanies our template class:

template<class T> ostream& operator<<(ostream& os, X<T> x)
   {                // assemble function call and do it
   return ((*x.pf)(os, x.val));
   }

• Every template function parameter must affect the type of one or more function parameters in some way, however else it is used in the function definition.
• Value parameters cannot be used as template function parameters, since they seldom can influence overload resolution.

Templates have other limitations as well, at least for now. Current implementations have fundamental differences in how they manage template definitions. You can, in principle, write a template class like any other. You define the template class itself in a header, but keep the member function definitions in a separate source file or files. In practice, however, not all implementations deal with this approach well, if at all. And some implementations have limited capacity for dealing with complex template definitions.

Writing inline definitions for template functions of all flavors seems to work most reliably in current implementations. Of course, you run risks in doing so, at least with certain compilers. A nontrivial inline function definition may still expand to inline code, so the compiler generates an excess of code. Other compilers choose not to inline code that contains loops, such as for or while statements. (The cfront preprocessor won't even translate such code. It favors a different template style.) Whether or not that is a good decision, the compilers still see fit to complain repeatedly about such code. I have had reasonable programs fail to compile simply because the compiler decided it had emitted too many (gratuitous) diagnostics.

The style I chose for this implementation is to write only inline definitions for all template functions. I try to keep them small, for a host of reasons. Occasionally, I offload some work to secret functions that are shared across template instantiations. But the basic risks of this approach remain, as I outlined above. Still, I find this approach best for the sake of portability and clear presentation today. You may need to alter the representation of some templates presented here, if for no other reason than to improve translation speed, execution speed, or generated code size.

• to use one or more of the predefined manipulators that take an argument
• to define one or more additional manipulators that take an argument

• resetiosflags(fmtflags), clears the specified format flags
• setiosflags(fmtflags), sets the specified format flags
• setbase(int), sets the basefield format flags to match the specified numeric base
• setfill(int), alters the fill character
• setprecision(int), alters the floating-point precision
• setw(int), alters the field width