Data types¶

The armaio.binary module provides utility functions for reading and writing the basic data types used in Arma 3 file formats as outlined on the community wiki.

Examples¶

The following examples give a simple demonstration about the usage of the function in the module.

Writing¶

from armaio import binary as a3io

with open("file.bin", "wb") as file:
    a3io.write_chars(file, "A3IO")
    version_major = 2
    version_minor = 1
    a3io.write_ushort(file, version_major, version_minor)
    count = 10
    a3io.write_compressed_uint(file, count)
    for i in range(count):
        a3io.write_ulong(file, i)

Reading¶

from armaio import binary as a3io

with open("file.bin", "rb") as file:
    signature = a3io.read_char(file)
    version_major, version_minor = a3io.read_ushorts(file, 2)
    count = a3io.read_compressed_uint(file)
    data = []
    for i in range(count):
        data.append(a3io.read_ulong(file))

Functions¶

String reading¶

armaio.binary.read_asciiz(stream: IO[bytes]) → str¶

Reads a NULL-terminated ASCII string.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: ASCII string
Return type:: str

armaio.binary.read_asciiz_field(stream: IO[bytes], field: int) → str¶

Reads a NULL-terminated ASCII string NULL padded to field length.

Parameters:

stream (IO[bytes]) – Source binary stream
field (int) – Field length

Raises:

EOFError – EOF was encountered in given length
ValueError – Terminator NULL was not found in field

Returns:

ASCII string

Return type:

str

armaio.binary.read_lascii(stream: IO[bytes]) → str¶

Reads a length-prefixed ASCII string.

The string can be at most 255 characters long.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: EOFError – EOF was encountered in expected length
Returns:: ASCII string
Return type:: str

armaio.binary.read_char(stream: IO[bytes], count: int = 1) → str¶

Reads a sequence of ASCII characters.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of characters to read, defaults to 1

Returns:

String of ASCII characters

Return type:

str

String writing¶

armaio.binary.write_asciiz(stream: IO[bytes], value: str) → None¶

Writes a NULL-terminated ASCII string.

Parameters:

stream (IO[bytes]) – Target binary stream
value (str) – ASCII string

armaio.binary.write_asciiz_field(stream: IO[bytes], value: str, field: int) → None¶

Writes a NULL-terminated ASCII string to a NULL paddded field.

Parameters:

stream (IO[bytes]) – Target binary stream
value (str) – ASCII string
field (int) – Field length

Raises:

ValueError – String with NULL-terminator does not fit into field

armaio.binary.write_lascii(stream: IO[bytes], value: str) → None¶

Writes length-prefixed ASCII string.

The string can be at most 255 characters.

Parameters:

stream (IO[bytes]) – Target binary stream
value (str) – ASCII string

Raises:

ValueError – String is longer than 255 characters

armaio.binary.write_chars(stream: IO[bytes], values: str) → None¶

Writes a sequence of ASCII characters.

Parameters:

stream (IO[bytes]) – Target binary stream
values (str) – ASCII string

Integer reading¶

armaio.binary.read_bool(stream: IO[bytes]) → bool¶

Reads a single byte as boolean.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: Boolean value
Return type:: bool

armaio.binary.read_byte(stream: IO[bytes]) → int¶

Reads a single byte as an unsigned integer.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 8-bit unsigned integer
Return type:: int

armaio.binary.read_bytes(stream: IO[bytes], count: int = 1) → tuple[int, ...]¶

Reads multiple bytes as unsigned integers.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of bytes to read, defaults to 1

Returns:

8-bit unsigned integers

Return type:

tuple[int, …]

armaio.binary.read_short(stream: IO[bytes]) → int¶

Reads a single little-endian short integer.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 16-bit signed integer
Return type:: int

armaio.binary.read_shorts(stream: IO[bytes], count: int = 1) → tuple[int, ...]¶

Reads multiple little-endian short integers.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of integers to read, defaults to 1

Returns:

16-bit unsigned integers

Return type:

tuple[int, …]

armaio.binary.read_ushort(stream: IO[bytes]) → int¶

Reads a single little-endian unsigned short integer.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 16-bit unsigned integer
Return type:: int

armaio.binary.read_ushorts(stream: IO[bytes], count: int = 1) → tuple[int, ...]¶

Reads multiple little-endian unsigned short integers.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of integers to read, defaults to 1

Returns:

16-bit unsigned integers

Return type:

tuple[int, …]

armaio.binary.read_long(stream: IO[bytes]) → int¶

Reads a single little-endian long integer.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 32-bit signed integer
Return type:: int

