gleam/bytes_tree

BytesTree is a type used for efficiently building binary content to be written to a file or a socket. Internally it is represented as tree so to append or prepend to a bytes tree is a constant time operation that allocates a new node in the tree without copying any of the content. When writing to an output stream the tree is traversed and the content is sent directly rather than copying it into a single buffer beforehand.

If we append one bit array to another the bit arrays must be copied to a new location in memory so that they can sit together. This behaviour enables efficient reading of the data but copying can be expensive, especially if we want to join many bit arrays together.

BytesTree is different in that it can be joined together in constant time using minimal memory, and then can be efficiently converted to a bit array using the to_bit_array function.

Byte trees are always byte aligned, so that a number of bits that is not divisible by 8 will be padded with 0s.

On Erlang this type is compatible with Erlang’s iolists.

Types

BytesTree

opaque </>

pub opaque type BytesTree

Functions

append

</>

pub fn append(
  to first: BytesTree,
  suffix second: BitArray,
) -> BytesTree

Appends a bit array to the end of a bytes tree.

Runs in constant time.

append_string

</>

pub fn append_string(
  to first: BytesTree,
  suffix second: String,
) -> BytesTree

Appends a string onto the end of a bytes tree.

Runs in constant time when running on Erlang. Runs in linear time with the length of the string otherwise.

append_tree

</>

pub fn append_tree(
  to first: BytesTree,
  suffix second: BytesTree,
) -> BytesTree

Appends a bytes tree onto the end of another.

Runs in constant time.

byte_size

</>

pub fn byte_size(tree: BytesTree) -> Int

Returns the size of the bytes tree’s content in bytes.

Runs in linear time.

concat

</>

pub fn concat(trees: List(BytesTree)) -> BytesTree

Joins a list of bytes trees into a single one.

Runs in constant time.

concat_bit_arrays

</>

pub fn concat_bit_arrays(bits: List(BitArray)) -> BytesTree

Joins a list of bit arrays into a single bytes tree.

Runs in constant time.

from_bit_array

</>

pub fn from_bit_array(bits: BitArray) -> BytesTree

Creates a new bytes tree from a bit array.

Runs in constant time.

from_string

</>

pub fn from_string(string: String) -> BytesTree

Creates a new bytes tree from a string.

Runs in constant time when running on Erlang. Runs in linear time otherwise.

from_string_tree

</>

pub fn from_string_tree(tree: StringTree) -> BytesTree

Creates a new bytes tree from a string tree.

Runs in constant time when running on Erlang. Runs in linear time otherwise.

new

</>

pub fn new() -> BytesTree

Create an empty BytesTree. Useful as the start of a pipe chaining many trees together.

prepend

</>

pub fn prepend(
  to second: BytesTree,
  prefix first: BitArray,
) -> BytesTree

Prepends a bit array to the start of a bytes tree.

Runs in constant time.

prepend_string

</>

pub fn prepend_string(
  to second: BytesTree,
  prefix first: String,
) -> BytesTree

Prepends a string onto the start of a bytes tree.

Runs in constant time when running on Erlang. Runs in linear time with the length of the string otherwise.

prepend_tree

</>

pub fn prepend_tree(
  to second: BytesTree,
  prefix first: BytesTree,
) -> BytesTree

Prepends a bytes tree onto the start of another.

Runs in constant time.

to_bit_array

</>

pub fn to_bit_array(tree: BytesTree) -> BitArray

Turns a bytes tree into a bit array.

Runs in linear time.

When running on Erlang this function is implemented natively by the virtual machine and is highly optimised.