File streams reference

Introduction

The C++ libraries provide the ability to perform input and output using streams. A "stream" is a sequence of characters read or written from an I/O device or file. You've probably already tried using the three C++ standard streams: cin, cout, cerr and clog. This tech note will, hopefully, extend that knowledge and experience to file I/O streams.

File input or output usually involves an idiomatic sequence of operations:

• Open a file stream for input (or output.)
• Read data items from the input stream (or write data items to the output stream) until the end of file is reached.
• Close the input (or output) stream when finished.

We will provide code examples for both input and output. We will also briefly list format manipulator and stream methods that give more control over I/O conversion and stream behavior. We will start with output first as it is usually simpler to code.

Output code examples

Before doing any file stream-related operations, we must first include definitions for the C++ standard library fstream:

    #include <fstream>
    using namespace std ;

In order to write data to a file, we begin by defining a file output stream object:

    ofstream outputStream ;

    outputStream.open("filename") ;

Note: The open method may also take an optional second parameter which is the intended access mode: ios::in, ios::trunc, ios::out, ios::app, ios::ate, or ios::binary. Usually the default mode is sufficient.

The definition of a file input stream and opening of the stream can be combined into one definition:

    ofstream outputStream("filename") ;

Due to file and directory permission rules, the open method may fail. For example, the user may be running the program in a directory that does not permit writing by that user. The program should always check for failure. The value of outputStream will be zero (null) if the open method fails, so checking for failure is easy:

    if (outputStream == 0) {
      cerr << "Error! Couldn't open output file for writing" << endl ;
      exit( 0 ) ;
    }

• If the open is embedded in a function, return an error value to the function's caller, bumping responsibility for recovery to the caller.
• Prompt the user for a different file name and try again.
• Throw an exception that bumps responsibility for recovery to a caller that has executed a catch for the exception.

Note: Another way to check if the file was successfully opened is:

    assert(outputStream.is_open()) ;

The error message generated by assert is not very informative and assert terminates the program. So, this method is not particularly desirable from the user's perspective.

Once the output file stream is open, the program can use the stream insertion operator, <<, to send values to the output stream for writing. The syntax is similar to working with cout:

    int value ;
    ...
    value = 42 ;
    outputStream << "The answer is " << value << "." << endl ;

After writing data to the output file, you should close the file. This is accomplished by calling the stream's close method:

    outputStream.close() ;

The example below pulls all of these parts together into a short program. Feel free to borrow from this program when working on your assignments. Try compiling the program and running it. You can exercise the error case by changing the permissions on the file "filename" to make it read-only. The open method will fail causing the error message to display and the program to exit.

    #include <iostream>
    #include <fstream>
    using namespace std ;

    int main(int argc, char *argv[])
    {
      ofstream outputStream ;
      int value ;

      outputStream.open("filename") ;

      if (outputStream == 0) {
        cerr << "Error! Couldn't open output file for writing" << endl ;
        exit( 0 ) ;
      }

      value = 42 ;
      outputStream << "The answer is " << value << "." << endl ;

      outputStream.close() ;
    }

Output manipulators and methods

File output streams support format manipulators that control the formatting of data during output. We've seen these same format manipulators before when working with the standard output and standard error streams.

Other format manipulators are available by including the standard C++ library iomanip. The following table shows a few of the format manipulators from that library.

Output streams also support methods, which are functions that can be applied to an output stream. The table below describes a few of the methods that can be applied to an output stream like count, cerr and clog, as well as a file output stream.

Input code examples

Reading data from a file follows a similar pattern. However, we must also handle the case when the end-of-file has been reached and no more data items are available to be read. The code to include fstream, define an input file stream and check for success is similar to the code for output:

    #include <iostream>
    #include <fstream>
    using namespace std ;
    ...
    ifstream inputStream ;

    inputStream.open("numbers") ;

    if (inputStream == 0) {
      cerr << "Error! Couldn't open input file for reading" << endl ;
      exit( 0 ) ;
    }

Note: One way to test the error case, is to temporarily rename the file to something else to simulate a non-existent file. Or, set the the file permissions to disallow reading, e.g., chmod 0222 file. Then run the program and induce the error condition. Your error handling code will be invoked. Be sure to re-establish the original name or file permissions!

The input and output stream classes provide method functions that check the status of a stream.

• The is_open() method returns true if the stream is open for input or output.
• The eof() method returns true if the input stream has reached the end of the file.
• The good() method returns true if the stream is healthy.
• The bad() method returns true if an unrecoverable error has occurred while accessing the stream.
• The fail() method returns true if a recoverable error has occurred while accessing the stream.

The following code idiom reads a sequence of values from an input stream until the end-of-file is reached:

    int value ;
    ...
    for( ; ; ) {
      ...
      inputStream >> value ;
      if (inputStream.eof()) break ;
      if (inputStream.fail()) {
        cerr << "Error! Failure while reading input stream" << endl ;
        break ;
      }
      ...
    }

    inputStream.close() ;

Putting together the pieces, here is a short program that reads a sequence of integers from a file. The program counts the number of integer values that were read and computes the sum of the integers. When finished, the program displays the number read and the sum, and closes the input file.

    #include <iostream>
    #include <fstream>
    using namespace std ;

    int main(int argc, char *argv[])
    {
      ifstream inputStream ;
      int value, count, sum ;

      inputStream.open("numbers") ;

      if (inputStream == 0) {
        cerr << "Error! Couldn't open input file for reading" << endl ;
        exit( 0 ) ;
      }

      for( count = 0, sum = 0 ; ; ) {
        inputStream >> value ;
        if (inputStream.eof()) break ;
        if (inputStream.fail()) {
          cerr << "Error! Failure while reading input stream" << endl ;
          break ;
        }
        sum = sum + value ;
        count = count + 1 ;
      }

      cout << "Numbers read: " << count << endl ;
      cout << "Sum:          " << sum << endl ;

      inputStream.close() ;
    }

    Numbers read: 11
    Sum:          55

    Error! Failure while reading input stream
    Numbers read: 4
    Sum:          6

Input manipulators and methods

The following table describes a few of the format manipulators that can be used to control the conversion of data on input. These format manipulators can also be applied to the standard input stream, cin, since the standard input stream is just a specific kind of input stream. (This relationship is called "inheritance" because cin inherits these manipulators from the parent input stream class.)

A number of input stream methods are suppported. A few of these methods are summarized in the table below.

Character input

The following short program illustrates the use of the method get() to read individual characters from the file named "characters." The program echoes the characters to the screen. Try experimenting with the other input stream methods to see what they do and how they handle newline characters.

    #include <iostream>
    #include <fstream>
    using namespace std ;

    int main(int argc, char *argv[])
    {
      ifstream inputStream ;
      char c ;

      inputStream.open("characters") ;

      if (inputStream == 0) {
        cerr << "Error! Couldn't open input file for reading" << endl ;
        exit( 0 ) ;
      }

      for( ; ; ) {
        c = inputStream.get() ;
        if (inputStream.eof()) break ;
        if (inputStream.fail()) {
          cerr << "Error! Failure while reading input stream" << endl ;
          break ;
        }
        cout << c ;
      }

      inputStream.close() ;
    }