ByteArrayclass | bytearr.h[26] |
Superclass Tree | Subclass Tree | Global Objects | Property Summary | Method Summary | Property Details | Method Details |
ByteArray is particularly useful for reading and writing binary files, since it lets you manipulate the raw bytes in a file directly.
intrinsic class
ByteArray : Object
ByteArray
Object
copyFrom
digestMD5
fillValue
length
mapToString
packBytes
readInt
sha256
subarray
unpackBytes
writeInt
Inherited from Object
:
callInherited
createIterator
createLiveIterator
forEach
getPropList
getPropParams
getSuperclassList
isClass
isTransient
mapAll
ofKind
propDefined
propInherited
propType
valToSymbol
copyFrom (src, srcStartIndex, dstStartIndex, length) | bytearr.h[70] |
digestMD5 ( ) | bytearr.h[213] |
fillValue (val, startIndex?, length?) | bytearr.h[78] |
length ( ) | bytearr.h[55] |
mapToString (charset, startIndex?, length?) | bytearr.h[88] |
If the starting index and length are not given, the entire byte array is converted to a string. 'charset' must be an object of intrinsic class CharacterSet.
packBytes (idx, format, ...) | bytearr.h[180] |
'idx' is the starting index in the array for the packed bytes. 'format' is the format string, which specifies the binary representations to use for the argument values. The remaining arguments after 'format' are the data values to pack.
Returns the number of bytes written to the array. (More precisely, returns the final write pointer as a byte offset from 'idx'. If a positioning code like @ or X is used in the string, it's possible that more bytes were actually written.)
You can also call packBytes a static method, on the ByteArray class itself:
ByteArray.packBytes(format, ...)
The static version of the method packs the data into bytes the same way the regular method does, but returns a new ByteArray object containing the packed bytes. Note that there's no index argument with the static version.
Refer to Byte Packing in the System Manual for details.
readInt (startIndex, format) | bytearr.h[127] |
'format' gives the format of the integer to be read. This is a combination (using '|' operators) of three constants, giving the size, byte order, and signedness of the value.
First, choose the SIZE of the value: FmtSize8, FmtSize16, FmtSize32, for 8-bit, 16-bit, and 32-bit integers, respectively.
Second, choose the BYTE ORDER of the value, as represented in the byte array: FmtLittleEndian or FmtBigEndian. The standard T3 portable data interchange format uses little-endian values; this is a format in which the least-significant byte of a value comes first, followed by the remaining bytes in ascending order of significance. The big-endian format uses the opposite order. The byte order obviously is irrelevant for 8-bit values.
Third, choose the SIGNEDNESS of the value: FmtSigned or FmtUnsigned. Note that FmtUnsigned cannot be used with FmtSize32, because T3 itself doesn't have an unsigned 32-bit integer type.
For example, to read a 16-bit unsigned integer in the standard T3 portable interchange format, you'd use
FmtUnsigned | FmtSize16 | FmtLittleEndian
For convenience, individual macros are also defined that pre-compose all of the meaningful combinations; see below.
The byte array must be large enough to read the required number of bytes starting at the given index. An "index out of range" exception is thrown if there aren't enough bytes in the array to satisfy the request.
sha256 (idx?, len?) | bytearr.h[203] |
subarray (startIndex, length?) | bytearr.h[62] |
unpackBytes (idx, format) | bytearr.h[193] |
'idx' is the starting index in the array for the unpacking, and 'format' is the format string. Returns a list of the unpacked values.
Refer to Byte Packing in the System Manual for details.
writeInt (startIndex, format, val) | bytearr.h[151] |
The byte array must be large enough to hold the number of bytes required by the format starting at the starting index. An "index out of range" exception is thrown if the byte array doesn't have enough space to store the value.
The value is not checked for range. If the value is outside of the range that the format is capable of storing, the value stored will be truncated to its least significant bits that fit the format. For example, attempting to store 0xABCD in an 8-bit format will store only 0xCD.
Note that the signedness doesn't matter when writing a value. The signedness is important only when reading the value back in.