ByteArray

Module	ejs
Definition	final class ByteArray
Inheritance	ByteArray Object
Specified	ejscript-2.5
Stability	Evolving.

ByteArrays provide a resizable, integer indexed, in-memory store for bytes.

ByteArrays can be used as a simple array type to store and encode data as bytes or they can be used as buffered loop-back Streams.

When used as a simple byte array, the ByteArray class offers a low level set of methods to insert and extract bytes. The index operator [] can be used to access individual bytes and the copyIn and copyOut methods can be used to get and put blocks of data. In this mode, the readPosition and writePosition properties are ignored.

Access to the byte array is from index zero up to the size defined by the size property. When constructed, the ByteArray can be designated as resizable, in which case the initial size will grow as required to accomodate data and the size property will be updated accordingly.

ByteArrays provide additional write methods to store data at the location specified by the writePosition property and read methods to read from the readPosition property. The length property indicates how much data is available between the read and write position pointers. The reset method can reset the pointers to the start of the array. When used with for/in, ByteArrays will iterate or enumerate over the available data between the read and write pointers.

If numeric values are read or written, they will be coded according to the value of the endian property which can be set to either LittleEndian or BigEndian. If strings values are read or written, they will be encoded according to the value of the character set encoding property.

When used as loop-back streams, data written to ByteArrays is immediately available for reading. ByteArrays can be run in sync or async mode. ByteArrays will issue events for key state transitions such as close, EOF, readable and writable events. All event observers are called with the following signature: function callback(event: String, ba: ByteArray): Void.

Properties

