• Next chapter
• Previous chapter
• Table of contents

Chapter 12: The IO-stream Library

We're always interested in getting feedback. E-mail us if you like this guide, if you think that important material is omitted, if you encounter errors in the code examples or in the documentation, if you find any typos, or generally just if you feel like e-mailing. Send your email to Frank Brokken.

Please state the document version you're referring to, as found in the title (in this document: 4.4.2).

As an extension to the standard stream (FILE) approach well known from the C programming language, C++ offers an I/O library based on class concepts.

Earlier (in chapter 3) we've already seen examples of the use of the C++ I/O library. In this chapter we'll cover the library to a larger extent.

Apart from defining the insertion (<<) and extraction(>>) operators, the use of the C++ I/O library offers the additional advantage of type safety in all kinds of standard situations. Objects (or plain values) are inserted into the iostreams. Compare this to the situation commonly encountered in C where the fprintf() function is used to indicate by a format string what kind of value to expect where. Compared to this latter situation C++'s iostream approach uses the objects where their values should appear, as in

The compiler notices the type of the nMaidens variable, inserting its proper value at the appropriate place in the sentence inserted into the cout iostream.

Compare this to the situation encountered in C. Although C compilers are getting smarter and smarter over the years, and although a well-designed C compiler may warn you for a mismatch between a format specifier and the type of a variable encountered in the corresponding position of the argument list of a printf() statement, it can't do much more than warn you. The type safety seen in C++ prevents you from making type mismatches, as there are no types to match.

Apart from this, the iostreams offer more or less the same set of possibilities as the standard streams of C: files can be opened, closed, positioned, read, written, etc.. The remainder of this chapter presents an overview.

In general, input is managed by istream objects, having the derived classes ifstream for files, and istrstream for strings (character arrays), whereas output is managed by ostream objects, having the derived classes ofstream for files and ostrstream for strings.

If a file should allow both reading from and writing to, a fstream object (c.q. strstream object) should be used.

Finally, in order to use the iostream facilities, the header file iostream must be included in source files using these facilities. When ifstream, ofstream or fstream objects are to be used, the fstream header file, which in turn includes iostream, must be included. An analogous situation holds true for string streams. Here the header file strstream is required.

12.1: Streams: insertion (<<) and extraction (>>)

12.1.1: The insertion operator <<

As an example, the << operator as defined with the class ostream is an overloaded operator having as prototype, e.g.,

The normal associativity of the <<-operator remains unaltered, so when a statement like

Since the << operator has a lot of (overloaded) variants, many types of variables can be inserted into ostream objects. There is an overloaded <<-operator expecting an int, a double, a pointer, etc. etc.. For every part of the information that is inserted into the stream the operator returns the ostream object into which the information so far was inserted, and the next part of the information to be inserted is devoured.

As we have seen in the discussion of friends, even new classes can contain an overloaded << operator to be used with ostream objects (see sections 14.3 and 14.3.1).

12.1.2: The extraction operator >>

Consider the following code:

    int
        i1,
        i2;
    char
        c;
        
    cin >> i1 >> i2;                // see (1)
    
    while (cin >> c && c != '.')    // see (2)
        process(c);
                             
    char                            // see (3)
        buffer[80];
                                    // see (3)
    while (cin >> buffer)
        process(buffer);

This example shows several characteristics of the extraction operator worth noting. Assume the input consists of the following lines:

    125
    22
    h e l l o 
    w o r l d .
    this example shows
    that we're not yet done 
    with C++

1. In the first part of the example two int values are extracted from the input: these values are assigned, respectively, to i1 and i2. White-space (newlines, spaces, tabs) is skipped, and the values 125 and 22 are assigned to i1 and i2.

   If the assignment fails, e.g., when there are no numbers to be converted, the result of the extraction operator evaluates to a zero result, which can be used for testing purposes, as in:

   if (!(cin >> i1))
2. In the second part, characters are read. However, white space is skipped, so the characters of the words hello and world are produced by cin, but the blanks that appear in between are not.

   Furthermore, the final '.' is not processed, since that one's used as a sentinel: the delimiter to end the while-loop, when the extraction is still successful.

