@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
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
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
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