ByteArray

Moduleejs
Namespaceintrinsic
Definitionfinal class ByteArray
InheritanceByteArray inherit 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

QualifiersPropertyTypeDescription
public static const BigEndianNumber 
public static const LittleEndianNumberNumeric byte order constants used for the endian property.

ByteArray Methods

QualifiersMethod
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 override 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 skip(n: Number): Void
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.

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.

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.

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

override get public length(): Number

Get the length of an array.

Description
This is not the amount of read or write data, but is the size of the total array storage.
Returns
The size of the byte array.

set public output(callback: Function): Void

Define an output function to process (output) data.

Description
The output callback should read from the supplied buffer.
Parameters
callback: Function Function to invoke when the byte array is full or flush() is called. function outputCallback(buffer: ByteArray): Number

get public output(): Function

public read(buffer: ByteArray, offset: Number, count: Number): Number

Read data from the array into another byte array.

Description
Data is read from the current read $position pointer.
Parameters
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.
Returns
The count of bytes read. Returns 0 on end of file.

Throws

IOError: if an I/O error occurs.


public readBoolean(): Boolean

Read a boolean from the array.

Description
Data is read from the current read $position pointer.
Returns
A boolean.

Throws

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


public readByte(): Number

Read a byte from the array.

Description
Data is read from the current read $position pointer.
Returns
A byte.

Throws

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


public readDate(): Date

Read a date from the array or a premature end of file.

Description
Data is read from the current read $position pointer.
Returns
A date.

Throws

IOError: if an I/O error occurs.


public readDouble(): Date

Read a double from the array.

Description
The data will be decoded according to the encoding property. Data is read from the current read $position pointer.
Returns
A double.

Throws

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


public readInteger(): Number

Read an 32-bit integer from the array.

Description
The data will be decoded according to the encoding property. Data is read from the current read $position pointer.
Returns
An integer.

Throws

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


public readLong(): Number

Read a 64-bit long from the array.

Description
The data will be decoded according to the encoding property. Data is read from the current read $position pointer.
Returns
A long.

Throws

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


get public readPosition(): Number

Return the current read position offset.

Returns
The read offset.

set public readPosition(position: Number): Void

Set the current read position offset.

Parameters
position: Number The new read position

public readShort(): Number

Read a 16-bit short integer from the array.

Description
The data will be decoded according to the encoding property. Data is read from the current read $position pointer.
Returns
A short int.

Throws

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


public readString(count: Number): String

Read a data from the array as a string.

Description
Read data from the read position to a string up to the write position, but not more than count characters.
Parameters
count: Number of bytes to read. If -1, convert the data up to the write position.
Returns
A string.

Throws

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


public readXML(): XML

Read an XML document from the array.

Description
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.


public reset(): Void

Reset the read and write position pointers if there is no available data.


get public room(): Number

Get the number of data bytes that the array can store from the write position till the end of the array.

Returns
The number of data bytes that can be written.

public skip(n: Number): Void

override public toString(locale: String): String

Convert the data in the byte array between the read and write positions to a string.

Parameters
locale: String
Returns
A string.

public write(data: Array): Number

Write data to the array.

Description
Binary data is written in an optimal, platform dependent binary format. If cross-platform portability is required, use the BinaryStream to encode the 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. NOTE: the data byte array will not have its readPosition adjusted.
Parameters
data: Array Data elements to write
Returns
The number of bytes written into the array.

public writeByte(data: Number): Void

Write a byte to the array.

Description
Data is written to the current write $position pointer which is then incremented.
Parameters
data: Number Data to write

public writeDouble(data: Number): Void

Write a double to the array.

Description
Data is written to the current write $position pointer which is then incremented.
Parameters
data: Number Data to write

public writeInteger(data: Number): Void

Write a 32-bit integer to the array.

Description
Data is written to the current write $position pointer which is then incremented.
Parameters
data: Number Data to write

public writeLong(data: Number): Void

Write a 64 bit long integer to the array.

Description
Data is written to the current write $position pointer which is then incremented.
Parameters
data: Number Data to write

get public writePosition(): Number

Get the current write position offset.

Returns
The write position.

set public writePosition(position: Number): Void

Set the current write position offset.

Parameters
position: Number the new write position

public writeShort(data: Number): Void

Write a short to the array.

Description
Data is written to the current write $position pointer which is then incremented.
Parameters
data: Number Data to write