Encode an integer value as a Big-Endian (most-significant bytes first) ByteArray. The size is the expected size in number of bytes.

important

This function fails (i.e. halts the program) if the value cannot fit in the given size. When the size is too large, the array is left-padded with zeroes.

bytearray.from_int_big_endian(1_000_000, 3) == #"0f4240"
bytearray.from_int_big_endian(1_000_000, 5) == #"00000f4240"
bytearray.from_int_big_endian(0, 8) == #"0000000000000000"
bytearray.from_int_big_endian(1_000_000, 1) => 💥

Encode an integer value as a Little-Endian (least-significant bytes first) ByteArray. The size is the expected size in number of bytes.

important

This function fails (i.e. halts the program) if the value cannot fit in the given size. When the size is too large, the array is right-padded with zeroes.

bytearray.from_int_little_endian(1_000_000, 3) == #"40420f"
bytearray.from_int_little_endian(1_000_000, 5) == #"40420f0000"
bytearray.from_int_little_endian(0, 8) == #"0000000000000000"
bytearray.from_int_little_endian(1_000_000, 1) => 💥

Convert a String into a ByteArray.

bytearray.from_string(@"ABC") == #"414243"

Add a byte element in front of a ByteArray. When the given byte is greater than 255, it wraps-around. PlutusV2 behavior So 256 is mapped to 0, 257 to 1, and so forth. In PlutusV3 this will error instead of wrapping around.

bytearray.push(#"", 0) == #"00"
bytearray.push(#"0203", 1) == #"010203"
bytearray.push(#"0203", 257) == #"010203"

Get the Byte at the given index, or crash.

warning

This functions fails (i.e. halts the program) if there’s no byte at the given index.

Search the start and end positions of a sub-array in a ByteArray.

bytearray.index_of("Hello, World!", "World") == Some((7, 11))
bytearray.index_of("Hello, World!", "foo") == None
bytearray.index_of("Hello, World!", "!") == Some((12, 12))
bytearray.index_of("Hello, World!", "o") == Some((4, 4))
bytearray.index_of("Hello, World!", "Hello, World!") == Some((0, 12))

Returns True when the given ByteArray is empty.

bytearray.is_empty(#"") == True
bytearray.is_empty(#"00ff") == False

Returns the number of bytes in a ByteArray.

bytearray.length(#[1, 2, 3]) == 3

Checks whether a bit (Most-Significant-Bit first) is set in the given ‘ByteArray’.

For example, consider the following bytearray: #"8b765f". It can also be written as the following bits sequence:

And thus, we have:

test_bit(#"8b765f", 0) == True
test_bit(#"8b765f", 1) == False
test_bit(#"8b765f", 2) == False
test_bit(#"8b765f", 3) == False
test_bit(#"8b765f", 7) == True
test_bit(#"8b765f", 8) == False
test_bit(#"8b765f", 20) == True
test_bit(#"8b765f", 21) == True
test_bit(#"8b765f", 22) == True
test_bit(#"8b765f", 23) == True

Returns the suffix of a ByteArray after n elements.

bytearray.drop(#[1, 2, 3], n: 2) == #[3]

Extract a ByteArray as a slice of another ByteArray.

Indexes are 0-based and inclusive.

bytearray.slice(#[0, 1, 2, 3, 4, 5, 6], start: 1, end: 3) == #[1, 2, 3]

Returns the n-length prefix of a ByteArray.

bytearray.take(#[1, 2, 3], n: 2) == #[1, 2]

Combine two ByteArray together.

bytearray.concat(left: #[1, 2, 3], right: #[4, 5, 6]) == #[1, 2, 3, 4, 5, 6]

Compare two bytearrays lexicographically.

bytearray.compare(#"00", #"FF") == Less
bytearray.compare(#"42", #"42") == Equal
bytearray.compare(#"FF", #"00") == Greater

Left-fold over bytes of a ByteArray. Note that every byte given to the callback function is comprised between 0 and 255.

bytearray.foldl(#"acab", 0, fn(byte, acc) { acc * 256 + byte }) == 44203
bytearray.foldl(#[1, 2, 3], #"", flip(bytearray.push)) == #[3, 2, 1]

Right-fold over bytes of a ByteArray. Note that every byte given to the callback function is comprised between 0 and 255.

bytearray.foldr(#"acab", 0, fn(byte, acc) { acc * 256 + byte }) == 43948
bytearray.foldl(#[1, 2, 3], #"", flip(bytearray.push)) == #[1, 2, 3]

Reduce bytes in a ByteArray from left to right using the accumulator as left operand. Said differently, this is foldl with callback arguments swapped.

bytearray.reduce(#[1,2,3], #[], bytearray.push) == #[3, 2, 1]

Interpret a Big-Endian (most-significant bytes first) ByteArray as an Int.

bytearray.to_int_big_endian(#"0f4240") == 1_000_000
bytearray.to_int_big_endian(#"00000f4240") == 1_000_000
bytearray.to_int_big_endian(#"0000000000000000") == 0

Interpret a Little-Endian (least-significant bytes first) ByteArray as an Int.

bytearray.to_int_big_endian(#"40420f") == 1_000_000
bytearray.to_int_big_endian(#"40420f0000") == 1_000_000
bytearray.to_int_big_endian(#"0000000000000000") == 0

Convert a ByteArray into a String.

warning

This functions fails (i.e. halts the program) if the underlying ByteArray isn’t UTF-8-encoded. In particular, you cannot convert arbitrary hash digests using this function.

For converting arbitrary ByteArrays, use bytearray.to_hex.

bytearray.to_string(#"414243") == "ABC"
bytearray.to_string(some_hash) => 💥

Encode a ByteArray as a hexidecimal String.

bytearray.to_hex("Hello world!") == @"48656c6c6f20776f726c6421"

Checks whether a ByteArray starts with a given prefix.

bytearray.starts_with("Hello, World!", prefix: "Hello") == True
bytearray.starts_with("", prefix: "") == True
bytearray.starts_with("Hello", prefix: "Hello, World!") == False