9.5 Manipulators

A manipulator is a function object that can be used as an operand to an input or output operator to manipulate the stream. Manipulators can send additional output to a stream, read input from a stream, set flags, and more. For example, to output a zero-padded, hexadecimal integer, you can use an ostream's member functions or manipulators, whichever you prefer. Example 9-7 shows both ways.

Example 9-7. Manipulating an output stream to format a number

using namespace std;

// Output a value using ostream's member functions.
cout.fill('0');
cout.width(8);
cout.setf(ios_base::internal, ios_base::adjustfield);
cout.setf(ios_base::hex, ios_base::basefield);
cout << value;

// Output the same value using manipulators.
cout << setfill('0') << setw(8) << hex << internal << value;

9.5.1 Standard Manipulators

The standard library defines several manipulators for setting formatting flags, setting other formatting parameters, skipping whitespace, flushing output, and more. The following is a list of all the standard manipulators, grouped by header:

<ios>

Declares the manipulators that set the formatting flags: boolalpha, dec, fixed, hex, internal, left, noboolalpha, noshowbase, noshowpoint, noshowpos, noskipws, nouppercase, nounitbuf, oct, right, scientific, showbase, showpoint, showpos, skipws, uppercase, and unitbuf

<istream>

Declares the input manipulator: ws

<ostream>

Declares the output manipulators: endl, ends, and flush

<iomanip>

Declares several additional manipulators: resetioflags, setioflags, setbase, setfill, setprecision, and setw

Most manipulators are declared in the same header as the stream type they manipulate. The only time you need to #include an additional header is when you use a manipulator that takes an argument. These manipulators are in the <iomanip> header.

9.5.2 Custom Manipulators

To write your own manipulator, use the standard manipulators as patterns. The easiest to use are manipulators that take no arguments. A manipulator is simply a function that takes a stream as an argument and returns the same stream. The standard streams overload operator<< and operator>> to take a pointer to such a function as an operand.

Suppose you want to write an input manipulator that skips all characters up to and including a newline. (Perhaps this manipulator is used by a command processor after reading a // comment sequence.) Example 9-8 shows one way to write the skipline manipulator.

Example 9-8. Skipping a line in an input stream

template<typename charT, typename traits>
std::basic_istream<charT,traits>&
skipline(std::basic_istream<charT,traits>& in)
{
  charT c;
  while (in.get(c) && c != '\n')
    ;
  return in;
}
...
int x;
std::string next;
std::cin >> x >> skipline >> next;

Manipulators that take arguments are harder to write, but only slightly. You need to write some supporting infrastructure, such as additional overloaded operator>> or operator<< functions.

For example, suppose you want to parameterize your input skipline manipulator so it skips everything up to a caller-supplied character. This manipulator is defined as a class template, in which the constructor takes the manipulator's argument, that is, the delimiter character. You must overload operator>> so it recognizes your manipulator as an operand and invokes the manipulator's operator( ). You don't need to use operator( ), but this is a good choice when building a reusable infrastructure for manipulators. Example 9-9 shows the new skip manipulator.

Example 9-9. Writing a manipulator that takes an argument

template<typename charT>
class skipper
{
public:
  typedef charT char_type;
  skipper(char_type delim) : delim_(delim) {}
  template<typename traits>
  void operator(  )(std::basic_istream<charT,traits>&) const;
private:
  char_type delim_;
};

// Skip the rest of the line. The compiler deduces the traits type from the
// stream argument.
template<typename charT>
template<typename traits>
void skipper<charT>::operator(  )(std::basic_istream<charT,traits>& stream)
const
{
  char_type c;
  while (stream.get(c) && c != delim_)
    ;
}

// Invoke the skipper manipulator.
template<typename charT, typename traits>
std::basic_istream<charT,traits>& 
           const skipper<charT>& f)
{
  f(stream);
  return stream;
}

// Let the compiler deduce the character type.
template<typename charT>
skipper<charT> skip(charT c)
{
  return skipper<charT>(c);
}
...
int x;
std::string next;
std::cin >> x >> skip('\n') >> next;