Next: 3.8 External Resources
Up: 3 The Slate World
Previous: 3.6 Collections
  Contents
Subsections
Streams are objects that act as a sequential channel of elements from
(or even to) some source.
Streams respond to a number of common messages. However, many of these
only work on some of the stream types, usually according to good sense:
- next
- reads and returns the next element in the stream.
This causes the stream reader to advance one element.
- peek
- reads and returns the next element in the stream.
This does not advance the stream reader.
- next:
- draws the next n number of elements from
the stream and returns them in a Sequence of the appropriate
type.
- next:putInto:
- reads the next N elements into the given
Sequence starting from index 0.
- next:putInto:startingAt:
- reads the N elements into the
given Sequence starting from the given index.
- nextPutInto:
- reads into the given Sequence the
number of elements which will fit into it.
- nextPut:
- writes the object to the stream.
- nextPutAll:
- alias stream ; sequence
writes all the objects in the Sequence to the stream. The
; selector allows the user to cascade several sequences into
the stream as though they were concatenated.
- do:
- applies a Block to each element of the stream.
- flush
- synchronizes the total state of the stream with any
pending requests made by the user.
- atEnd
- answers whether or not the stream has reached some
limit.
- upToEnd
- collects all the elements of the stream up to its
limit into an ExtensibleSequence.
Figure
shows the major stream types
and their relationships.
Figure:
Stream Inheritance
|
- Stream
- provides the basic protocol for instantiating streams.
- ReadStream
- provides the basic protocol for input access
from a source.
- WriteStream
- provides the basic protocol for output access
to a target.
- ReadWriteStream
- provides the basic protocol for both read
and write access, and caches its input as necessary.
- PositionableStream
- extends Stream to provide a
basic protocol to iterate over a sequence of elements from a Sequence
or a file or other source. These streams store their position in the
sequence as they iterate, and are re-positionable. It also has its
own variants, -Read-, -Write-, and -ReadWrite-.
- DummyStream
- is a (singleton) ReadWriteStream that
just returns Nil repeatedly (and does nothing on writing).
It is best created by applying the reader, writer,
or iterator methods to Nil.
- EchoStream
- is a wrapper for a Stream which copies
all stream input/output interactions to another Stream for
logging purposes. It is best created by applying the echo
(goes to the Console) or echoTo: anotherStream
methods to any stream.
- Method ReadStream
- is a ReadStream that targets
a no-input block and returns its output each time. It is best created
by applying the reader or iterator method to any
block.
- Method WriteStream
- is a WriteStream that targets
a single-input block and applies its input each time. It is best created
by applying the writer method to any block.
- FilterStream
- is a ReadStream that returns the
elements of a wrapped ReadStream that satisfy the logical
test of a single-argument block being applied to each element. It
is created by applying the select: method to any Stream.
- CollectStream
- is a ReadStream that returns the
results of applying a single-argument block to each element of a ReadStream
that it wraps. It is created by applying the collect: method
to any Stream.
- BufferReadStream
- wraps another
stream with a special Buffer object for reading large chunks
from the stream at a time while handing out the elements as requested.
This also minimizes stress on the memory-allocator by avoiding unnecessary
allocation of arrays. It is created by applying the readBuffered
method to any Stream.
- BufferWriteStream
- wraps another
stream with a special Buffer object for writing large chunks
to the stream at a time while accepting new elements as requested.
This also minimizes stress on the memory-allocator by avoiding unnecessary
allocation of arrays. It is created by applying the writeBuffered
method to any Stream.
There are a number of ways to create Streams, and a large
number of implementations, so some methods exist to simplify the process
of making a new one:
- newOn:
- creates a new Stream of the same type as
the first argument, targetting it to the second as a source. This
should not be overridden. Instead, the retargetting method on:
is overridden.
- newTo:
- creates a new WriteStream of the appropriate
type on the specified target. This should be overridden for derived
types, and the first argument should apply to the generic Stream
type to allow any instance to know this protocol.
- newFrom:
- creates a new ReadStream of the appropriate
type on the specified target. This should be overridden for derived
types, and the first argument should apply to the generic Stream
type to allow any instance to know this protocol.
- buffered
- creates and returns a new BufferStream
whose type corresponds to the argument and wraps the argument Stream.
- readBuffered
- creates and returns a new ReadBufferStream
which wraps the argument Stream.
- writeBuffered
- creates and returns a new WriteBufferStream
which wraps the argument Stream.
- echoTo:
- creates and returns a new EchoStream which
wraps the first argument Stream and echoes to the second.
- echo
- creates and returns a new EchoStream to the
Console.
Each type (typically a collection) often defines its own Stream
type which goes over its elements in series, even if the collection
is not ordered, and only visits each element once. This type's prototype
is accessed via the slot ReadStream within each collection
(usually located on its traits object). So ``Set ReadStream''
refers to the prototype suitable for iterating over Sets.
In order to create a new iterator for a specific collection, the iterator
message is provided, which clones the prototype for that collection's
type and targets it to the receiver of the message. The protocol summary:
- iterator
- will return a ReadStream or preferably
a ReadWriteStream if one is available for the type.
- reader
- and writer get streams with only
ReadStream and WriteStream capabilities for the
type, when available.
The stream capabilities supported for each basic collection type are
usually limited by the behavior that the type supports. The capabilities
per basic type are as follows; types not mentioned inherit or specialize
the capabilities of their ancestors:
Type |
Capabilities
Collection |
Next: 3.8 External Resources
Up: 3 The Slate World
Previous: 3.6 Collections
  Contents
The Slate Project
2004-01-04