Output File Stream Member Functions

You have already seen the formatting member function width. The setw manipulator served as a substitute and was more convenient for formatted I/O that used the insertion operator. There are three classes of output stream member functions:

Member functions that are equivalent to manipulators

Member functions that perform unformatted write operations

Member functions that otherwise modify the stream state and have no equivalent manipulator or insertion operator

If you need sequential, formatted output, you might use only manipulators and insertion operators, but if you need random-access binary disk output, you would use several other member functions. In this second case, you may choose to use no insertion operators at all.

The following member functions are particularly useful for disk output. For a complete list of stream member functions, see Part 3 of the Class Libraries Reference.

The open Function

If you are using an output file stream (ofstream), then you must associate that stream with a specific disk file. You can make this association in the constructor, or you can use the open function. The second method allows you to reuse the same stream object with a series of separate files. In either case, the parameters describing the file are the same.

You generally specify an open_mode flag when you open the file associated with an output stream (there is a default mode parameter). Here is a list of the open_mode flags defined as enumerators in the ios class. Note that the list includes flags for both input and output streams. The flags can be combined as appropriate using the bitwise OR (|) operator.

Here are three common output stream situations that involve the mode options:

You want to create a file. If it already exists, delete the old version.

ostream ofile( "FILENAME" ); // Default is ios::out

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

You want to append records to an existing file or create one it if it does not exist.

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

You want to open 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 a single character to the output stream. The following two statements are the same by default, but the second is affected by the stream's format parameters:

cout.put( 'A' ); // Exactly one character written

cout << 'A'; // Format parameters 'width' and 'fill' apply

The write Function

The write member function writes a block of memory to an output file stream. The number of bytes written is determined by the specified length parameter. The function accommodates the complex binary data structures found in many business and scientific applications.

Example 8

Example 8 shows the write member function being used to write binary data to an output file stream.

// exios108.cpp

// The write member function

#include <fstream.h>

struct Date

{

int mo, da, yr;

};

void main()

{

Date dt = { 6, 10, 91 };

ofstream tfile( "date.dat" , ios::binary );

tfile.write( (char *) &dt, sizeof dt );

}

The program creates an output file stream and writes the binary value of the Date structure to it. The write function does not stop writing when it reaches a null character, so the complete class structure is written regardless of its content. For an explanation of ios::binary, see “Binary Output Files” on page 378.

The write function takes two arguments: a char pointer and a count of characters to write. Note the cast to char* before the address of the structure object. Without this cast, the program would not compile.

The seekp and tellp Functions

An output file stream keeps an internal pointer corresponding to the position in the file where data will be written next. The seekp member function sets that pointer and thus allows random-access disk file output. The seekp function is often used in conjunction with the seekg function in input/output streams. For a programming example that uses the input stream equivalent to the seekp function, see the description for seekg in “Input Streams” on page 382.

The tellp member function returns the current file position. For a programming example that uses the input stream equivalant to the tellp function, see the description for tellg in “Input Streams” on page 382.

The close Function

Use the close member function to close the disk file associated with an output file stream. The file must be closed in order to properly update the disk. 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.

Note:

The output stream destructor automatically closes the stream's file only if the file was opened by the constructor or by the open member function. If you have passed the constructor a file descriptor for an already-open file or if you have used the attach member function, then it is your responsibility to close the file.

Error Processing Functions

These member functions enable you 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 equivalent to if( !cout.fail() )...

Note that the void*() operator is not the same as good because it doesn't test for the end-of-file condition.