Documentation

baml.Uint8Array

A mutable, growable array of bytes, each in the range 0–255.

Reference version

Signature

class baml.Uint8Array

A mutable, growable array of bytes, each in the range 0–255.

The type for binary data: file contents, network payloads, encoded strings. push, pop, and sort modify the array in place; every other method here returns a new one.

The two ways of turning an int into a byte disagree deliberately. push silently masks its argument to the low 8 bits, as assigning into a JavaScript typed array does, while from_array throws baml.errors.InvalidArgument on anything outside 0–255.

JavaScript's Uint8Array, Python's bytearray.

Source:<builtin>/baml/uint8array.bamlbytes 748–8183

Static methods

function

from_array

(array: int[]) -> uint8array throws baml.errors.InvalidArgument

Creates a uint8array from an array of integers, one byte per element.

Unlike push, this validates rather than masks.

Throws

  • baml.errors.InvalidArgument if any value is outside the range 0–255.

Examples

uint8array.from_array([104, 101, 108, 108, 111])  // b"hello"
uint8array.from_array([256])                      // throws — out of range
function

from_base64

(base64: string) -> uint8array throws baml.errors.InvalidArgument

Decodes a Base64-encoded string into bytes.

Accepts both the standard (+/) and URL-safe (-_) alphabets, with or without padding.

Throws

  • baml.errors.InvalidArgument if base64 is not valid Base64.

Examples

uint8array.from_base64("aGVsbG8=")   // [104, 101, 108, 108, 111]  ("hello")
function

from_hex

(hex: string) -> uint8array throws baml.errors.InvalidArgument

Decodes a hexadecimal string such as "deadbeef" into bytes.

Two characters per byte, in either case. Python's bytes.fromhex additionally skips embedded whitespace; this does not.

Throws

  • baml.errors.InvalidArgument if hex has an odd length or contains a non-hex character.

Examples

uint8array.from_hex("deadbeef")  // [222, 173, 190, 239]
function

zeroes

(size: int) -> uint8array throws baml.errors.InvalidArgument

Creates an array of size zero bytes.

Throws

  • baml.errors.InvalidArgument if size is negative.

Panics

  • baml.panics.AllocFailure if size bytes cannot be allocated.

Examples

uint8array.zeroes(3)  // [0, 0, 0]
uint8array.zeroes(0)  // []

Instance methods

function

_to_string_impl

(self) -> string throws never

(internal) Native backing for the to_string implementation above.

function

at

(self, index: int) -> int | null throws never

Returns the byte at index, or null if index is out of range.

A negative index counts from the end, so -1 is the last byte. This is JavaScript's at with null in place of undefined.

Examples

b"abc".at(0)   // 97
b"abc".at(-1)  // 99
b"abc".at(99)  // null
function

concat

(self, other: uint8array) -> uint8array throws never

Returns a new array holding self followed by other.

Examples

b"abc".concat(b"def")  // [97, 98, 99, 100, 101, 102]
function

includes

(self, item: int) -> bool throws never

Returns true if the array contains item.

An item outside 0–255 is never present.

Examples

b"abc".includes(98)  // true
function

index_of

(self, item: int) -> int | null throws never

Returns the index of the first occurrence of item, or null if it is absent. An item outside 0–255 is never present.

Examples

b"abc".index_of(98)   // 1
b"abc".index_of(122)  // null
function

length

(self) -> int throws never

Returns the number of bytes.

function

pop

(self) -> int | null throws never
function

push

(self, item: int) -> int throws never
function

reverse

(self) -> uint8array throws never

Returns a new array with the bytes in reverse order.

JavaScript's reverse reverses in place; this leaves self alone.

Examples

b"abc".reverse()  // b"cba"
function

slice

(self, start: int, end: int) -> uint8array throws never

Returns the bytes in [start, end).

Either bound may be negative, counting from the end. Out-of-range bounds are clamped, and an end at or before start yields an empty array.

Examples

b"hello".slice(0, 3)    // b"hel"
b"hello".slice(-3, -1)  // b"ll"
function

sort

(self) -> null throws never
function

to_array

(self) -> int[] throws never

Returns the bytes as ints, each in the range 0–255.

Examples

b"hi".to_array()  // [104, 105]
function

to_base64

(self) -> string throws never

Encodes the bytes as a standard Base64 string, with = padding. Python's base64.b64encode.

Examples

"hello".to_utf8().to_base64()   // "aGVsbG8="
function

to_hex

(self) -> string throws never

Encodes the bytes as a lowercase hexadecimal string, two characters per byte. Python's bytes.hex.

Examples

uint8array.from_hex("deadbeef").to_hex()  // "deadbeef"

Implementations

baml.Concrete for T

Source:<builtin>/baml/core.bamlbytes 747–779

baml.ToString for baml.Uint8Array

Instance methods

function

to_string

(self) -> string throws never

Lossily decodes the bytes as UTF-8.

Each invalid sequence becomes U+FFFD, the replacement character. Use string.from_utf8 to reject malformed input instead.

Examples

b"hello".to_string()  // "hello"
b"".to_string()  // ""
b"\x80".to_string()  // "�"

Source:<builtin>/baml/uint8array.bamlbytes 7212–7759

baml.ops.Equals for uint8array

Instance methods

function

eq

(self, other: uint8array) -> bool throws never
function

neq

(self, other: Self) -> bool throws never

Whether self and other differ. Defaults to !self.eq(other).

Override this only to compute the answer more directly; an override that disagrees with !eq leaves the pair inconsistent. Equals for null overrides it with a constant false, which is consistent because null has exactly one value.

Source:<builtin>/baml/ns_ops/comparison.bamlbytes 13116–13238

baml.ops.Index for uint8array

Output = int

Instance methods

function

index

(self, idx: int) -> int throws never

Source:<builtin>/baml/ns_ops/index.bamlbytes 2767–2910