ByteArray
Module | ejs |
Definition | final class ByteArray |
Inheritance | ByteArray ![]() |
Specified | ejscript-1.1 |
Stability | Evolving. |
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
Qualifiers | Property | Type | Description |
---|---|---|---|
public static const | BigEndian | Number | Big endian byte order used for the endian property. |
public static const | LittleEndian | Number | Little endian byte order constants used for the endian property. |
public get | available | Number | Number 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 set | endian | Number | Current 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 set | output | Function | Output function to process (output) data. The output callback should read from the supplied buffer. |
public get set | readPosition | Number | Current read position offset. |
public get | room | Number | Number of data bytes that the array can store from the writePosition till the end of the array. |
public get set | writePosition | Number | Current write position offset. |
ByteArray Methods
Qualifiers | Method |
---|---|
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
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]
Close the byte array.
- Parameters
graceful: Boolean If true, then write all pending data. [default: false]
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.
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.
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.
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]
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.
Iterator for this array to be used by "for each (v in array)".
- Description
- This will return read data in the array.
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.
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.
Reset the read and writePosition pointers if there is no available data.
Convert the data in the byte array between the readPosition and writePosition offsets.
- 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.