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.

Flag	Function
ios::app	Opens an output file for appending.
ios::ate	Opens an existing file (either input or output) and seeks the end.
ios::in	Opens an input file. Use ios::in as an open_mode for an ofstream file to prevent truncating an existing file.
ios::out	Opens an output file. When you use ios::out for an ofstream object without ios::app, ios::ate, or ios::in, ios::trunc is implied.
ios::nocreate	Opens a file only if it already exists; otherwise the operation fails.
ios::noreplace	Opens a file only if it does not exist; otherwise the operation fails.
ios::trunc	Opens a file and deletes the old file (if it already exists).
ios::binary	Opens a file in binary mode (default is text mode).

Three common output stream situations involve mode options:

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

ostream 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 does not 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𠏋 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:

#include <fstream.h>

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

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

The write function does not 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 equivalants 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𠏋 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:

Function	Return value
bad	Returns TRUE if there is an unrecoverable error.
fail	Returns TRUE if there is an unrecoverable error or an 婫xpected?condition, such as a conversion error, or if the file is not found. Processing can often resume after a call to clear with a zero argument.
good	Returns TRUE if there is no error condition (unrecoverable or otherwise) and the end-of-file flag is not set.
eof	Returns TRUE on the end-of-file condition.
clear	Sets the internal error state. If called with the default arguments, it clears all error bits.
rdstate	Returns the current error state. For a complete description of error bits, see the Class Library Reference.

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 is not equivalent to good because it doesn㦙 test for the end of file.