@head @module io @title Class io::Stream @index Stream @implements Iterable @supertypes

The Stream class represents a generic stream of character data. Stream provides a high-level buffered interface for reading and writing strings, but does not implement the actual writing or reading. Stream subclasses must provide _write and/or _read methods for actually processing data. @class Stream(... as Constant) @desc Construct a Stream object. The arguments may include some of the options @ref{Input} and @ref{Output} (Input is the default if none are specified), and one of the buffering options @ref{Buffered}, @ref{LineBuffered} or @ref{Unbuffered} (buffering is enabled by default). Finally, the arguments may include @ref{Narrow} to indicate a narrow (8-bit) stream that only accepts character codes less than 256. By default, any 16-bit character codes are supported. @end

Stream methods

@fun write(...) @desc Write the arguments to the stream. Non-string arguments will be first converted to strings using the @ref{std::Str} constructor. @end @fun writeLn(...) @desc Write the arguments to the stream, followed by a line break. Non-string arguments will be first converted to strings using the @ref{std::Str} constructor. @end @fun read() as Str @desc Read the rest of the stream contents, until reaching the end of the stream. Close the stream and return the contents that were read. Return an empty string at the end of stream. @end @fun read(size as Int) as Str @desc Read up to the specified number of characters from the stream and return them as a string. Read less than size characters only if the end of stream was encountered. @end @fun readLn() as Str @desc Read a line from the stream, and return the line without the line ending. Raise @ref{IoError} if called at the end of stream. @end @fun readLines() as Array @desc Read the rest of the stream as lines, close the stream and return an array containing the lines. Line endings are not included in the lines. The stream will be closed even if there is an IO error. @end @fun flush() @desc Flush the output buffer of the stream by writing its contents. If the buffer is empty or does not exist, do nothing. This method can only be used on streams that support writing. @end @fun eof() as Boolean @desc Return a boolean indicating whether there are any characters left in the stream before the end of stream. This method can only be used on streams that support reading. @end @fun close() @desc Close the stream by flushing the output buffers. Subclasses of Stream should also release any operating system resources that might be allocated for the object. Any stream operations other than close made to a closed stream object will fail. Calling close on a closed stream does nothing. @end @fun peek() as Str @desc Return the contents of the input buffer as a string. If the input buffer is empty or does not exist, return an empty string. This method can only be used on streams that support reading. @end @fun iterator() as Iterator @desc Return an iterator that iterates over all the lines in the stream. Line endings are not included in the lines. @end

Stream operations

@op for line in stream @desc The lines in a stream can be enumerated with a for loop. Line endings are not included in the lines. @end

Stream subclass methods

At least one of these methods must be provided by subclasses of Stream (_write for output streams and _read for input streams). Stream does not implement these and therefore is an abstract class. @fun _write(...) @desc Write the arguments directly to the stream without buffering. The arguments are strings. @end @fun _read(size as Int) as Str @desc Read up to the specified number of characters from the stream, directly without buffering. Return nil if at the end of the stream. @end @end-class