Qualifiers	Property	Type	Description
static const	BigEndian	Number	Big endian byte order used for the endian property.
static const	LittleEndian	Number	Little endian byte order used for the endian property 0.
get	MD5	String	An MD5 checksum for the buffer contents (.
get set	async	Boolean	The current async mode. Set to true if the stream is in async mode.
get set	encoding	String	Current encoding scheme for serializing strings. The default encoding is "utf-8". Set to "" for no encoding. If no encoding, string character points are stored as a pairs of two byte in little-endian format.
get set	endian	Number	Current byte ordering for storing and retrieving numbers. Set to either LittleEndian or BigEndian.
get	length	Number	Number of bytes that are currently available for reading. This consists of the bytes available from the current readPosition up to the current writePosition. To get the total size of the ByteArray use size.
get set	readPosition	Number	Current read position offset.
get	resizable	Boolean	Is the ByteArray is resizable.
get	room	Number	Number of data bytes that the array can store from the writePosition till the end of the array.
get	size	Number	Size of the byte array. This is not the amount of read or write data, but is the size of the total array storage. Use length to get the amount of data between the read and write positions.
get set	writePosition	Number	Current writePosition offset. 8.

Inherited Properties

ByteArray Class Methods

(No own class methods defined)

Qualifiers	Method

Inherited Methods

ByteArray Instance Methods

Qualifiers	Method
	ByteArray(size: Number = -1, resizable: Boolean = true)
	Create a new array.
	close(): Void
	Close the stream.
	compact(): Void
	Compact available data down and adjust the read/write positions accordingly.
	copyIn(destOffset: Number, src: ByteArray, srcOffset: Number = 0, count: Number = -1): Number
	Copy data into the array.
	copyOut(srcOffset: Number, dest: ByteArray, destOffset: Number = 0, count: Number = -1): Number
	Copy data from the array.
	flush(dir: Number = expression): Void
	Flush (discard) the data in the byte array and reset the read and write positions.
iterator override	get(): Iterator
	Iterator for this array to be used by "for (v in array)".
iterator override	getValues(): Iterator
	Iterator for this array to be used by "for each (v in array)".
	off(name: Object, observer: Function): Void
	Remove an observer from the stream.
	on(name: Object, observer: Function): ByteArray
	Add an observer to the stream for the named events.H.
	read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number
	Read a data from the stream.Data is read from the current read position pointer toward the current writePosition.
	readBoolean(): Boolean
	Read a boolean from the array.
	readByte(): Number
	Read a byte from the array.
	readDate(): Date
	Read a date from the array.
	readDouble(): Number
	Read a double from the array.
	readInteger(): Number
	Read an 32-bit integer from the array.
	readLong(): Number
	Read a 64-bit long from the array.The data will be decoded according to the endian property.
	readShort(): Number
	Read a 16-bit short integer from the array.The data will be decoded according to the endian property.
	readString(count: Number = -1): String
	Read a data from the array as a string.
	readXML(): XML
	Read an XML document from the array.
	reset(): Void
	Reset the read and writePosition pointers if there is no available data.
override	toString(): String
	Convert the data in the byte array between the readPosition and writePosition.
	write(data: Array): Number
	Write data to the stream.Write data to the ByteArray.
	writeByte(data: Number): Void
	Write a byte to the array.
	writeDouble(data: Number): Void
	Write a double to the array.
	writeInteger(data: Number): Void
	Write a 32-bit integer to the array.
	writeLong(data: Number): Void
	Write a 64 bit long integer to the array.
	writeShort(data: Number): Void
	Write a short to the array.

Inherited Methods

Method Detail

ByteArray(size: Number = -1, resizable: Boolean = true)

Description: Create a new array.

Parameters

size: Number	The initial size of the byte array. If not supplied a default buffer size will be used which is typically 4K or larger. [default: -1]
resizable: Boolean	Set to true to automatically grow the array as required to fit written data. [default: true]

close(): Void

Description: Close the stream.

Events

A close event is issued before closing the stream.

compact(): Void

Description: Compact available data down and adjust the read/write positions accordingly. This sets the read pointer to the zero index and adjusts the write pointer by the corresponding amount.

copyIn(destOffset: Number, src: ByteArray, srcOffset: Number = 0, count: Number = -1): Number

Description: Copy data into the array. This is a low-level data copy routine that does not update read and write positions. Data is written at the destOffset index. This call does not issue events unless required to make room for the incoming data ("readable" event).

Parameters

destOffset: Number	Index in the destination byte array to copy the data to.
src: ByteArray	Source byte array containing the data elements to copy.
srcOffset: Number	Location in the source buffer from which to copy the data. Defaults to the start. [default: 0]
count: Number	Number of bytes to copy. Set to -1 to read all the src buffer. [default: -1]

Returns: The number of bytes written into the array. If the array is not resizable and there is insufficient room, this may be less than the requested amount.

copyOut(srcOffset: Number, dest: ByteArray, destOffset: Number = 0, count: Number = -1): Number

Description: Copy data from the array. Data is copied from the srcOffset pointer. This call does not update the read and write positions. This call does not issue events.

Parameters

srcOffset: Number	Location in the source array from which to copy data.
dest: ByteArray	Destination byte array.
destOffset: Number	Location in the destination array to copy the data. Defaults to the start. [default: 0]
count: Number	Number of bytes to read. Set to -1 to read all available data. [default: -1]

Returns: The count of bytes read. Returns null on EOF.

flush(dir: Number = expression): Void

Description: Flush (discard) the data in the byte array and reset the read and write positions. This call may block if the stream is in sync mode.

Parameters

dir: Number

The dir parameter is Ignored. Flushing a ByteArray in either direction the same effect of discarding all buffered data and resetting the read and write positions -- so this argument is ignored. [default: expression]

override iterator get(): Iterator

Description: Iterator for this array to be used by "for (v in array)". This will return array indicies.

override iterator getValues(): Iterator

Description: Iterator for this array to be used by "for each (v in array)". This will return read data in the array.

off(name: Object, observer: Function): Void

Description: Remove an observer from the stream.

Parameters

name: Object	Event name previously used with observe. The name may be an array of events.
observer: Function	Observer function previously used with observe.

on(name: Object, observer: Function): ByteArray

Description: Add an observer to the stream for the named events.H.

Parameters

name: Object	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.

Events

readable	Issued when the stream becomes readable.
writable	Issued when the stream becomes writable.
close	Issued when stream is being closed. 8.

read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number

Description: Read a data from the stream.Data is read from the current read position pointer toward the current writePosition. 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.This byte array's readPosition is updated. If offset is < 0, then data is copied to the destination buffer's writePosition and the destination buffer's writePosition is also updated. If the offset is >= 0, the read position is set to the specified offset and data is stored at this offset. The write position is set to one past the last byte read.

Parameters

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]

Events

