Output File Stream Member Functions

Output stream member functions have three types: those that are equivalent to manipulators, those that perform unformatted write operations, and those that otherwise modify the stream state and have no equivalent manipulator or insertion operator. For sequential, formatted output, you might use only insertion operators and manipulators. For random-access binary disk output, you use other member functions, with or without insertion operators.

The open Function for Output Streams

To use an output file stream (ofstream), you must associate that stream with a specific disk file in the constructor or the open function. If you use the open function, you can reuse the same stream object with a series of files. In either case, the arguments describing the file are the same.

When you open the file associated with an output stream, you generally specify an open_mode flag. You can combine these flags, which are defined as enumerators in the ios class, with the bitwise OR ( | ) operator. See ios_base::openmode for a list of the enumerators.

Three common output stream situations involve mode options:

• Creating a file. If the file already exists, the old version is deleted.

  ofstream ofile("FILENAME");
  // Default is ios::out
  
  ofstream ofile("FILENAME", ios::out);
  // Equivalent to above
  

• Appending records to an existing file or creating one if it doesn't exist.

  ofstream ofile("FILENAME", ios::app);
  

• Opening two files, one at a time, on the same stream.

  ofstream ofile();
  ofile.open("FILE1", ios::in);
  // Do some output
  ofile.close();    // FILE1 closed
  ofile.open("FILE2", ios::in);
  // Do some more output
  ofile.close();    // FILE2 closed
  // When ofile goes out of scope it is destroyed.
  

The put function

The put function writes one character to the output stream. The following two statements are the same by default, but the second is affected by the stream's format arguments:

cout.put('A');

// Exactly one character written
cout <<'A'; // Format arguments 'width' and 'fill' apply

The write function

The write function writes a block of memory to an output file stream. The length argument specifies the number of bytes written. This example creates an output file stream and writes the binary value of the Date structure to it:

// write_function.cpp
// compile with: /EHsc
#include <fstream>
using namespace std;

struct Date
{
   int mo, da, yr;
};

int main( )
{
   Date dt = { 6, 10, 92 };
   ofstream tfile( "date.dat" , ios::binary );
   tfile.write( (char *) &dt, sizeof dt );
}

The write function doesn't stop when it reaches a NULL character, so the complete class structure is written. The function takes two arguments: a char pointer and a count of characters to write. Note the required cast to char * before the address of the structure object.

The seekp and tellp Functions

An output file stream keeps an internal pointer that points to the position where data is to be written next. The seekp member function sets this pointer and thus provides random-access disk file output. The tellp member function returns the file position. For examples that use the input stream equivalents to seekp and tellp, see The seekg and tellg Functions.

The close Function for Output Streams

The close member function closes the disk file associated with an output file stream. The file must be closed to complete all disk output. If necessary, the ofstream destructor closes the file for you, but you can use the close function if you need to open another file for the same stream object.

The output stream destructor automatically closes a stream's file only if the constructor or the open member function opened the file. If you pass the constructor a file descriptor for an already-open file or use the attach member function, you must close the file explicitly.

Error Processing Functions

Use these member functions to test for errors while writing to a stream:

The ! operator is overloaded to perform the same function as the fail function. Thus the expression:

if(!cout)...

is equivalent to:

if(cout.fail())...

The void*() operator is overloaded to be the opposite of the ! operator; thus the expression:

if(cout)...

is equal to:

if(!cout.fail())...

The void*() operator isn't equivalent to good because it doesn't test for the end of file.

See also

Output Streams