@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