Module io
This module implements the Stream/TextStream classes as per the CommonJS IO/A proposal.
Class MemoryStream
Instance Methods
- close()
- closed()
- flush()
- read(maxBytes)
- readInto(buffer, begin, end)
- readable()
- seekable()
- writable()
- write(source, begin, end)
Instance Properties
MemoryStream (binaryOrNumber)
A binary stream that reads from and/or writes to an in-memory byte array.
If the constructor is called with a Number argument, a ByteArray with the given length is allocated and the length of the stream is set to zero.
If the argument is a [binary object][binary] it will be used as underlying buffer and the stream length set to the length of the binary object. If argument is a [ByteArray][binary#ByteArray], the resulting stream is both readable, writable, and seekable. If it is a [ByteString][binary#ByteString], the resulting stream is readable and seekable but not writable.
If called without argument, a ByteArray of length 1024 is allocated as buffer.
Parameters
| Binary|Number | binaryOrNumber | the buffer to use, or the initial capacity of the buffer to allocate. |
MemoryStream.prototype. close ()
Closes the stream, freeing the resources it is holding.
MemoryStream.prototype. closed ()
Returns true if the stream is closed, false otherwise.
Returns
| Boolean | true if the stream has been closed |
MemoryStream.prototype. content
The wrapped buffer.
MemoryStream.prototype. flush ()
Flushes the bytes written to the stream to the underlying medium.
MemoryStream.prototype. length
The number of bytes in the stream's underlying buffer.
MemoryStream.prototype. position
The current position of this stream in the wrapped buffer.
MemoryStream.prototype. read (maxBytes)
Read up to maxBytes bytes from the stream, or until the end of the stream
has been reached. If maxBytes is not specified, the full stream is read
until its end is reached. Reading from a stream where the end has already been
reached returns an empty ByteString.
Parameters
| Number | maxBytes | the maximum number of bytes to read |
Returns
| ByteString |
MemoryStream.prototype. readInto (buffer, begin, end)
Read bytes from this stream into the given buffer. This method does not increase the length of the buffer.
Parameters
| ByteArray | buffer | the buffer |
| Number | begin | optional begin index, defaults to 0. |
| Number | end | optional end index, defaults to buffer.length - 1. |
Returns
| Number | The number of bytes read or -1 if the end of the stream has been reached |
MemoryStream.prototype. readable ()
Returns true if the stream supports reading, false otherwise. Always returns true for MemoryStreams.
Returns
| Boolean | true if stream is readable |
MemoryStream.prototype. seekable ()
Returns true if the stream is randomly accessible and supports the length and position properties, false otherwise. Always returns true for MemoryStreams.
Returns
| Boolean | true if stream is seekable |
MemoryStream.prototype. writable ()
Returns true if the stream supports writing, false otherwise. For MemoryStreams this returns true if the wrapped binary is an instance of ByteArray.
Returns
| Boolean | true if stream is writable |
MemoryStream.prototype. write (source, begin, end)
Write bytes from b to this stream. If begin and end are specified, only the range starting at begin and ending before end is written.
Parameters
| Binary | source | The source to be written from |
| Number | begin | optional |
| Number | end | optional |
Stream ()
This class implements an I/O stream used to read and write raw bytes.
Stream.prototype. close ()
Closes the stream, freeing the resources it is holding.
Stream.prototype. closed ()
Returns true if the stream has been closed, false otherwise.
Returns
| Boolean | true if the stream has been closed |
Stream.prototype. copy (output)
Reads all data available from this stream and writes the result to the given output stream, flushing afterwards. Note that this function does not close this stream or the output stream after copying.
Parameters
| Stream | output | The target Stream to be written to. |
Stream.prototype. flush ()
Flushes the bytes written to the stream to the underlying medium.
Stream.prototype. forEach (fn, [thisObj])
Read all data from this stream and invoke function fn for each chunk of data read.
The callback function is called with a ByteArray as single argument. Note that
the stream is not closed after reading.
Parameters
| Function | fn | the callback function |
| Object | [thisObj] | optional this-object to use for callback |
Stream.prototype. inputStream
The wrapped java.io.InputStream.
Stream.prototype. outputStream
The wrapped java.io.OutputStream.
Stream.prototype. read (maxBytes)
Read up to maxBytes bytes from the stream, or until the end of the stream
has been reached. If maxBytes is not specified, the full stream is read
until its end is reached. Reading from a stream where the end has already been
reached returns an empty ByteString.
Parameters
| Number | maxBytes | the maximum number of bytes to read |
Returns
| ByteString |
Stream.prototype. readInto (buffer, begin, end)
Read bytes from this stream into the given buffer. This method does not increase the length of the buffer.
Parameters
| ByteArray | buffer | the buffer |
| Number | begin | optional begin index, defaults to 0. |
| Number | end | optional end index, defaults to buffer.length - 1. |
Returns
| Number | The number of bytes read or -1 if the end of the stream has been reached |
Stream.prototype. readable ()
Returns true if the stream supports reading, false otherwise.
Returns
| Boolean | true if stream is readable |
Stream.prototype. seekable ()
Returns true if the stream is randomly accessible and supports the length and position properties, false otherwise.
Returns
| Boolean | true if stream is seekable |
Stream.prototype. skip (num)
Try to skip over num bytes in the stream. Returns the number of acutal bytes skipped or throws an error if the operation could not be completed.
Parameters
| Number | num | bytes to skip |
Returns
| Number | actual bytes skipped |
Stream.prototype. unwrap ()
Get the Java input or output stream instance wrapped by this Stream.
Stream.prototype. writable ()
Returns true if the stream supports writing, false otherwise.
Returns
| Boolean | true if stream is writable |
Stream.prototype. write (source, begin, end)
Write bytes from b to this stream. If begin and end are specified, only the range starting at begin and ending before end is written.
Parameters
| Binary | source | The source to be written from |
| Number | begin | optional |
| Number | end | optional |
TextStream (io, options, buflen)
A TextStream implements an I/O stream used to read and write strings. It wraps a raw Stream and exposes a similar interface.
Parameters
| Stream | io | The raw Stream to be wrapped. |
| Object | options | the options object. Supports the following properties:
|
| number | buflen | optional buffer size. Defaults to 8192. |
TextStream.prototype. content
If the wrapped stream is a [MemoryStream][#MemoryStream] this contains its content decoded to a String with this streams encoding. Otherwise contains an empty String.
TextStream.prototype. copy (output)
Reads from this stream with [readLine][#readLine], writing the results to the target stream and flushing, until the end of this stream is reached.
Parameters
| null | output |
TextStream.prototype. forEach (callback, [thisObj])
Calls callback with each line in the input stream.
Parameters
| Function | callback | the callback function |
| Object | [thisObj] | optional this-object to use for callback |
TextStream.prototype. next ()
Returns the next line of input without the newline. Throws
StopIteration if the end of the stream is reached.
Returns
| String | the next line |
TextStream.prototype. print ()
Writes all argument values as a single line, delimiting the values using a single blank.
TextStream.prototype. raw
The wrapped binary stream.
TextStream.prototype. read ()
Read the full stream until the end is reached and return the data read as string.
Returns
| String |
TextStream.prototype. readInto (buffer)
Not implemented for TextStraim. Calling this method will raise an error.
Parameters
| null | buffer |
TextStream.prototype. readLine ()
Reads a line from this stream. If the end of the stream is reached before any data is gathered, returns an empty string. Otherwise, returns the line including the newline.
Returns
| String | the next line |
TextStream.prototype. readLines ()
Returns an Array of Strings, accumulated by calling readLine until it
returns an empty string. The returned array does not include the final
empty string, but it does include a trailing newline at the end of every
line.
Returns
| Array | an array of lines |
TextStream.prototype. seekable ()
Always returns false, as a TextStream is not randomly accessible.
TextStream.prototype. write ()
Writes all arguments to the stream.
TextStream.prototype. writeLine (line)
Writes the given line to the stream, followed by a newline.
Parameters
| null | line |
TextStream.prototype. writeLines (lines)
Writes the given lines to the stream, terminating each line with a newline.
This is a non-standard extension, not part of CommonJS IO/A.
Parameters
| null | lines |