ByteArray

Module	ejs
Namespace	intrinsic
Definition	final class ByteArray
Inheritance	ByteArray Object

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

ByteArrays are a powerful data type that can be used as a simple array to store and encode data as bytes or it can be used as a Stream implementing the Stream interface. 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 read and write position properties are ignored. Accesses to the byte array are from index zero up to the size defined by the length property. When constructed, the ByteArray can be designated as growable, in which case the initial size will grow as required to accomodate data and the length property will be updated accordingly. When used as a Stream, the byte array offers various read and write methods which store data at the location specified by the write position property and they read data from the read position. The available method indicates how much data is available between the read and write position pointers. The flush method will reset the pointers to the start of the array. The length property is unchanged in behavior from when used as a simple byte array and it specifies the overall storage capacity of the byte array. As numeric values are read or written, they will be encoded according to the value of the endian property which can be set to either LittleEndian or BigEndian. When used with for/in, ByteArrays will iterate or enumerate over the available data between the read and write pointers. In Stream mode ByteArrays can be configured with input and output callbacks to provide or consume data to other streams or components. These callbacks will automatically be invoked as required when the various read/write methods are called.

Properties

Qualifiers	Property	Type	Description
public const	BigEndian	Number
public const	LittleEndian	Number	Numeric byte order constants used for the endian property.

ByteArray Methods

Qualifiers	Method
public get	available(): Number
	Get the number of bytes that are currently available for reading from the current read position.
	ByteArray(size: Number, growable: Boolean)
	Create a new array.
public	close(graceful: Boolean): Void
	Close the byte array.
public	copyIn(destOffset: Number, src: ByteArray, srcOffset: Number, count: Number): Void
	Copy data into the array.
public	copyOut(srcOffset: Number, dest: ByteArray, destOffset: Number, count: Number): Number
	Copy data from the array.
public get	endian(): Number
	Determine if the system is using little endian byte ordering.
public set	endian(value: Number): Void
	Set the system encoding to little or big endian.
public	flush(): Void
	Flush the the byte array and reset the read and write position pointers.
iterator override	get(deep: Boolean): Iterator
	Get an iterator for this array to be used by "for (v in array)".
iterator override	getValues(deep: Boolean): Iterator
	Get an iterator for this array to be used by "for each (v in array)".
public set	input(value: Function): Void
	Input callback function when read data is required.
public get	input(): Function
public get	length(): Number
	Get the length of an array.
public set	output(callback: Function): Void
	Define an output function to process (output) data.
public get	output(): Function
public	read(buffer: ByteArray, offset: Number, count: Number): Number
	Read data from the array into another byte array.
public	readBoolean(): Boolean
	Read a boolean from the array.
public	readByte(): Number
	Read a byte from the array.
public	readDate(): Date
	Read a date from the array or a premature end of file.
public	readDouble(): Date
	Read a double from the array.
public	readInteger(): Number
	Read an 32-bit integer from the array.
public	readLong(): Number
	Read a 64-bit long from the array.
public get	readPosition(): Number
	Return the current read position offset.
public set	readPosition(position: Number): Void
	Set the current read position offset.
public	readShort(): Number
	Read a 16-bit short integer from the array.
public	readString(count: Number): String
	Read a data from the array as a string.
public	readXML(): XML
	Read an XML document from the array.
public	reset(): Void
	Reset the read and write position pointers if there is no available data.
public get	room(): Number
	Get the number of data bytes that the array can store from the write position till the end of the array.
public override	toString(locale: String): String
	Convert the data in the byte array between the read and write positions to a string.
public	write(data: Array): Number
	Write data to the array.
public	writeByte(data: Number): Void
	Write a byte to the array.
public	writeDouble(data: Number): Void
	Write a double to the array.
public	writeInteger(data: Number): Void
	Write a 32-bit integer to the array.
public	writeLong(data: Number): Void
	Write a 64 bit long integer to the array.
public get	writePosition(): Number
	Get the current write position offset.
public set	writePosition(position: Number): Void
	Set the current write position offset.
public	writeShort(data: Number): Void
	Write a short to the array.

Inherited Methods

Method Detail

get public available(): Number

Get the number of bytes that are currently available for reading from the current read position.

Returns: The number of available bytes of data.

ByteArray(size: Number, growable: Boolean)

Create a new array.

Description: This will set the default encoding.

Parameters

size: Number	The initial size of the byte array. If not supplied a system default buffer size will be used.
growable: Boolean	Set to true to automatically grow the array as required to fit written data. If growable is false, then some writes may return "short". ie. not be able to accomodate all written data. [default: false]

public close(graceful: Boolean): Void

Close the byte array.

Parameters

graceful: Boolean

[default: false]

public copyIn(destOffset: Number, src: ByteArray, srcOffset: Number, count: Number): Void

Copy data into the array.

Description: Data is written at the $destOffset index.

Parameters

destOffset: Number	Index in the destination byte array to copy the data to
src: ByteArray	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.
count: Number	Number of bytes to copy. Set to -1 to read all available data.

Returns: The number of bytes written into the array.

public copyOut(srcOffset: Number, dest: ByteArray, destOffset: Number, count: Number): Number

Copy data from the array.

Description: Data is copied from the $srcOffset pointer.

Parameters

dest: ByteArray	Destination byte array
destOffset: Number	Location in the destination array to copy the data. Defaults to the start.
count: Number	Number of bytes to read. Set to -1 to read all available data.

Returns: The count of bytes read. Returns 0 on end of file.

Throws

IOError: if an I/O error occurs.

get public endian(): Number

Determine if the system is using little endian byte ordering.

Returns: An endian encoding constant. Either LittleEndian or BigEndian.

set public endian(value: Number): Void

Set the system encoding to little or big endian.

Parameters

value: Number

Set to true for little endian encoding or false for big endian.

public flush(): Void

Flush the the byte array and reset the read and write position pointers.

Description: This may invoke the output callback to send the data if the output callback is defined.

override iterator get(deep: Boolean): Iterator

Get an iterator for this array to be used by "for (v in array)".

Description: This will return array indicies for read data in the array.

Parameters

deep: Boolean

Follow the prototype chain. Only implemented in ECMA compliance mode.. [default: false]

Returns: An iterator object.

Specified: Ecma-4.

override iterator getValues(deep: Boolean): Iterator

Get an iterator for this array to be used by "for each (v in array)".

Description: This will return read data in the array.

Parameters

deep: Boolean

Follow the prototype chain. Only implemented in ECMA compliance mode.. [default: false]

Returns: An iterator object.

Specified: Ecma-4.

set public input(value: Function): Void

Input callback function when read data is required.

Description: The input callback should write to the supplied buffer.

Parameters

get public input(): Function

buffer: ByteArray	Destination byte array
offset: Number	Location in the destination buffer to copy the data. Defaults to the write position. If the offset is < 0, then the write position will be updated.
count: Number	Number of bytes to read. Set to -1 to read all available data.