Classes for Files and Strings

There are two very common special cases of input and output: using files, and using strings in memory.

libio defines four specialized classes for these cases:

ifstream

Methods for reading files.

ofstream

Methods for writing files.

istrstream

Methods for reading strings from memory.

ostrstream

Methods for writing strings in memory.

• Files: Reading and writing files.
• Strings: Reading and writing strings in memory.

Reading and writing files

These methods are declared in `fstream.h'.

You can read data from class ifstream with any operation from class istream. There are also a few specialized facilities:

Constructor: ifstream::ifstream ()

Make an ifstream associated with a new file for input. (If you use this version of the constructor, you need to call ifstream::open before actually reading anything)

Constructor: ifstream::ifstream (int fd)

Make an ifstream for reading from a file that was already open, using file descriptor fd. (This constructor is compatible with other versions of iostreams for POSIX systems, but is not part of the ANSI working paper.)

Constructor: ifstream::ifstream (const char* fname [, int mode [, int prot]])

Open a file *fname for this ifstream object.

By default, the file is opened for input (with ios::in as mode). If you use this constructor, the file will be closed when the ifstream is destroyed.

You can use the optional argument mode to specify how to open the file, by combining these enumerated values (with `|' bitwise or). (These values are actually defined in class ios, so that all file-related streams may inherit them.) Only some of these modes are defined in the latest draft ANSI specification; if portability is important, you may wish to avoid the others.

ios::in

Open for input. (Included in ANSI draft.)

ios::out

Open for output. (Included in ANSI draft.)

ios::ate

Set the initial input (or output) position to the end of the file.

ios::app

Seek to end of file before each write. (Included in ANSI draft.)

ios::trunc

Guarantee a fresh file; discard any contents that were previously associated with it.

ios::nocreate

Guarantee an existing file; fail if the specified file did not already exist.

ios::noreplace

Guarantee a new file; fail if the specified file already existed.

ios::bin

Open as a binary file (on systems where binary and text files have different properties, typically how `\n' is mapped; included in ANSI draft).

The last optional argument prot is specific to Unix-like systems; it specifies the file protection (by default `644').

Method: void ifstream::open (const char* fname [, int mode [, int prot]])

Open a file explicitly after the associated ifstream object already exists (for instance, after using the default constructor). The arguments, options and defaults all have the same meanings as in the fully specified ifstream constructor.

You can write data to class ofstream with any operation from class ostream. There are also a few specialized facilities:

Constructor: ofstream::ofstream ()

Make an ofstream associated with a new file for output.

Constructor: ofstream::ofstream (int fd)

Make an ofstream for writing to a file that was already open, using file descriptor fd.

Constructor: ofstream::ofstream (const char* fname [, int mode [, int prot]])

Open a file *fname for this ofstream object.

By default, the file is opened for output (with ios::out as mode). You can use the optional argument mode to specify how to open the file, just as described for ifstream::ifstream.

The last optional argument prot specifies the file protection (by default `644').

Destructor: ofstream::~ofstream ()

The files associated with ofstream objects are closed when the corresponding object is destroyed.

Method: void ofstream::open (const char* fname [, int mode [, int prot]])

Open a file explicitly after the associated ofstream object already exists (for instance, after using the default constructor). The arguments, options and defaults all have the same meanings as in the fully specified ofstream constructor.

The class fstream combines the facilities of ifstream and ofstream, just as iostream combines istream and ostream.

The class fstreambase underlies both ifstream and ofstream. They both inherit this additional method:

Method: void fstreambase::close ()

Close the file associated with this object, and set ios::fail in this object to mark the event.

Reading and writing in memory

The classes istrstream, ostrstream, and strstream provide some additional features for reading and writing strings in memory--both static strings, and dynamically allocated strings. The underlying class strstreambase provides some features common to all three; strstreambuf underlies that in turn.

Constructor: istrstream::istrstream (const char* str [, int size])

Associate the new input string class istrstream with an existing static string starting at str, of size size. If you do not specify size, the string is treated as a NUL terminated string.

Constructor: ostrstream::ostrstream ()

Create a new stream for output to a dynamically managed string, which will grow as needed.

Constructor: ostrstream::ostrstream (char* str, int size [,int mode])

A new stream for output to a statically defined string of length size, starting at str. You may optionally specify one of the modes described for ifstream::ifstream; if you do not specify one, the new stream is simply open for output, with mode ios::out.

Method: int ostrstream::pcount ()

Report the current length of the string associated with this ostrstream.

Method: char* ostrstream::str ()

A pointer to the string managed by this ostrstream. Implies `ostrstream::freeze()'.

Note that if you want the string to be nul-terminated, you must do that yourself (perhaps by writing ends to the stream).

Method: void ostrstream::freeze ([int n])

If n is nonzero (the default), declare that the string associated with this ostrstream is not to change dynamically; while frozen, it will not be reallocated if it needs more space, and it will not be deallocated when the ostrstream is destroyed. Use `freeze(1)' if you refer to the string as a pointer after creating it via ostrstream facilities.

`freeze(0)' cancels this declaration, allowing a dynamically allocated string to be freed when its ostrstream is destroyed.

If this ostrstream is already static--that is, if it was created to manage an existing statically allocated string---freeze is unnecessary, and has no effect.

Method: int ostrstream::frozen ()

Test whether freeze(1) is in effect for this string.

Method: strstreambuf* strstreambase::rdbuf ()

A pointer to the underlying strstreambuf.