ByteArray

Moduleejs
Definitionfinal class ByteArray
InheritanceByteArray inherit Object
Specifiedejscript-1.1
StabilityEvolving.

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 readPosition and writePosition 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 readPosition.


Properties

QualifiersPropertyTypeDescription
public static const BigEndianNumberBig endian byte order used for the endian property.
public static const LittleEndianNumberLittle endian byte order constants used for the endian property.
public get availableNumberNumber of bytes that are currently available for reading. This consists of the bytes available from the current readPosition up to the current write position.
public get setendianNumberCurrent byte ordering for storing and retrieving numbers. Set to either LittleEndian or BigEndian.
public set input Input callback function when read data is required. The input callback should write to the supplied buffer.
public get setoutputFunctionOutput function to process (output) data. The output callback should read from the supplied buffer.
public get setreadPositionNumberCurrent read position offset.
public get roomNumberNumber of data bytes that the array can store from the writePosition till the end of the array.
public get setwritePositionNumberCurrent write position offset.

ByteArray Methods

QualifiersMethod
ByteArray(size: Number = -1 , growable: Boolean = false)
 Create a new array.
public close(graceful: Boolean = false): Void
 Close the byte array.
public compact(): Void
 Compact available data down and adjust the read/write positions accordingly.
public copyIn(destOffset: Number, src: ByteArray, srcOffset: Number = 0 , count: Number = -1): Number
 Copy data into the array.
public copyOut(srcOffset: Number, dest: ByteArray, destOffset: Number = 0 , count: Number = -1): Number
 Copy data from the array.
public flush(graceful: Boolean = true): Void
 Flush the the byte array and reset the read and write position pointers.
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)".
public read(buffer: ByteArray, offset: Number = 0 , count: Number = -1): 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.The data will be decoded according to the encoding property.
public readShort(): Number
 Read a 16-bit short integer from the array.The data will be decoded according to the encoding property.
public readString(count: Number = -1): 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 writePosition pointers if there is no available data.
public override toString(): String
 Convert the data in the byte array between the readPosition and writePosition offsets.
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 writeShort(data: Number): Void
 Write a short to the array.

Method Detail

public ByteArray(size: Number = -1 , growable: Boolean = false)

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. [default: -1 ]
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 = false): Void

Close the byte array.

Parameters
graceful: Boolean If true, then write all pending data. [default: false]

public compact(): Void

Compact available data down and adjust the read/write positions accordingly.

Description
This sets the read pointer to the zero index and adjusts the write pointer by the corresponding amount.

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

Copy data into the array.

Description
Data is written at the destOffset index. This call does not update the read and write positions.
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 to the end of the src buffer. [default: -1]
Returns
The number of bytes written into the array.

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

Copy data from the array.

Description
Data is copied from the srcOffset pointer. This call does not update the read and write positions.
Parameters
srcOffset: Number Location in the source array from which to copy the 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 0 on end of file.
Throws
IOError: if an I/O error occurs.

public flush(graceful: Boolean = true): 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.
Parameters
graceful: Boolean [default: true]

override iterator get(): Iterator

Iterator for this array to be used by "for (v in array)".

Description
This will return array indicies for read data in the array.
Returns
An iterator object.

override iterator getValues(): Iterator

Iterator for this array to be used by "for each (v in array)".

Description
This will return read data in the array.

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

Read data from the array into another byte array.

Description
Data is read from the current read position pointer toward the current write position. This byte array's readPosition is updated. If offset is < 0, then data is copied to the destination buffer's write position and the destination buffer's write position is also updated. If the offset is >= 0, the read and write positions of the destination buffer are updated.
Parameters
buffer: ByteArray Destination byte array.
offset: Number Location in the destination buffer to copy the data. If the offset is < 0, then the write position is used and will be updated with the number of bytes read from the buffer. [default: 0 ]
count: Number Number of bytes to read. Set to -1 to read all available data that will fit into the destination buffer. [default: -1]
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.The data will be decoded according to the encoding property.

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

public readShort(): Number

Read a 16-bit short integer from the array.The data will be decoded according to the encoding property.

Description
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 = -1): String

Read a data from the array as a string.

Description
Read data from the readPosition to a string up to the writePosition, but not more than count characters.
Parameters
count: Number Of bytes to read. If -1, convert the data up to the writePosition. [default: -1]
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 writePosition pointers if there is no available data.


override public toString(): String

Convert the data in the byte array between the readPosition and writePosition offsets.

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.

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.