gleam/bytes_builder

BytesBuilder 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 builder 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.

BytesBuilder 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 builders 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

BytesBuilder

opaque </>

pub opaque type BytesBuilder

Functions

append

</>

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

Appends a bit array to the end of a builder.

Runs in constant time.

append_builder

</>

pub fn append_builder(
  to first: BytesBuilder,
  suffix second: BytesBuilder,
) -> BytesBuilder

Appends a builder onto the end of another.

Runs in constant time.

append_string

</>

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

Appends a string onto the end of a builder.

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

byte_size

</>

pub fn byte_size(builder: BytesBuilder) -> Int

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

Runs in linear time.

concat

</>

pub fn concat(builders: List(BytesBuilder)) -> BytesBuilder

Joins a list of builders into a single builder.

Runs in constant time.

concat_bit_arrays

</>

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

Joins a list of bit arrays into a single builder.

Runs in constant time.

from_bit_array

</>

pub fn from_bit_array(bits: BitArray) -> BytesBuilder

Creates a new builder from a bit array.

Runs in constant time.

from_string

</>

pub fn from_string(string: String) -> BytesBuilder

Creates a new builder from a string.

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

from_string_builder

</>

pub fn from_string_builder(
  builder: StringBuilder,
) -> BytesBuilder

Creates a new builder from a string builder.

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

new

</>

pub fn new() -> BytesBuilder

Create an empty BytesBuilder. Useful as the start of a pipe chaining many builders together.

prepend

</>

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

Prepends a bit array to the start of a builder.

Runs in constant time.

prepend_builder

</>

pub fn prepend_builder(
  to second: BytesBuilder,
  prefix first: BytesBuilder,
) -> BytesBuilder

Prepends a builder onto the start of another.

Runs in constant time.

prepend_string

</>

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

Prepends a string onto the start of a builder.

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

to_bit_array

</>

pub fn to_bit_array(builder: BytesBuilder) -> BitArray

Turns an builder 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.