const type: signedness

Enumeration of signedness values. Signedness defines if negative values can be represented. Defines: UNSIGNED and SIGNED. Signed values use the twos-complement representation.

const type: endianness

Enumeration of endianness values. Endianness defines how the bytes of a data are ordered within memory. Defines: LE (little-endian) and BE (big-endian). A little-endian representation starts with the least significant byte. A big-endian representation starts with the most significant byte.

const func string: fromAsciiz (in string: stri, in integer: startPos)

Get a null terminated string from stri starting from startPos.

Parameters:

stri - string of bytes from which the result is obtained.

startPos - Start position of the null terminated string.

Returns:

the null terminated string without the null ('\0;') character.

const func string: getAsciiz (in string: stri, inout integer: currPos)

Read a null terminated string from stri starting from currPos. CurrPos is advanced after the null ('\0;') character. When there is no null character the string is assumed to extend to the end of stri. In this case currPos is advanced beyond the length of stri.

Parameters:

stri - string of bytes from which the result is obtained.

currPos - Start position of the null terminated string. The function advances currPos to refer to the position behind the terminating null ('\0;') character.

Returns:

the null terminated string without the null ('\0;') character.

const func string: getAsciiz (inout file: inFile)

Read a null terminated string from inFile. The file position is advanced after the null ('\0;') character.

Parameters:

inFile - File from which the result is obtained.

Returns:

the null terminated string without the null ('\0;') character.

const func string: hex (in string: stri)

Convert a string of bytes to its hexadecimal representation. Each byte is represented by two hexadecimal digits.

hex("!;Mn")  returns "213b4d6e"

Returns:

the hexadecimal representation of the given string.

Raises:

RANGE_ERROR - If characters beyond '\255;' are present.

const func string: hex2Bytes (in string: hex)

Convert a string with hexadecimal digits to a string of bytes. Each byte in the result is represented by two hexadecimal digits in hex.

hexToBytes("6d")        returns "m"
hexToBytes("213b4d6e")  returns "!;Mn"

Returns:

the byte string that corresponds to the given hexadecimal string hex.

Raises:

RANGE_ERROR - If the length of hex is odd or if hex contains other characters than hexadecimal digits.

const func string: bytes (in integer: number, in signedness: signed, in endianness: endian)

Convert an integer into a string of bytes. The result uses binary representation with a base of 256. The result contains chars (bytes) with an ordinal <= 255.

bytes(1413829460, SIGNED, BE)  returns "TEST"
bytes(1497451343, SIGNED, LE)  returns "OKAY"

Parameters:

number - Integer number to be converted.

signed - Determines the signedness of the result. Possible values are UNSIGNED and SIGNED. If signed is SIGNED the result is encoded with the twos-complement representation. In this case a negative number is converted to a result where the most significant byte has an ordinal >= 128.

endian - Determines the endianness of the result. Possible values are LE for little-endian and BE for big-endian.

Returns:

a string with the shortest binary representation of number.

Raises:

RANGE_ERROR - If number is negative and signed is UNSIGNED.

MEMORY_ERROR - Not enough memory to represent the result.

const func string: bytes (in integer: number, in signedness: signed, in endianness: endian, in integer: length)

Convert an integer into a string of bytes with the given length. The result uses binary representation with a base of 256. The result contains chars (bytes) with an ordinal <= 255.

bytes(1413829460, SIGNED, BE, 5)  returns "\0;TEST"
bytes(1413829460, SIGNED, BE, 4)  returns "TEST"
bytes(1413829460, SIGNED, BE, 3)  raises RANGE_ERROR
bytes(1497451343, SIGNED, LE, 5)  returns "OKAY\0;"
bytes(1497451343, SIGNED, LE, 4)  returns "OKAY"
bytes(1497451343, SIGNED, LE, 3)  raises RANGE_ERROR
bytes(-1246382667, SIGNED, BE, 6)   returns "ÿÿµµµµ"
bytes(-1246382667, SIGNED, LE, 6)   returns "µµµµÿÿ"
bytes(-1246382667, SIGNED, LE, 4)   returns "µµµµ"
bytes(-1246382667, SIGNED, LE, 3)   raises RANGE_ERROR
bytes(-123456789, UNSIGNED, BE, 4)  raises RANGE_ERROR
bytes(-123456789, UNSIGNED, LE, 4)  raises RANGE_ERROR
bytes(3048584629, UNSIGNED, BE, 4)  returns "µµµµ"
bytes(3048584629, UNSIGNED, BE, 5)  returns "\0;µµµµ"
bytes(3048584629, UNSIGNED, LE, 6)  returns "µµµµ\0;\0;"

Parameters:

number - Integer number to be converted.

signed - Determines the signedness of the result. Possible values are UNSIGNED and SIGNED. If signed is SIGNED the result is encoded with the twos-complement representation. In this case a negative number is converted to a result where the most significant byte has an ordinal >= 128.

endian - Determines the endianness of the result. Possible values are LE for little-endian and BE for big-endian.

length - Determines the length of the result string.

Returns:

a string of length bytes with the binary representation of number.

Raises:

RANGE_ERROR - If number is negative and signed is UNSIGNED, or if length is negative or zero, or if the result would not fit in length bytes.

MEMORY_ERROR - Not enough memory to represent the result.

const func string: bytes (in bigInteger: number, in signedness: signed, in endianness: endian)

Convert a bigInteger into a string of bytes. The result uses binary representation with a base of 256. The result contains chars (bytes) with an ordinal <= 255.

