@head @module io @title Class io::TextStream @index TextStream @inherits Stream @supertypes
The TextStream class represents an encoded text stream. @see The @ref{encodings} module defines several encoding classes. @end @class TextStream(stream as Stream[, encoding as Encoding], ... as Constant) @desc Construct an encoded text stream. The stream argument should conform to the @ref{Stream} interface. It is used for reading and writing the encoded (narrow) text data, i.e. the TextStream object wraps this stream. This class is typically used for reading and writing Unicode text using narrow (8-bit) streams. If the encoding is not specified, the encoding will be @ref{DefaultEncoding}.
The optional arguments may include a buffering argument that defines the buffering mode (@ref{Buffered}, @ref{LineBuffered} or @ref{Unbuffered}) and either @ref{encodings::Strict} or @ref{encodings::Unstrict}. The default options are Buffered and Strict.
All input and output operations return and expect Unicode encoded strings. If an attempt is made to write a character that cannot be represented by the stream encoding, an @ref{encodings::EncodeError} exception will be raised. @note When using buffering, reporting of encoding errors may be delayed. Errors are reported only when the buffer is actually written to the wrapped stream. @end @end @h2 TextStream methods
TextStream does not define any additional methods over those inherited from @ref{Stream}. A single method has a significantly different behavior in TextStream than in Stream: @fun close() @desc Close the stream by flushing the output buffers and closing the wrapped stream. Any stream operations other than close made to a closed TextStream object will fail. @end