readable	Issued when there is new read data available.
writable	Issued when the stream becomes empty. `.

Returns: A count of the bytes actually read. Returns null on EOF or errors.

readBoolean(): Boolean

Description: Read a boolean from the array. Data is read from the current read position pointer. If insufficient data, a "writable" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF.

Returns: A boolean or null on EOF.

Throws: IOError: if an I/O error occurs or premature EOF.

readByte(): Number

Description: Read a byte from the array. Data is read from the current read position pointer. If insufficient data, a "write" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF.

Throws: IOError: if an I/O error occurs or premature EOF.

readDate(): Date

Description: Read a date from the array. Data is read from the current read position pointer. If insufficient data, a "write" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF.

Throws: IOError: if an I/O error occurs or premature EOF.

readDouble(): Number

Description: Read a double from the array. The data will be decoded according to the endian property. Data is read from the current read position pointer. If insufficient data, a "write" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF.

Returns: A double or null on EOF.

Throws: IOError: if an I/O error occurs or premature EOF.

readInteger(): Number

Description: Read an 32-bit integer from the array. The data will be decoded according to the endian property. Data is read from the current read position pointer. If insufficient data, a "write" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF.

Throws: IOError: if an I/O error occurs or premature EOF.

readLong(): Number

Description: Read a 64-bit long from the array.The data will be decoded according to the endian property. Data is read from the current read position pointer. If insufficient data, a "write" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF.

Throws: IOError: if an I/O error occurs or premature EOF. 0

readShort(): Number

Description: Read a 16-bit short integer from the array.The data will be decoded according to the endian property. Data is read from the current read position pointer. If insufficient data, a "write" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF. If there is insufficient data.

Returns: A short int or null on EOF.

Throws: IOError: if an I/O error occurs or premature EOF.

readString(count: Number = -1): String

Description: Read a data from the array as a string. Read data from the readPosition to a string up to the writePosition, but not more than count characters. If insufficient data, a "writable" event will be issued indicating that the byte array is writable. This enables observers to write data into the byte array. If there is no data available, the call will return return null indicating EOF. If there is insufficient data.

Parameters

count: Number

Of bytes to read. If -1, convert the data up to the writePosition. [default: -1]

Returns: A string or null on EOF.

Throws: IOError: if an I/O error occurs or a premature EOF.

readXML(): XML

Description: Read an XML document from the array. Data is read from the current read position pointer.

Returns: An XML document.

Throws: IOError: if an I/O error occurs or a premature end of file.

reset(): Void

Description: Reset the read and writePosition pointers if there is no available data. This is used to rewind the read/write pointers to maximize available buffer space.

override toString(): String

Description: Convert the data in the byte array between the readPosition and writePosition.

Returns: A string.

write(data: Array): Number

Description: Write data to the stream.Write data to the ByteArray. 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 is written to the current writePosition. If the data argument is itself a ByteArray, the available data from the byte array will be copied, ie. the data byte array will not have its readPosition adjusted. If the byte array is resizable, the underlying data storage will grow to accomodate written data. If the data will not fit in the ByteArray, the call may return having only written a portion of the data. When strings are written, they are not null terminated. 0

Parameters

data: Array

Data to write.

Events

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.

Returns: A count of the bytes actually written.

Throws: IOError: if there is an I/O error.

writeByte(data: Number): Void

Description: Write a byte to the array. Data is written to the current write position pointer which is then incremented. See write for details about sync, async modes and event handling.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

Throws: IOError: if an I/O error occurs or if the stream cannot absorb all the data.

writeDouble(data: Number): Void

Description: Write a double to the array. Data is written to the current write position pointer which is then incremented. See write for details about sync, async modes and event handling.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

Throws: IOError: if an I/O error occurs or if the stream cannot absorb all the data.

writeInteger(data: Number): Void

Description: Write a 32-bit integer to the array. Data is written to the current write position pointer which is then incremented. See write for details about sync, async modes and event handling.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

Throws: IOError: if an I/O error occurs or if the stream cannot absorb all the data.

writeLong(data: Number): Void

Description: Write a 64 bit long integer to the array. Data is written to the current write position pointer which is then incremented. See write for details about sync, async modes and event handling.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

Throws: IOError: if an I/O error occurs or if the stream cannot absorb all the data.

writeShort(data: Number): Void

Description: Write a short to the array. Data is written to the current write position pointer which is then incremented. See write for details about sync, async modes and event handling.

Parameters

data: Number

Data to write.

Events

readable

Issued when data is written and a consumer can read without blocking.

Throws: IOError: if an I/O error occurs or if the stream cannot absorb all the data.