|Definition|| class Stream|
Stream objects represent streams of data that pass data elements between an endpoint known as a source or sink
and a consumer or producer.
Streams are full-duplex and may be stacked where intermediate streams are be used
as filters or data mutators. Example endpoints are the File, Socket, and Http classes. The TextStream is an
example of a filter stream. The data elements passed by streams may be any series of objects including: bytes,
lines of text, numbers or objects. Streams may buffer the incoming data or not. Streams may issue events to
registered observers for topics of interest. Streams may offer synchronous and asynchronous APIs.
| static const ||BOTH|| ||Both directions constant for flush(). |
| static const ||READ|| ||Read direction constant for flush(). |
| static const ||WRITE|| ||Write direction constant for flush(). |
| get set ||async||Boolean||The current async mode. Set to true if the stream is in async mode.|
Stream Class Methods
(No own class methods defined)
Stream Instance Methods
- Close the stream.
|close||A close event is issued before closing the stream.
- Flush the stream and underlying streams. A supplied flush direction argument modifies the effect of this call.
If direction is set to Stream.READ, then all read data is discarded. If direction is set to Stream.WRITE,
any buffered data is written. Stream.BOTH will cause both directions to be flushed. If the stream is in
sync mode, this call will block until all data is written. If the stream is in async mode, it will attempt
to write all data but will return immediately. Defaults to Stream.WRITE.
- Remove an observer from the stream.
|name ||Event name previously used with observe. The name may be an array of events.|
|observer: Function ||Observer function previously used with observe.|
- Add an observer to the stream for the named events.
|name: [String|Array]||Name of the event to listen for. The name may be an array of events.|
|observer: Function ||Callback observer function. The function is called with the following signature: function observer(event: String, ...args): Void.|
|readable||Issued when the stream becomes readable.
||writable||Issued when the stream becomes writable.
||close||Issued when stream is being closed. 8.
- Read a data from the stream. If data is available, the call will return immediately.
If no data is available and the stream is in sync mode, the call will block until data is available.
If no data is available and the stream is in async mode, the call will not block and will return immediately.
In this case a "readable" event will be issued when data is available for reading.
|buffer: ByteArray ||Destination byte array for read data.|
|offset: Number ||Offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer write position which is then updated. If offset is >= 0, the data is read to the offset and the read pointer is set to the offset and the write pointer to one past the end of the data just read. [default: 0]|
|count: Number ||Read up to this number of bytes. If -1, read as much as the buffer will hold up. If the stream is of fixed and known length (such as a file) and the buffer is of sufficient size or is growable, read the entire stream. If the buffer is of a fixed size, ready only what will fit into the buffer. [default: -1]|
|readable||Issued when there is new read data available.
||writable||Issued when the stream becomes empty. `.
- A count of the bytes actually read. Returns null on EOF or errors.
- Write data to the stream. If the stream can accept all the write data, the call returns immediately with the number of bytes written.
If writing more data than the stream can absorb in sync mode, the call will block until the data is written.
If writing more data than the stream can absorb in async mode, the call will not block and will buffer the
data and return immediately. Some streams will require a flush() call to actually send the data.
A "writable" event will be issued when the stream can again absorb more data.
|data: Array ||Data to write.|
|readable||Issued when data is written and a consumer can read without blocking.
||writable||Issued when the stream becomes empty and it is ready to be written to.
- A count of the bytes actually written.
IOError: if there is an I/O error.