3. In the third part, the argument of the extraction operator is yet another type of variable: when a char * is passed, white-space delimited strings are extracted. So, here the words this, example, shows, that, we're, not, yet, done, with and C++ are returned.

   Then, the end of the information is reached. This has two consequences: First, the while-loop terminates. Second, an empty string is copied into the buffer variable.

12.2: Four standard iostreams

In C++ comparable iostreams are

• cin, an istream object from which information can be extracted. This stream is normally connected to the keyboard.
• cout, an ostream object, into which information can be inserted. This stream is normally connected to the screen.
• cerr, an ostream object, into which information can be inserted. This stream is normally connected to the screen. Insertions into that stream are unbuffered.
• clog, an ostream object, comparable to cerr, but using buffered insertions. Again, this stream is normally connected to the screen.

12.3: Files and Strings in general

String stream objects can be used to read or write objects to streams in memory, allowing the use of, e.g., the insertion and extraction operators on these objects. To use the string stream objects istrstream, ostrstream or strstream the header file strstream must be included. Note that a strstream object is not a string object. A strstream object should be approached like a fstream object, not as a char * object having special characteristics.

12.3.1: String stream objects: a summary

These objects can be created by constructors expecting the address of a block of memory (and its size) as its argument. It is also possible to let the objects to the memory management themselves.

Let's go through some examples. To write something into a block of memory using a ostrstream object, the following code could be used:

    char
        buffer[100];
    ostrstream
        os(buffer, 100);    // construct the ostrstream object

                            // fill 'buffer' with a well-known text
    os << "Hello world " << endl << ends;

    cout << os.str(); // display the string 
        

    char
        buffer[100];
    ostrstream
        os(buffer, 100);    // construct the ostrstream object

    os << "Hello world " << ends;

    os << " More text " << ends;

    cout << os.str() << endl; // this only shows 'Hello world' 
        

    void bytes(ostrstream &str)
    {
        char
            *cp = str.str();
    
        cout << str.pcount() << ": "; 
    
        for (int idx = 0; idx < 10; ++idx)
            cout << setw(3) << static_cast<int>(cp[idx]) << " ";
        cout << endl;
    }
    
    int main()
    {
        char buffer[10];
    
        memset(buffer, 10, 10);
    
        ostrstream
            str(buffer, 100);
        
        bytes(str);
    
        str << "A";
    
        bytes(str);
    
        str << "B" << ends;
    
        bytes(str);
    
        str << "C";
    
        bytes(str);
    
        return (0);
    }
        

    0:  10  10  10  10  10  10  10  10  10  10 
    1:  65  10  10  10  10  10  10  10  10  10 
    3:  65  66   0  10  10  10  10  10  10  10 
    4:  65  66   0  67  10  10  10  10  10  10 
        

Furthermore, note the use of the member function str(), returning the string the ostrstream object operates on. Using str() the existence of buffer can be hidden from the users of the ostrstream object.

