@head @module io @title 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 @ref{std::IoError} exception. @see The module @ref{encodings} defines several useful text file encodings that can be used with @ref{TextStream} and @ref{TextFile} classes. @end

Stream classes

@link io_stream.html
This is the abstract base class of all stream classes defined in this module.
@link io_file.html
This class represents open files using raw access, i.e. no character set conversion.
@link io_textstream.html
This class can be used to wrap around raw streams to provide transparent character set conversion when reading or writing.
@link io_textfile.html
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: @var StdIn as TextStream @desc The standard input stream. @end @var StdOut as TextStream @desc The standard output stream. This stream will be line buffered if connected to a terminal, and buffered otherwise. @end @var StdErr as TextStream @desc The standard error stream. This stream is always unbuffered. @end

The standard streams are also available as raw 8-bit streams: @var RawStdIn as File @var RawStdOut as File @var RawStdErr as File @desc Raw standard streams. The buffering mode is the same as with corresponding non-raw streams. @end

Stream options

Several options can be used with Stream and File constructors. They are all symbolic constants: @var Input as Constant @desc Stream option for reading. @end @var Output as Constant @desc Stream option for writing. @end @var Append as Constant @desc 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. @end @var Unbuffered as Constant @desc Stream option for unbuffered access. The stream will be automatically flushed after every output operation and the use of an input buffer is minimized. @end @var LineBuffered as Constant @desc 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. @end @var Buffered as Constant @desc 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. @end @var Narrow as Constant @desc 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. @end @var Protected as Constant @desc File option for creating a file that can only be accessed by the current user. @end

Default encoding

The platform default encoding class: @var DefaultEncoding as encodings::Encoding @desc The default system text encoding. Its value depends on the current locale settings and the operating system. This object implements the interface @href{encodings::Encoding} described in the @ref{encodings} module. @end