no copyright!iostream-manipulator.html.3

IOStream manipulators

Synopsis

#include <ios>

namespace std {
  ios_base& uppercase(ios_base& stream);
  ios_base& nouppercase(ios_base& stream);

  ios_base& showbase(ios_base& stream);
  ios_base& noshowbase(ios_base& stream);

  ios_base& showpoint(ios_base& stream);
  ios_base& noshowpoint(ios_base& stream);

  ios_base& showpos(ios_base& stream);
  ios_base& noshowpos(ios_base& stream);

  ios_base& skipws(ios_base& stream);
  ios_base& noskipws(ios_base& stream);

  ios_base& uppercase(ios_base& stream);
  ios_base& nouppercase(ios_base& stream);

  // changing in the alignment of formatted output
  ios_base& internal(ios_base& stream);
  ios_base& left(ios_base& stream);
  ios_base& right(ios_base& stream);

  // changing the base for integer formatting
  ios_base& dec(ios_base& stream);
  ios_base& hex(ios_base& stream);
  ios_base& oct(ios_base& stream);

  // changing the the formatting of floating points:
  ios_base& fixed(ios_base& stream);
  ios_base& scientific(ios_base& stream);
}
  

Description

For convenient modification of the formatting parameters, a lot of so-called "manipulators" are defined. A manipulator can be used as if it is an object which is written to or read from a stream but instead of writing or reading anything, they just change the format flags or perform a specific operation on the stream. For example, the follwing code can be used to write the integer i in octal, decimal, and hexadecimal format:
  std::cout << std::oct << i << " "
	    << std::dec << i << " "
	    << std::hex << i << std::endl;
    
Switching the used base is accomplished with the three manipulators std::oct, std::dec, and std::hex. After writing the integer using three different bases, the line is terminated and the buffer of std::cout is flushed using the manipulator std::endl.

All manipulators which do not take an additional argument, are implemented as functions getting a reference to a stream object as argument and also returning a reference to such a stream object, namely the argument. The exact type of the stream object is the most general type for which this operation is possible, even if it is not really useful. For example, you can change the flags determining how floating point values are written using an input stream because these flags are maintained in the base class ios_base, although this will not change the behavior at all. For the stream classes are the corresponding input or output operators overloaded to take such functions as arguments. These operators do nothing else than calling the function with the argument. Here are the implementations of a sample manipulator and the corresponding output operators:
  namespace std {
    ios_base&
    uppercase(ios_base& ib) {
      ib.setf(ios_base::uppercase);
      return ib;
    }

    template <typename charT, typename traits>
    basic_ostream<charT, traits>&
    basic_ostream<charT, traits>::operator<< (ios_base& (*manipulator)(ios_base&)) {
      manipulator(*this);
      return *this;
    }
  }
    
The implementation of the manipulator is extremely simple: It just calls the method which changes the corresponding flags, in this case ios_base::setf(), with the proper argument and returns the argument ib. The implementation of the output operator is also quite simple: It just calls the function it gets as argument with itself as argument ( basic_ostream is indirectly derived from ios_base) and returns itself for chaining of output operators. Put together, this gives some neat syntactic sugar.

Manipulator Overview

Name Reverse/
Group
Semantic Stream Type
uppercase nouppercase Turn on/off use of textual representation of Boolean values. ios_base
showbase noshowbase Turn on/off generation of a base indication for integer output. ios_base
showpoint noshowpoint Turn on/off generation of a decimal point, even if it is necessary, for floating point output. ios_base
showpos noshowpos Turn on/off generation of a positive sign for numeric output. ios_base
skipws noskipws Turn on/off skipping of whitespace for formatted input. ios_base
uppercase nouppercase Turn on/off use of uppercase letters for formatted output. ios_base
internal adjustfield Setup filling at an internal position for formatted output. ios_base
left adjustfield Setup left adjusting formatted output (fill characters are inserted right from value). ios_base
right adjustfield Setup right adjusting formatted output (fill characters are inserted left from value). ios_base
dec basefield Setup use of the decimal base for formatted input and output. ios_base
hex basefield Setup use of the hexadecimal base for formatted input and output. ios_base
oct basefield Setup use of the octal base for formatted input and output. ios_base
fixed floatfield Setup use of fixed point notation for formatted floating point output. ios_base
scientific floatfield Setup use of scientific notation for formatted floating point output (i.e. use of mantissa and exponent). ios_base

Details

The description of the manipulators will be quite brief, mainly because the meaning of the formatting flags is described elsewhere in great detail.

ios_base& boolalpha(ios_base& ib)

Effect
The flag ios_base::boolalpha is set: ib.setf(ios_base::boolalpha).
Post Condition
(ib.flags() & ios_base::boolalpha) != 0
Return
The function returns ib.

ios_base& noboolalpha(ios_base& ib)

Effect
The flag ios_base::boolalpha is cleared: ib.unsetf(ios_base::boolalpha).
Post Condition
(ib.flags() & ios_base::boolalpha) == 0
Return
The function returns ib.

ios_base& showbase(ios_base& ib)

Effect
The flag ios_base::showbase is set: ib.setf(ios_base::showbase).
Post Condition
(ib.flags() & ios_base::showbase) != 0
Return
The function returns ib.

ios_base& noshowbase(ios_base& ib)