When an ostrstream object is created without an external memory buffer (e.g., `ostrstream str;' is defined), the ostrstream object allocates the required memory itself. In that case using the str() member function will result in the freezing of the ostrstream object: it will no longer create room for new characters when additional text is inserted into the object, and, most important, it will not delete allocated memory when the object itself is deleted.

To prevent memory leakage here, the program using the str() member function can take two actions:

• First, as str() returns a char * rather than a char const * the caller of str() may consider the returned string its own. Consequently, the caller of str() is responsible for deleting the string returned by str(). E.g.,

  
      ostrstream
          ostr;
      
      ostr << "Hello world" << ends;
  
      char
          *cp = ostr.gets();  // freezes ostr
  
      cout << cp;             // use ostr's string
      delete cp;              // caller deletes ostr's string
          
  

• Alternatively, the string can be unfrozen, after which insertions are again possible. Now, when the ostrstream object is destroyed the ostrstream's internally stored string is destroyed too. E.g.,

  
      ostrstream
          ostr;
      
      ostr << "Hello world" << ends;
  
      char
          *cp = ostr.gets();  // freezes ostr
  
      cout << cp;             // use ostr's string
  
      ostr.freeze(0);         // ostr will now delete its own string, cp 
                              // should leave the memory it points to alone.
          
  

The following member functions are available for strstream objects:

• istrstream::istrstream(const char *str [, int size]): This constructor creates an input string class istrstream object, associating it with an existing buffer starting at str, of size size. If size is not specified, the buffer is treated as a null-terminated string.
• ostrstream::ostrstream(): This constructor creates a new stream for output to a dynamically managed string, which will grow as needed.
• ostrstream::ostrstream(char *str, int size [, int mode]): This constructor creates a new stream for output to a statically defined string of length size, starting at str. The mode parameter may optionally be specified as one of the iostream modes. By default ios::out is used.
• int ostrstream::pcount(): returns the current length of the string associated with this ostrstream object.
• char *ostrstream::str(): The member function returns a pointer to the string managed by this ostrstream object. This function implies freeze(), see below:
• void ostrstream::freeze ([int n]): If n is nonzero (the default), the string associated with this ostrstream object must not change dynamically anymore. While frozen, it will not be reallocated if it needs more space, and it will not be deallocated when the ostrstream object is destroyed. freeze(1) can be used to refer to the string as a pointer after creating it via ostrstream facilities. freeze(0) can be used to unfreeze (thaw ?) the object again. Following freeze(0) the ostrstream object will delete memory it allocated when the object itself is deleted.
• int ostrstream::frozen(): This member can be used to test whether freeze(1) is in effect for this string.

12.3.2: Writing streams

To open a file to write to, the ofstream constructor receives the name of the file to be opened:

By default this will result in the creation of the file, and information inserted into it will be written from the beginning of the file. Actually, this corresponds to the creation of the ofstream object in standard output mode, for which the enumeration value ios::out could have been provided as well:

Alternatively, instead of (re)writing the file, the ofstream object could be created in the append mode, using the ios::app mode indicator:

Normally, information will be inserted into the ofstream object using the insertion operator <<, in the way it is used with the standard streams like cout, e.g.:

Just like the fopen() function of C may fail, the construction of the ofstream object might not succeed. When an attempt is made to create an ofstream object, it is a good idea to test the successful construction. The ofstream object returns 0 if its construction failed. This value can be used in tests, and the code can throw an exception (see chapter 13) or it can handle the failure itself, as in the following code:

    #include <iostream>
    #include <fstream>
    
    int main()
    {
        ofstream
            out("/");   // creating 'out' fails
            
        if (!out)
        {
            cerr << "creating ofstream object failed\n";
            exit(1);
        }
    }

Alternatively, a ofstream object may be constructed first, and opened later:

    ofstream
        out;

    out.open("outfile");
        

Analogous to an ofstream object, an ostrstream object can be created. Here no filename is required. E.g.,

An ostrstream object may be initialized by an ascii-z string. E.g.,

12.3.3: Reading streams

To open a file to read from, the ifstream constructor receives the name of the file to be opened:

By default this will result in the opening of the file for reading. The file must exist for the ifstream object construction to succeed. Instead of the shorthand form to open a file for reading, and explicit ios flag may be used as well:

As with the ofstream objects, ifstream objects may be constructed first, and opened later:

    ifstream
        ifstr;

    ifstr.open("infile");
        

By default, the extraction operator skips blanks: between words, between characters, between numbers, etc.. Consequently, if the input consists of the following information:

    12 
    13
    a b 
    hello world

    int
        x,
        y;
    char
        c,
        buffer[10];
        
    in >> x >> y >> c >> c >> buffer >> buffer;

Just like the fopen() function of C may fail, the construction of the ifstream object might not succeed. When an attempt is made to create an ifstream object, it is a good idea to test the successful construction. The ifstream object returns 0 if its construction failed. This value can be used in tests, and the code can throw an exception (see section 13) or it can handle the failure itself, as in the following code:

    #include <iostream>
    #include <fstream>
    
    int main()
    {
        ifstream
            in("");         // creating 'in' fails
            
        if (!in)
        {
            cerr << "creating ifstream object failed\n";
            exit(1);
        }
    }

Analogous to an ifstream object, an istrstream object can be created. Here no filename is required. E.g.,

12.3.4: Reading and writing streams

Note the use of the ios constants ios::in and ios::out, indicating that the file must be opened both for reading and writing. Multiple mode indicators may be used, concatenated by the binary or operator '|'. Alternatively, instead of ios::out, ios::app might have been used, in which case writing will always be done at the end of the file.

Under DOS-like operating systems, which use the multiple character \r\n sentinels to separate lines in textfiles the flag ios::binary (or ios::bin) is required for processing binary files to ensure that \r\n combinations are processed as two characters.

With fstream objects, the ios::out will result in the creation of the file, if the file doesn't exist, and if ios::out is the only mode specification of the file. If the mode ios::in is given as well, then the file is created only if it doesn't exist. So, we have the following possibilities:

                       
    -------------------------------------------------------------
                                 Specified Filemode            
                    ---------------------------------------------
     File:                ios::out            ios::in | ios::out
    -------------------------------------------------------------
     exists           File is rewritten     File is used as found
    
    doesn't exist      File is created         File is created
    -------------------------------------------------------------

Once a file has been opened in read and write mode, the << operator may be used to write to the file, while the >> operator may be used to read from the file. These operations may be performed in random order. The following fragment will read a blank-delimited word from the file, will write a string to the file, just beyond the point where the string just read terminated, and will read another string: just beyond the location where the string just written ended:

    ...
    fstream
        f("filename", ios::in | ios::out);
    char
        buffer[80]; // for now assume this 
                    // is long enough
        
    f >> buffer;    // read the first word    

                    // write a well known text 
    f << "hello world";
    
    f >> buffer;    // and read again

The answer is: it doesn't. The compiler casts the fstream object into an ifstream object in combination with the extraction operator, and into an ofstream object in combination with the insertion operator. Consequently, a statement like

Of course, random insertions and extractions are hardly used. Generally, insertions and extractions take place at specific locations in the file. In those cases, the position where the insertion or extraction must take place can be controlled and monitored by the seekg() and tellg() member functions.

The member function tellg() returns the current offsetposition of the stream for which it is called.

The member function seekg() expects two arguments, the second one having a default value:

• ios::beg: add offset to the begin of file position. Negative offsets result in an error condition, which must be cleared before any further operations on the file will succeed.
• ios::end: add offset to the end of file position. Positive offsets result in the insertion of as many padding (char)0 characters as necessary to reach the intended offset.
• ios::cur: add offset to the current file position. If adding the offset to the current position would result in a position before ios::beg, then, again, an error condition results. If the position would be beyond ios::end, then extra (char)0 characters are supplied.

Error conditions (see also section 12.3.6) occurring due to, e.g., reading beyond end of file, reaching end of file, or positioning before begin of file, can be cleared using the clear() member function. Following clear() processing continues. E.g.,

    ...
    fstream
        f("filename", ios::in | ios::out);
    char
        buffer[80]; // for now assume this 
                    // is long enough

    f.seekg(-10);   // this fails, but...
    f.clear();      // processing f continues

    f >> buffer;    // read the first word    

Strstream objects can be given flags as well. The ostrstream object may be constructed by the following constructor:

12.3.5: Special functions

For reading the following member functions, that can be used with istream objects (which includes ifstream and fstream objects) are available:

• int istream::get(): this function returns EOF or the next available single character as an int value.
• istream &istream::get(char &c): this function reads the next single character from the input stream into c.
• int istream::peek(): this function returns the next available input character, but does not actually remove the character from the input stream.
• istream& istream::get(char *buffer, int len [, char delimiter]): This function reads a string from the input stream into the array starting at buffer, which should be at least len bytes long. At most len - 1 characters are read into the buffer. The delimiter is a newline ('\n') character by default.
  Note that the delimiter is not read by get() if the delimiter is encountered in the input stream.
  After reading the string into buffer, an ascii-Z character is appended to the string in buffer delimiter.
  Note that the functions eof() and fail() (see section 12.3.6) do not return true if the delimiter was not encountered on input. Furthermore, an ascii-Z character can be used for the delimiter: this way strings terminating in ascii-Z characters may be read from a (binary) file. Of course, the program reading the string should know in advance the number of characters that are going to be read by the function. A small example illustrating the use of get() in combination with ascii-Z delimiters is:

  
      #include <fstream>
      
      void main(int argc, char **argv)
      {
          fstream
              f(argv[1], ios::in | ios::out); // r/w the file, assume this 
                                              // succeeds
          f.write("hello", 6);
          f.write("hello", 6);
      
          f.seekg(0, ios::beg);               // reset to begin of file
      
          char 
              buffer[20],
              c;
                                              // read the first `hello'
          cout << f.get(buffer, 100, 0).tellg() << endl;;
          f >> c;                             // read the ascii-z delim
  
                                              // and read the second `hello'
          cout << f.get(buffer + 6, 100, 0).tellg() << endl;;
      }
          
  

