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.
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:
ostream ofile( "FILENAME" ); // Default is ios::out
ofstream ofile( "FILENAME", ios::out ); // Equivalent to above
ofstream ofile( "FILENAME", ios::app );
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 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 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.
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 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.
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 “expected?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’t test for the end of file.