gleam/bit_builder

BitBuilder is a type used for efficiently concatenating bits to create bit strings.

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

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

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

Types

pub external type BitBuilder

Functions

pub fn append(to: BitBuilder, suffix: BitString) -> BitBuilder

Appends a bit string to the end of a builder.

Runs in constant time.

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

Appends a builder onto the end of another.

Runs in constant time.

pub fn append_string(to: BitBuilder, suffix: String) -> BitBuilder

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.

pub fn byte_size(builder: BitBuilder) -> Int

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

Runs in linear time.

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

Joins a list of builders into a single builders.

Runs in constant time.

pub fn from_bit_string(bits: BitString) -> BitBuilder

Creates a new builder from a bit string.

Runs in constant time.

pub fn from_string(string: String) -> BitBuilder

Creates a new builder from a string.

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

pub fn from_string_builder(builder: StringBuilder) -> BitBuilder

Creates a new builder from a string builder.

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

pub fn new() -> BitBuilder

Create an empty BitBuilder. Useful as the start of a pipe chaning many builders together.

pub fn prepend(to: BitBuilder, prefix: BitString) -> BitBuilder

Prepends a bit string to the start of a builder.

Runs in constant time.

pub fn prepend_builder(to: BitBuilder, prefix: BitBuilder) -> BitBuilder

Prepends a builder onto the start of another.

Runs in constant time.

pub fn prepend_string(to: BitBuilder, prefix: String) -> BitBuilder

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.

pub fn to_bit_string(builder: BitBuilder) -> BitString

Turns an builder into a bit string.

Runs in linear time.

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