ByteArray class | bytearr.h[26]

'ByteArray' intrinsic class. This class provides a fixed-size array of unsigned 8-bit byte values; each array element is an integer in the range 0-255.

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`

Superclass Tree (in declaration order)

`ByteArray`
`Object`

Subclass Tree

(none)

Global Objects

(none)

Summary of Properties

``

``

(none)

Summary of Methods

`copyFrom digestMD5 fillValue length mapToString packBytes readInt sha256 subarray unpackBytes writeInt`

Inherited from `Object` :
`getPropList getPropParams getSuperclassList isClass isTransient ofKind propDefined propInherited propType valToSymbol`

Properties

(none)

Methods

`copyFrom (src, srcStartIndex, dstStartIndex, length)` | `bytearr.h[70]`

Copy bytes from the source array into this array. Bytes are copied into this array starting at the given index. The specified number of bytes are copied from the source array starting at the given index.

`digestMD5 ( )` | `bytearr.h[213]`

Get the MD5 digest of the string. This calculates the 128-bit RSA MD5 digest value, returning the digest as a 32-character string of hex digits. The hash value is computed on the UTF-8 representation of the string. If 'idx' and 'len' are specified, the give the range of bytes to include in the hash; the default is to hash the whole array.

`fillValue (val, startIndex?, length?)` | `bytearr.h[78]`

Fill bytes in this array with the given value. If no starting index or length values are given, the entire array is filled with the given byte value. The byte value must be an integer in the range 0 to 255.

`length ( )` | `bytearr.h[55]`

Get the number of bytes in the array. The length is fixed at creation time.

`mapToString (charset, startIndex?, length?)` | `bytearr.h[88]`

Convert a range of bytes in the array to a string, interpreting the bytes in the array as characters in the given character set.

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]`

Pack data values into bytes according to a format definition string, and store the packed bytes in the byte array starting at the given index.

'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]`

Read an integer value from the byte array. Reads bytes from the starting index; the number of bytes read depends on the format. Returns an integer giving the value read.

'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]`

Get the SHA-256 hash of the bytes in the array. This calculates the 256-bit Secure Hash Algorithm 2 hash value, returning the hash as a 64-character string of hex digits. The hash value is computed on the UTF-8 representation of the string. If 'idx' and 'len' are specified, they give the range of bytes to include in the hash; the default is to hash the whole array.

`subarray (startIndex, length?)` | `bytearr.h[62]`

create a new ByteArray as a copy of the given range of this array; if the length is not given, bytes from the starting index to the end of this array are included in the new array

`unpackBytes (idx, format)` | `bytearr.h[193]`

Unpack bytes from the byte array starting at the given index, and translate the bytes into data values according to the given format string.

'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]`

Write an integer value to the byte array. Writes bytes starting at the given index; the number of bytes written depends on the format. The 'format' parameter gives the format, using the same codes as in readInt(). 'val' is the integer value to be written. If 'val' is outside of the bounds of the format to be written, the written value is truncated.

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.

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3