Effect
The flag ios_base::showbase is cleared: ib.unsetf(ios_base::showbase).
Post Condition
(ib.flags() & ios_base::showbase) == 0
Return
The function returns ib.

ios_base& showpoint(ios_base& ib)

Effect
The flag ios_base::showpoint is set: ib.setf(ios_base::showpoint).
Post Condition
(ib.flags() & ios_base::showpoint) != 0
Return
The function returns ib.

ios_base& noshowpoint(ios_base& ib)

Effect
The flag ios_base::showpoint is cleared: ib.unsetf(ios_base::showpoint).
Post Condition
(ib.flags() & ios_base::showpoint) == 0
Return
The function returns ib.

ios_base& showpos(ios_base& ib)

Effect
The flag ios_base::showpos is set: ib.setf(ios_base::showpos).
Post Condition
(ib.flags() & ios_base::showpos) != 0
Return
The function returns ib.

ios_base& noshowpos(ios_base& ib)

Effect
The flag ios_base::showpos is cleared: ib.unsetf(ios_base::showpos).
Post Condition
(ib.flags() & ios_base::showpos) == 0
Return
The function returns ib.

ios_base& skipws(ios_base& ib)

Effect
The flag ios_base::skipws is set: ib.setf(ios_base::skipws).
Post Condition
(ib.flags() & ios_base::skipws) != 0
Return
The function returns ib.

ios_base& noskipws(ios_base& ib)

Effect
The flag ios_base::skipws is cleared: ib.unsetf(ios_base::skipws).
Post Condition
(ib.flags() & ios_base::skipws) == 0
Return
The function returns ib.

ios_base& uppercase(ios_base& ib)

Effect
The flag ios_base::uppercase is set: ib.setf(ios_base::uppercase).
Post Condition
(ib.flags() & ios_base::uppercase) != 0
Return
The function returns ib.

ios_base& nouppercase(ios_base& ib)

Effect
The flag ios_base::uppercase is cleared: ib.unsetf(ios_base::uppercase).
Post Condition
(ib.flags() & ios_base::uppercase) == 0
Return
The function returns ib.

ios_base& unitbuf(ios_base& ib)

Effect
The flag ios_base::unitbuf is set: ib.setf(ios_base::unitbuf).
Post Condition
(ib.flags() & ios_base::unitbuf) != 0
Return
The function returns ib.

ios_base& nounitbuf(ios_base& ib)

Effect
The flag ios_base::unitbuf is cleared: ib.unsetf(ios_base::unitbuf).
Post Condition
(ib.flags() & ios_base::unitbuf) == 0
Return
The function returns ib.

ios_base& internal(ios_base& ib)

Effect
The flags ios_base::internal is set and all other flags in the ios_base::adjustfield are cleared: ib.setf(ios_base::internal, ios_base::adjustfield).
Post Condition
(ib.flags() & ios_base::adjustfield) == ios_base::internal
Return
The function returns ib.

ios_base& left(ios_base& ib)

Effect
The flags ios_base::left is set and all other flags in the ios_base::adjustfield are cleared: ib.setf(ios_base::left, ios_base::adjustfield).
Post Condition
(ib.flags() & ios_base::adjustfield) == ios_base::left
Return
The function returns ib.

ios_base& right(ios_base& ib)

Effect
The flags ios_base::right is set and all other flags in the ios_base::adjustfield are cleared: ib.setf(ios_base::right, ios_base::adjustfield).
Post Condition
(ib.flags() & ios_base::adjustfield) == ios_base::right
Return
The function returns ib.

ios_base& dec(ios_base& ib)

Effect
The flags ios_base::dec is set and all other flags in the ios_base::basefield are cleared: ib.setf(ios_base::dec, ios_base::basefield).
Post Condition
(ib.flags() & ios_base::basefield) == ios_base::dec
Return
The function returns ib.

ios_base& hex(ios_base& ib)

Effect
The flags ios_base::hex is set and all other flags in the ios_base::basefield are cleared: ib.setf(ios_base::hex, ios_base::basefield).
Post Condition
(ib.flags() & ios_base::basefield) == ios_base::hex
Return
The function returns ib.

ios_base& oct(ios_base& ib)

Effect
The flags ios_base::oct is set and all other flags in the ios_base::basefield are cleared: ib.setf(ios_base::oct, ios_base::basefield).
Post Condition
(ib.flags() & ios_base::basefield) == ios_base::oct
Return
The function returns ib.

ios_base& fixed(ios_base& ib)

Effect
The flags ios_base::fixed is set and all other flags in the ios_base::floatfield are cleared: ib.setf(ios_base::fixed, ios_base::floatfield).
Post Condition
(ib.flags() & ios_base::floatfield) == ios_base::fixed
Return
The function returns ib.

ios_base& scientific(ios_base& ib)

Effect
The flags ios_base::scientific is set and all other flags in the ios_base::floatfield are cleared: ib.setf(ios_base::scientific, ios_base::floatfield).
Post Condition
(ib.flags() & ios_base::floatfield) == ios_base::scientific
Return
The function returns ib.

See Also

ios_base(3), basic_ostream(3)
Copyright © 1999 Dietmar Kühl, Claas Solutions (dietmar.kuehl@claas-solutions.de)