• istream& istream::getline (char *buffer, int len [, char delimiter]) This function operates analogously to get(), but delimiter is removed from the input if it is actually encountered. At most len - 1 bytes are written into the buffer, and a trailing ascii-Z character is appended to the string that was read. The delimiter itself is not stored in the buffer. If delimiter was not found (before reading len characters or EOF, getline() the fail() member function, and possibly also eof() will return true.
  
• istream& istream::read(void *buffer, int len): this function reads at most len bytes from the input stream into the buffer. If EOF is encountered first, fewer bytes are read, and the member function eof() will return true. This function will normally be used for writing binary files. In the following example, an object of the class Date is written in its binary form to a file:

  
      #include <fstream>
  
      class Date
      {
          public:
              unsigned
                  year,
                  month,
                  day;
      };
          
      void main(int argc, char **argv)
      {
          ofstream
              f(argv[1], ios::out);
          Date
              d;
          f.read(&d, sizeof(Date));  // reads object in binary form.
      }
          
  

• int istream::gcount(): this function does not actually read from the input stream, but returns the number of characters that were read from the input stream during the last unformated input operation.
• istream& istream::ignore ([int n [, int delimiter]]): called without arguments, one character is skipped from the input stream. Called with one argument, n characters are skipped. The optional second argument specifies a delimiter: after skipping n or the delimiter character (whichever comes first) the function returns.
• istream& istream::putback (char c): the character c is `pushed back' into the input stream, to be read as the next character. EOF is returned if this is not allowed. One character may always be put back.
• istream& istream::unget(): an attempt is made to push back the last character that was read.

For writing binary files the following member functions are available. These functions can be used with ostream objects (including ofstream and fstream objects):

• ostream& ostream::put(char c): this function writes a single character to the output stream.
• ostream& ostream::write (void *buffer, int length): this function writes at most len bytes to the output stream. This function will normally be used for writing binary files.
• ostream& ostream::flush(): any pending output on the output stream is written.

12.3.6: Good, bad, and ...: IOStream Condition States

Several condition member functions of the fstreams exist to manipulate or determine the states of the stream:

• bad(): this member function returns a non-zero value when an invalid operation has been requested, like seeking before the begin of file position.
• eof(): this member function returns a non-zero value when the stream has reached end of file (EOF).
• fail(): this member function returns a non-zero value when eof() or bad() returns a non-zero value.

A subtlety is the following: Assume a stream is constructed, but not attached to an actual file. E.g., the statement ifstream instream creates the stream object, but doesn't assign it to a file. However, if we next check it's status through good() this member will return a non-zero value. The `good' status here indicates that the stream object has been cleanly constructed. It doesn't mean the file is also open. A direct test for that can be performed by inspecting instream.rdbuf()->is_open. If non-zero, the stream is open.

When an error condition has occurred (i.e., fail() returns a non-zero value), and can be repaired, then the member function clear() should be called to clear the error status of the file.

12.3.7: Formating

Apart from these member functions, member functions are available for defining the precision and the way numbers are displayed. Apart from using members, manipulators exist for controlling the display form and the width of output and input elements. Different from member functions, manipulators are part of insertion or extraction statements.

12.3.7.1: The (v)form() and (v)scan() members

To format information to be inserted into a stream the member form() is available:

The member function form() is the analogue of C's fprintf() function. When variadic functions are constructed in which information must be inserted into a stream, the member function vform() can be used, being the analogue of vfprintf().

To scan information from a stream, the member function scan() can be used, which is the analogue of C's fscanf() function. Similarly to vfscanf(), the member function vscan() can be used in variadic functions.

12.3.7.2: Manipulators: dec, hex, oct and other manipulators

The iostream objects maintain format states controlling the default formating of values. The format states can be controlled by member functions and by manipulators. Manipulators are inserted into the stream, the member functions are used by themselves.

The following manipulators are available:

• dec, hex, oct: These manipulators enforce the display of integral numbers in, respectively, decimal, hexadecimal and octal format. The default conversion is decimal. The conversion takes effect on information inserted into the stream after processing the manipulators. So, a statement like: cout << 16 << ", " << hex << 16 << ", " << oct << 16; will produce the output 16, 10, 20

• setbase(int b): This manipulator can be used to display integral values using the base 8, 10 or 16. It can be used instead of oct, dec, hex in situations where the base of integral values is parameterized.

• setfill(int ch): This manipulator defines the filling character in situations where the values of numbers are too small to fill the width that is used to display these values. By default the blank space is used.

• setprecision(int width): This manipulator can be used to set the precision in which a float or double is displayed. In order to use manipulators requiring arguments the header file iomanip must be included.

• setw(int width): This manipulator expects as its argument the width of the field that is inserted or extracted next. It can be used as manipulator for insertion, where it defines the maximum number of characters that are displayed for the field, and it can be used with extraction, where it defines the maximum number of characters that are inserted into an array.

  For example, to insert 20 characters into cout, use:

  cout << setw(20) << 8 << endl;

  To prevent array-bounds overflow when extracting from cin, setw() can be used as well:

  cin >> setw(sizeof(array)) >> array; A nice feature here is that a long string appearing at cin is split into substrings of at most sizeof(array) - 1 characters, and an ascii-z is appended. Notes:
  • setw() is valid only for the next field. It does not act like e.g., hex which changes the general state of the output stream for displaying numbers.
  • When setw(sizeof(someArray)) is used, make sure that someArray really is an array, and not a pointer to an array: the size of a pointer, being 2 or 4 bytes, is usually not the size of the array that it points to....
  • In order to use setw() the header file iomanip must be included.

12.3.7.3: Setting the precision: the member precision()

The function precision() is used to define the precision of the display of floating point numbers. The function expects the number of digits (not counting the decimal point or the minus sign) that are to be displayed as its argument. For example,

    cout.precision(4);
    cout << sqrt(2) << endl;
    cout.precision(6);
    cout << -sqrt(2) << endl;

    1.414
    -1.41421

When used without argument, precision() returns the actual precision value:

    cout.precision(4);
    cout << cout.precision() << ", " << sqrt(2) << endl;

12.3.7.4: (Un)Setting display flags: the member (un)setf()

The member function setf() is used to define the way numbers are displayed. It expects one or two arguments, all flags of the iostream class. In the following examples, cout is used, but other ostream objects might have been used as well:

• To display the numeric base of integral values, use cout.setf(ios::showbase) This results in no prefix for decimal values, 0x for hexadecimal values, 0 for octal values. For example:

  
      cout.setf(ios::showbase);
      cout << 16 << ", " << hex << 16 << ", " << oct << 16 << endl;
  
  

  results in: 16, 0x10, 020
• To display a trailing decimal point and trailing decimal zeros when real numbers are displayed, use cout.setf(ios::showpoint) For example:

  
      cout.setf(ios::showpoint);
      cout << 16.0 << ", " << 16.1 << ", " << 16 << endl;
  
  

  results in: 16.0000, 16.1000, 16 Note that the last 16 is an integral rather than a real number, and is not given a decimal point.

  If ios::showpoint is not used, then trailing zeros are discarded. If the decimal part is zero, then the decimal point is discarded as well.

• Comparable to the dec, hex and oct manipulators

  
      cout.setf(ios::dec, ios::basefield);
      cout.setf(ios::hex, ios::basefield);
  
  

  or

  
      cout.setf(ios::oct, ios::basefield);
  
  

  can be used.
• To control the way real numbers are displayed cout.setf(ios::fixed, ios::floatfield) or cout.setf(ios::scientific, ios::floatfield) can be used. These settings result in, respectively, a fixed value display or a scientific (power of 10) display of numbers. For example,

  
      cout.setf(ios::fixed, ios::floatfield);
      cout << sqrt(200) << endl;
      cout.setf(ios::scientific, ios::floatfield);
      cout << sqrt(200) << endl;
  
  

  results in

  
      14.142136
      1.414214e+01
  
  

• ios::left: This format state is used to left-adjust the display of values for which the setw() manipulator (see below) is used. The format state can be set using the setf() member function, and it can be unset using the unsetf() member function. By default values are right-adjusted.

• ios::internal: This format state will add the fill-characters (blanks by default) between the minus sign of negative numbers and the value itself.

With istream objects the flag ios::skipws can be used to control the handling of whitespace characters when characters are extracted. Leading white space characters of numerical values are skipped when istreamObject.unsetf(ios::skipws) has been specified, but otherwise they must be read explicitly. Reading a char * or string variable in this situation will only succeed if the first character to be read isn't a white-space character. The following small program can be used to illustrate the effects of unsetting ios::skipws:

#include <iostream>
#include <string>

int main()
{
    string
        buffer;
    int
        i;
    char
        c;

    cin.unsetf(ios::skipws);

    cin >> i;           // skips leading ws
    cin >> buffer;      // doesn't skip leading ws.

    cout << "got " << i << " and " << buffer << endl;

    while (cin >> c)    // reads individual chars, if the previous        
        cout << "got '" << c << "'\n";    // extraction succeeded.

    return (0);    
}
    

Summarizing:

• setf(ios::showbase) is used to display the numeric base of integral values,
• setf(ios::showpoint) is used to display the trailing decimal point and trailing zeros of real numbers
• setf(ios::dec, ios::basefield), setf(ios::hex, ios::basefield) and setf(ios::oct, ios::basefield) can be used instead of the dec, hex and oct manipulators.
• cout.setf(ios::scientific, ios::floatfield) and cout.setf(ios::fixed, ios::floatfield) can be used to obtain a fixed or scientific (power of 10) display of real values.
• setf(ios::left) is used to left-adjust values in the width of their fields
• setf(ios::internal) is used to left-adjust the minus sign of negative values (while the values themselves are right adjusted).
• ios::skipws is used to control the handling of white space characters by the extraction operator.

To unset flags, the function unsetf() can be used.

12.3.8: Constructing manipulators

Actually the construction of a manipulator is rather simple. To start, a definition of the manipulator is needed. Let's assume we want to create a manipulator w10 which will set the field width of the next field to be written to the ostream object to 10. This manipulator is constructed as a function. The w10 function will have to know about the ostream object in which the width must be set. By providing the function with a ostream & parameter, it obtains this knowledge. Now that the function knows about the ostream object we're referring to, it can set the width in that object.

Furthermore, it must be possible to use the manipulator in a <<-sequence. This implies that the return value of the manipulator must be a reference to an ostream object also.

From the above considerations we're now able to construct our w10 function:

    #include <iostream>
    #include <iomanip>

    ostream &w10(ostream &str)
    {
        return (str << setw(10));
    }
        

The w10 function can of course be used in a `stand alone' mode, but it can also be used as a manipulator. E.g.,

        #include <iostream>
        #include <iomanip>
    
        extern ostream &w10(ostream &str);
    
        int main()
        {
            w10(cout) << 3 << " ships sailed to America" << endl;
            cout << "And " << w10 << 3 << " other ships sailed too." << endl;
        }
    

The w10 function can be used as manipulator because the class ostream has an overloaded operator<< accepting a pointer to a function that takes an ostream & and returns an ostream &. Its definition is:

    ostream& operator<<(ostream & (*func)(ostream &str)) 
    {
        return ((*func)(*this)); 
    }
        

• Next chapter
• Previous chapter
• Table of contents