bytes(1413829460_, SIGNED, BE)                        returns "TEST"
bytes(1497451343_, SIGNED, LE)                        returns "OKAY"
bytes(8316866959935304777_, UNSIGNED, LE)             returns "It works"
bytes(54818063270363344731475178867_, UNSIGNED, BE)   returns "± plus-minus"
bytes(54818063270363344731475178867_, SIGNED, BE)     returns "\0;± plus-minus"
bytes(-24410099243900992862068771469_, SIGNED, BE)    returns "± plus-minus"
bytes(-24410099243900992862068771469_, UNSIGNED, LE)  raises RANGE_ERROR

Parameters:

number - BigInteger number to be converted.

signed - Determines the signedness of the result. Possible values are UNSIGNED and SIGNED. If signed is SIGNED the result is encoded with the twos-complement representation. In this case a negative number is converted to a result where the most significant byte has an ordinal >= 128.

endian - Determines the endianness of the result. Possible values are LE for little-endian and BE for big-endian.

Returns:

a string with the shortest binary representation of number.

Raises:

RANGE_ERROR - If number is negative and signed is UNSIGNED.

MEMORY_ERROR - Not enough memory to represent the result.

const func string: bytes (in bigInteger: number, in signedness: signed, in endianness: endian, in integer: length)

Convert a bigInteger to a string of bytes with a length. The result uses binary representation with a base of 256. The result contains chars (bytes) with an ordinal <= 255.

bytes(1413829460_, SIGNED, BE, 5)    returns "\0;TEST"
bytes(1413829460_, SIGNED, BE, 4)    returns "TEST"
bytes(1413829460_, SIGNED, BE, 3)    raises RANGE_ERROR
bytes(-1246382667_, SIGNED, BE, 6)   returns "ÿÿµµµµ"
bytes(-1246382667_, SIGNED, LE, 6)   returns "µµµµÿÿ"
bytes(-1246382667_, SIGNED, LE, 4)   returns "µµµµ"
bytes(-1246382667_, SIGNED, LE, 3)   raises RANGE_ERROR
bytes(3048584629_, UNSIGNED, BE, 4)  returns "µµµµ"
bytes(3048584629_, UNSIGNED, LE, 6)  returns "µµµµ\0;\0;"

Parameters:

number - BigInteger number to be converted.

signed - Determines the signedness of the result. Possible values are UNSIGNED and SIGNED. If signed is SIGNED the result is encoded with the twos-complement representation. In this case a negative number is converted to a result where the most significant byte has an ordinal >= 128.

endian - Determines the endianness of the result. Possible values are LE for little-endian and BE for big-endian.

length - Length of the result string.

Returns:

a string of bytes with length representing number.

Raises:

RANGE_ERROR - If the result does not fit into length.

RANGE_ERROR - If number is negative and signed is UNSIGNED.

MEMORY_ERROR - Not enough memory to represent the result.

const func integer: bytes2Int (in string: byteStri, in signedness: signed, in endianness: endian)

Convert a string of bytes to an integer.

bytes2Int("I\150;\2;\210;", UNSIGNED, BE)  returns  1234567890
bytes2Int("\210;\2;\150;I", UNSIGNED, LE)  returns  1234567890
bytes2Int(":\222;h\177;", UNSIGNED, BE)    returns   987654321

Parameters:

byteStri - String of bytes to be converted. The bytes are interpreted as binary representation with a base of 256.

signed - Determines the signedness of byteStri. Possible values are UNSIGNED and SIGNED. If signed is SIGNED bstri is interpreted as signed value in the twos-complement representation. In this case the result is negative if the most significant byte has an ordinal >= 128.

endian - Determines the endianness of byteStri. Possible values are LE for little-endian and BE for big-endian.

Returns:

an integer created from byteStri.

Raises:

RANGE_ERROR - If byteStri is empty or if characters beyond '\255;' are present or if the result value cannot be represented with an integer.

const func bigInteger: bytes2BigInt (in string: byteStri, in signedness: signed, in endianness: endian)

Convert a string of bytes to a bigInteger.

bytes2BigInt("I\150;\2;\210;", SIGNED, BE)        returns  1234567890_
bytes2BigInt("\210;\2;\150;I", UNSIGNED, LE)      returns  1234567890_
bytes2BigInt(":\222;h\177;", SIGNED, BE)          returns   987654321_
bytes2BigInt("\139;\208;\3;\152;", UNSIGNED, BE)  returns  2345665432_
bytes2BigInt("\139;\208;\3;\152;", SIGNED, BE)    returns -1949301864_
bytes2BigInt("\152;\3;\208;\139;", UNSIGNED, LE)  returns  2345665432_

Parameters:

byteStri - String of bytes to be converted. The bytes are interpreted as binary representation with a base of 256.

signed - Determines the signedness of byteStri. Possible values are UNSIGNED and SIGNED. If signed is SIGNED bstri is interpreted as signed value in the twos-complement representation. In this case the result is negative if the most significant byte has an ordinal >= 128.

endian - Determines the endianness of byteStri. Possible values are LE for little-endian and BE for big-endian.

Returns:

a bigInteger created from byteStri.

Raises:

RANGE_ERROR - If byteStri is empty or if characters beyond '\255;' are present.

MEMORY_ERROR - Not enough memory to represent the result.

const func integer: getUInt16Le (inout file: inFile)

Read two bytes from a file and return their little-endian value.

const func integer: getUInt32Le (inout file: inFile)

Read four bytes from a file and return their little-endian value.

const func integer: getUInt16Be (inout file: inFile)

Read two bytes from a file and return their big-endian value.

const func integer: getUInt32Be (inout file: inFile)

Read four bytes from a file and return their big-endian value.