armaio.binary.read_longs(stream: IO[bytes], count: int = 1) → tuple[int, ...]¶

Reads multiple little-endian long integers.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of integers to read, defaults to 1

Returns:

32-bit signed integers

Return type:

tuple[int, …]

armaio.binary.read_ulong(stream: IO[bytes]) → int¶

Reads a single little-endian unsigned long integer.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 32-bit unsigned integer
Return type:: int

armaio.binary.read_ulongs(stream: IO[bytes], count: int = 1) → tuple[int, ...]¶

Reads multiple little-endian unsigned long integers.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of integers to read, defaults to 1

Returns:

32-bit unsigned integers

Return type:

tuple[int, …]

armaio.binary.read_compressed_uint(stream: IO[bytes]) → int¶

Reads a little-endian compressed unsigned integer.

Compressed integers take up an arbitrary number of bytes. In each byte, the high bit signals if the next byte has to be read.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 7-bit encoded compressed unsigned integer
Return type:: int

Integer writing¶

armaio.binary.write_bool(stream: IO[bytes], value: bool) → None¶

Writes a boolean as a byte.

Parameters:

stream (IO[bytes]) – Target binary stream
value (bool) – Boolean value

armaio.binary.write_byte(stream: IO[bytes], *args: int) → None¶

Writes integers as bytes.

Parameters:

stream (IO[bytes]) – Target binary stream
args (int) – 8-bit unsigned integers

armaio.binary.write_short(stream: IO[bytes], *args: int) → None¶

Writes little-endian short integers.

Parameters:

stream (IO[bytes]) – Target binary stream
args (int) – 16-bit integers

armaio.binary.write_ushort(stream: IO[bytes], *args: int) → None¶

Writes little-endian unsigned short integers.

Parameters:

stream (IO[bytes]) – Target binary stream
args (int) – 16-bit unsigned integers

armaio.binary.write_long(stream: IO[bytes], *args: int) → None¶

Writes little-endian long integers.

Parameters:

stream (IO[bytes]) – Target binary stream
args (int) – 32-bit integers

armaio.binary.write_ulong(stream: IO[bytes], *args: int) → None¶

Writes little-endian unsigned long integers.

Parameters:

stream (IO[bytes]) – Target binary stream
args (int) – 32-bit unsigned integers

armaio.binary.write_compressed_uint(stream: IO[bytes], value: int) → None¶

Writes a little-endian compressed unsigned integer.

Compressed integers take up an arbitrary number of bytes. In each byte, the high bit signals if the next byte has to be read.

Parameters:

stream (IO[bytes]) – Target binary stream
value (int) – Unsigned integer

Float reading¶

armaio.binary.read_half(stream: IO[bytes]) → float¶

Reads a single little-endian half-precision float.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 16-bit float
Return type:: float

armaio.binary.read_halfs(stream: IO[bytes], count: int = 1) → tuple[float, ...]¶

Reads multiple little-endian half-precision floats.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of floats to read, defaults to 1

Returns:

16-bit floats

Return type:

tuple[float, …]

armaio.binary.read_float(stream: IO[bytes]) → float¶

Reads a single little-endian single-precision float.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 32-bit float
Return type:: float

armaio.binary.read_floats(stream: IO[bytes], count: int = 1) → tuple[float, ...]¶

Reads multiple little-endian single-precision floats.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of floats to read, defaults to 1

Returns:

32-bit floats

Return type:

tuple[float, …]

armaio.binary.read_double(stream: IO[bytes]) → float¶

Reads a single little-endian double-precision float.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: 64-bit float
Return type:: float

armaio.binary.read_doubles(stream: IO[bytes], count: int = 1) → tuple[float, ...]¶

Reads multiple little-endian double-precision floats.

Parameters:

stream (IO[bytes]) – Source binary stream
count (int, optional) – Number of floats to read, defaults to 1

Returns:

64-bit floats

Return type:

tuple[float, …]

Float writing¶

armaio.binary.write_half(stream: IO[bytes], *args: float) → None¶

Writes little-endian half-precision floats.

Parameters:

stream (IO[bytes]) – Target binary stream
args (float) – 16-bit floats

armaio.binary.write_float(stream: IO[bytes], *args: float) → None¶

Writes little-endian single-precision floats.

Parameters:

stream (IO[bytes]) – Target binary stream
args (float) – 32-bit floats

armaio.binary.write_double(stream: IO[bytes], *args: float) → None¶

Writes little-endian double-precision floats.

Parameters:

stream (IO[bytes]) – Target binary stream
args (float) – 64-bit floats