The author of this software is David M. Gay.

Copyright (c) 1991 by AT&T.

Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

4 Classes for Files and Strings

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

Iostream 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.

4.1 Reading and writing files

These methods are declared in `fstream.h'

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

Constructor: ifstream::ifstream (): Makes an ifstream associated with a new file for input. (If this version of the constructor is used , call ifstream::open before actually reading anything)

Constructor: ifstream::ifstream (int fd): Makes 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]])

Opens a file *fname for this ifstream object.

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

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, avoid the others.

ios::in: Open for input. (Included in ANSI draft.)
ios::out: Open for output. (Included in ANSI draft.)
ios::ate: Sets the initial input (or output) position to the end of the file.
ios::app: Seeks the end of file before each write. (Included in ANSI draft.)
ios::trunc: Guarantees a fresh file; discard any contents that were previously associated with it.
ios::nocreate: Guarantees an existing file; fail if the specified file did not already exist.
ios::noreplace: Guarantees a new file; fail if the specified file already existed.
ios::bin: Opens 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]]): Opens 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.

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

Constructor: ofstream::ofstream (): Makes an ofstream associated with a new file for output.

Constructor: ofstream::ofstream (int fd): Makes 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]])

Opens a file *fname for this ofstream object.

By default, the file is opened for output (with ios::out as mode). 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]]): Opens 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 (): Closes the file associated with this object, and set ios::fail in this object to mark the event.

4.2 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]): Associates the new input string class istrstream with an existing static string starting at str, of size size. If size is not specified, the string is treated as a NUL terminated string.

Constructor: ostrstream::ostrstream (): Creates 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. Optionally specify one of the modes described for ifstream::ifstream; if no mode is specified, the new stream is simply open for output, with mode ios::out.

Method: int ostrstream::pcount (): Reports 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:If the string is to be null-terminated, the user must do it (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 the string is referred to 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 (): Tests whether freeze(1) is in effect for this string.

Method: strstreambuf* strstreambase::rdbuf (): A pointer to the underlying strstreambuf.