Module io

This module provides functions for reading and writing streams of raw bytes. It implements the Stream and TextStream classes as per the CommonJS IO/A proposal.

Streams are closely related with two other modules. Low-level byte manipulation is provided by the binary module and uses the ByteArray or ByteString class. The fs module returns io streams for reading and writing files.

Class MemoryStream

Instance Methods

close()
closed()
flush()
read(maxBytes)
readInto(buffer, begin, end)
readable()
seekable()
writable()
write(source, begin, end)

Class Stream

Instance Methods

close()
closed()
copy(output)
flush()
forEach(fn, [thisObj])
read(maxBytes)
readInto(buffer, begin, end)
readable()
seekable()
skip(num)
unwrap()
writable()
write(source, begin, end)

Instance Properties

inputStream
outputStream

Class TextStream

Instance Methods

close()
copy(output)
flush()
forEach(callback, [thisObj])
iterator()
next()
print()
read()
readInto()
readLine()
readLines()
readable()
seekable()
writable()
write()
writeLine(line)
writeLines(lines)

Instance Properties

content
raw

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 it will be used as underlying buffer and the stream length set to the length of the binary object. If argument is a ByteArray, the resulting stream is both readable, writable, and seekable. If it is a 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

See

Stream.prototype.read

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

See

Stream.prototype.readInto

MemoryStream.prototype. readable ()

Returns true if the stream supports reading, false otherwise. Always returns true for MemoryStreams.

Returns

Boolean

true if stream is readable

See

Stream.prototype.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

See

Stream.prototype.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

See

Stream.prototype.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

See

Stream.prototype.write

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)

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

The raw Stream to be wrapped.

Object

options

the options object. Supports the following properties:

charset: string containing the name of the encoding to use. Defaults to "utf8".
newline: string containing the newline character sequence to use in writeLine() and writeLines(). Defaults to "\n".
delimiter: string containing the delimiter to use in print(). Defaults to " ".

Number

buflen

optional buffer size. Defaults to 8192.

TextStream.prototype. close ()

See

Stream.prototype.close

TextStream.prototype. content

If the wrapped stream is a 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, writing the results to the target stream and flushing, until the end of this stream is reached.

Parameters

Stream output

Returns

TextStream

this stream

TextStream.prototype. flush ()

See

Stream.prototype.flush

TextStream.prototype. forEach (callback, [thisObj])

Calls callback with each line in the input stream.

Example

const txtStream = fs.open('./browserStats.csv', 'r');
txtStream.forEach(function(line) {
  console.log(line); // Print one single line
});

Parameters

Function	callback	the callback function
Object	[thisObj]	optional this-object to use for callback

TextStream.prototype. iterator ()

Returns this stream.

Returns

TextStream

this stream

TextStream.prototype. next ()

Returns the next line of input without the newline. Throws StopIteration if the end of the stream is reached.

Example

const fs = require('fs');
const txtStream = fs.open('./browserStats.csv', 'r');
try {
  while (true) {
     console.log(txtStream.next());
  }
} catch (e) {
  console.log("EOF");
}

Returns

String

the next line

TextStream.prototype. print ()

Writes all argument values as a single line, delimiting the values using a single blank.

Example

>> const fs = require('fs');
>> const txtOutStream = fs.open('./demo.txt', 'w');
>> txtOutStream.print('foo', 'bar', 'baz');

// demo.txt content:
foo bar baz

Returns

TextStream

this stream

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 ()

Not implemented for TextStream. Calling this method will raise an error.

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 only the newline character. Carriage return will be dropped.

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.

Example

>> const fs = require('fs');
>> const txtStream = fs.open('./sampleData.csv', 'r');
>> const lines = txtStream.readLines();
>> console.log(lines.length + ' lines');
6628 lines

Returns

Array

an array of lines

TextStream.prototype. readable ()

See

Stream.prototype.readable

TextStream.prototype. seekable ()

Always returns false, as a TextStream is not randomly accessible.

TextStream.prototype. writable ()

See

Stream.prototype.writable

TextStream.prototype. write ()

Writes all arguments to the stream.

Example

>> const fs = require('fs');
>> const txtOutStream = fs.open('./demo.txt', 'w');
>> txtOutStream.write('foo', 'bar', 'baz');

// demo.txt content:
foobarbaz

Returns

TextStream

this stream

TextStream.prototype. writeLine (line)

Writes the given line to the stream, followed by a newline.

Parameters

String line

Returns

TextStream

this stream

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

Array lines

Returns

TextStream

this stream

main

• Overview • Module Index