ByteArray
Module | ejs |
Namespace | intrinsic |
Definition | final class ByteArray |
Inheritance | ByteArray ![]() |
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 static const | BigEndian | Number | |
public static 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 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 the number of bytes that are currently available for reading from the current read position.
- Returns
- The number of available bytes of data.
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]
Close the byte array.
- Parameters
graceful: Boolean [default: false]
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.
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.
Determine if the system is using little endian byte ordering.
- Returns
- An endian encoding constant. Either LittleEndian or BigEndian.
Set the system encoding to little or big endian.
- Parameters
value: Number Set to true for little endian encoding or false for big endian.
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.
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.
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.
Input callback function when read data is required.
- Description
- The input callback should write to the supplied buffer.
- Parameters
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.
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
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.
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.
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.
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.
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.
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.
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.
Return the current read position offset.
- Returns
- The read offset.
Set the current read position offset.
- Parameters
position: Number The new read position
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.
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.
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.
Reset the read and write position pointers if there is no available data.
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.
Convert the data in the byte array between the read and write positions to a string.
- Parameters
locale: String
- Returns
- A string.
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.
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
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
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
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 the current write position offset.
- Returns
- The write position.
Set the current write position offset.
- Parameters
position: Number the new write position
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