io: Basic file access

This module provides facilities for reading, creating, and writing files. The Stream class is also used as a base class for other file-like objects such as network connections.

Streams support both character and line based input and output. All of the following line endings are accepted when reading lines:

Line based output uses the native line ending of the platform (CR+LF on Windows, LF on Unix-like operating systems).

All file operations and some stream operations may raise a std::IoError exception.

See also: The module encodings defines several useful text file encodings that can be used with TextStream and TextFile classes.

Stream classes

File
This class represents open files using raw access, i.e. no character set conversion.
TextFile
This class represents open text files with a particular character encoding.
Stream
This is the abstract base class of all stream classes defined in this module.
TextStream
This class can be used to wrap around raw streams to provide transparent character set conversion when reading or writing.

Standard streams

The following constants refer to standard streams. They are available as text stream objects using the platform default encoding:

StdIn
The standard input stream.
StdOut
The standard output stream. This stream will be line buffered if connected to a terminal, and buffered otherwise.
StdErr
The standard error stream. This stream is always unbuffered.

The standard streams are also available as raw 8-bit streams:

RawStdIn
RawStdOut
RawStdErr
Raw standard streams. The buffering mode is the same as with corresponding non-raw streams.

Stream options

Several options can be used with Stream and File constructors. They are all symbolic constants:

Input
Stream option for reading.
Output
Stream option for writing.
Append
File option for opening a file for writing. The existing file contents will be kept and the file pointer will be moved to the end of the file when the file is opened.
Unbuffered
Stream option for unbuffered access. The stream will be automatically flushed after every output operation and the use of an input buffer is minimized.
LineBuffered
Stream option for line buffered access. The stream will be automatically flushed after writing a line break. The output and input buffer sizes will be small.
Buffered
Stream option for fully buffered access. All stream input and output operations will be buffered. The flush method (or the close method) must be called after a set of write operations.
Narrow
Stream option for creating a narrow stream. Narrow streams only process 8-bit (narrow) strings, i.e. strings with no character codes larger than 255.
Protected
File option for creating a file that can only be accessed by the current user.

Default encoding

The platform default encoding class:

DefaultEncoding
The default system text encoding. Its value depends on the current locale settings and the operating system. This object implements the Character encoding interface described in the encodings module.