The GNU C++ Iostream Library - 4. Classes for Files and Strings

Go to the first, previous, next, last section, table of contents.

# 4. 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.

## 4.1 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.

## 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])
  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`.

Go to the first, previous, next, last section, table of contents.