Apache C++ Standard Library User's Guide

## 33.2 Manipulators without Parameters

Manipulators that do not have any parameters, like `endl`, are the simplest form of manipulator. The manipulator type `manipT` is a function pointer type, the manipulator `Manip` is the function pointer, and the associated function `f` `manipT``()` is the function pointed to.

In iostreams, the following function pointer types serve as manipulators:

    (1) std::ios_base&        (*)(std::ios_base&)
    (2) std::basic_ios<>&     (*)(std::basic_ios<>&)
    (3) std::basic_istream<>& (*)(std::basic_istream<>&)
    (4) std::basic_ostream<>& (*)(std::basic_ostream<>&)

The signature of a manipulator function is not limited to the examples above. If you have created your own stream types, you will certainly want to use additional signatures as manipulators.

For the four manipulator types listed above, the stream classes already offer the required overloaded inserters and member functions. For input streams, extractors take the following form:

    template<class charT, class traits>
    std::basic_istream<charT, traits>&
    std::basic_istream<charT, traits>::operator>>
    (input_stream_type& (*pf)(input_stream_type&) )
    {  return (*pf)(*this); }

where the type of the argument `pf` is one of types (1) -- (3).

Similarly, for output streams we have:

    template<class charT, class traits>
    std::basic_ostream<charT, traits>&
    std::basic_ostream<charT, traits>::operator<<
    (output_stream_type& (*pf)(output_stream_type&))
    {  return (*pf)(*this);  }

where the type of the argument `pf` is one of the types (1), (2), or (4).

### 33.2.1 Examples of Manipulators without Parameters

Let's look at the manipulator `endl` as an example of a manipulator without parameters. The manipulator `endl`, which can be applied solely to output streams, is a pointer to the following function of type (4):

    template<class charT, class traits>
    std::basic_ostream<charT, traits>&
    std::endl(std::basic_ostream<charT, traits>& os)
    {
      return os.put(os.widen('\n')).flush();
    }

Hence an expression like:

    std::cout << std::endl;

results in a call to the inserter:

    std::ostream& std::ostream::operator<<(std::ostream&
       (*pf)(std::ostream&))

with`std::endl` as the actual argument for `pf`. In other words, `std::cout << std::endl;` is equivalent to `std::cout.operator<<(std::endl)`. That is, inserting `endl` into a stream is really inserting the address of the template specialization `std::endl<char, std::char_traits<char> >` into the stream object `std::cout`. Inserting `endl` into the standard wide character stream object `std::wcout` inserts the address of the specialization of the same template on `wchar_t`, or `std::endl<wchar_t, std::char_traits<wchar_t> >`. Thanks to template argument deduction one need not bother to specify the actual template arguments.

Here is another manipulator, `std::boolalpha`, that can be applied to input and output streams. The manipulator `boolalpha` is a pointer to a function of type (1), since all it needs to access is the state encapsulated in the `ios_base` part of the stream object:

    std::ios_base& boolalpha(std::ios_base& strm)
    {
      strm.setf(std::ios_base::boolalpha);

      return strm;
    }

> NOTE -- Every function that takes a reference to an `ios_base`, a `basic_ios`, a `basic_ostream`, or a `basic_istream`, and returns a reference to the same stream, can be used as a parameter-less manipulator.

### 33.2.2 A Remark on the Manipulator endl

The manipulator`std::endl` is often used for inserting the end-of-line character into a stream. However, `endl` does additionally flush the output stream, as you can see from the implementation of `endl` shown above. Flushing a stream, a relatively time-consuming operation that decreases performance, is unnecessary in most common situations. In the standard example:

    std::cout << "Hello world" << std::endl;

flushing is not necessary because the standard output stream `cout` is flushed automatically during program termination. Since no flush is required, the intent is probably to insert the end-of-line character. If you consider typing `'\n'` more trouble than typing `endl`, you can easily add a simple manipulator `nl` that inserts the end-of-line character, but refrains from flushing the stream.