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
Deprecated: The `bytes_builder` module has been deprecated, use the `bytes_tree.BytesTree` type instead.
@deprecated("The `bytes_builder` module has been deprecated, use the `bytes_tree.BytesTree` type instead.")
pub type BytesBuilder =
BytesTreeFunctions
pub fn append(
to first: BytesTree,
suffix second: BitArray,
) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.append` instead.
Appends a bit array to the end of a builder.
Runs in constant time.
pub fn append_builder(
to first: BytesTree,
suffix second: BytesTree,
) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.append_tree` instead.
Appends a builder onto the end of another.
Runs in constant time.
pub fn append_string(
to first: BytesTree,
suffix second: String,
) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.append_string` instead.
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: BytesTree) -> IntDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.byte_size` instead.
Returns the size of the builder’s content in bytes.
Runs in linear time.
pub fn concat(builders: List(BytesTree)) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.concat` instead.
Joins a list of builders into a single builder.
Runs in constant time.
pub fn concat_bit_arrays(bits: List(BitArray)) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.concat_bit_arrays` instead.
Joins a list of bit arrays into a single builder.
Runs in constant time.
pub fn from_bit_array(bits: BitArray) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.from_bit_array` instead.
Creates a new builder from a bit array.
Runs in constant time.
pub fn from_string(string: String) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.from_string` instead.
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: StringTree) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.from_string_tree` instead.
Creates a new builder from a string builder.
Runs in constant time when running on Erlang. Runs in linear time otherwise.
pub fn new() -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.new` instead.
Create an empty BytesBuilder. Useful as the start of a pipe chaining many
builders together.
pub fn prepend(
to second: BytesTree,
prefix first: BitArray,
) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.prepend` instead.
Prepends a bit array to the start of a builder.
Runs in constant time.
pub fn prepend_builder(
to second: BytesTree,
prefix first: BytesTree,
) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.prepend_tree` instead.
Prepends a builder onto the start of another.
Runs in constant time.
pub fn prepend_string(
to second: BytesTree,
prefix first: String,
) -> BytesTreeDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.prepend_string` instead.
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_array(builder: BytesTree) -> BitArrayDeprecated: The `bytes_builder` module has been deprecated, use `bytes_tree.to_bit_array` instead.
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.