Next: 3.8 External Resources
Up: 3 The Slate World
Previous: 3.6 Collections
Contents
Index
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 answers the next
element in the stream. This causes the stream reader to advance one
element.
- peek
- reads and answers 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 delivers 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.
- isAtEnd
- 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.
- contents
- answers a collection
of the output of the argument WriteStream.
Figure
2 shows the major stream types and their
relationships.
Figure 2:
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.
- PeekableStream
- extends
Stream to provide the ability to look forward on the stream
without advancing it.
- PositionableStream
- extends
PeekableStream 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 answers 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. It answers
the original stream, so that further processing can be chained.
- 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.
- StreamProcessor
- is an
abstract kind of ReadStream that has a source ReadStream
which it processes in some way. Derivatives specialize it in various
useful ways.
- FilterStream
- is
a StreamProcessor 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: or reject: method to any Stream.
- CollectStream
- is a StreamProcessor
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, targeting it to the second
as a source. This should not be overridden. Instead, the re-targeting
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.
- >>
- performs a looping
iterative transfer of all elements of the first stream to the second.
The second argument may be any WriteStream, or a StreamProcessor,
or a single-argument Method in which case it has the same
semantics as collect:. For targets to ExternalResources,
it will perform a buffered transfer. This method always returns the
target stream so that the results may be further processed.
Mirroring the collection protocols, streams support a mirror of that
interface (do:, select:, collect:, reject:).
The difference is that where collections would answer other collections,
streams return corresponding streams.
Many
types (typically collections) define their 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
(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 |
none |
ExtensibleCollection |
Write |
Bag |
Read and Write separately |
Sequence |
Positionables (R, W, RW); copy for extension |
ExtensibleSequence |
Positionables (R, W, RW) |
Next: 3.8 External Resources
Up: 3 The Slate World
Previous: 3.6 Collections
Contents
Index
Brian Rice
2004-10-30