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

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

Standard streams

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

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

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

RawStdIn as File
RawStdOut as File
RawStdErr as File
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 as Constant
Stream option for reading.
Output as Constant
Stream option for writing.
Append as Constant
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 as Constant
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 as Constant
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 as Constant
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 as Constant
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 as Constant
File option for creating a file that can only be accessed by the current user.

Default encoding

The platform default encoding class:

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