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).

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.

---

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.