BitBuilder

2 files changed, 91 insertions, 2 deletions

diff --git a/src/gleam/bit_builder.gleam b/src/gleam/bit_builder.gleam
new file mode 100644
index 0000000..c3c88b0
--- /dev/null
+++ b/src/gleam/bit_builder.gleam
@@ -0,0 +1,90 @@
+import gleam/bit_string.{BitString}
+
+/// 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.
+///
+pub external type BitBuilder
+
+/// Prepend a bit string to the start of a builder.
+///
+/// Runs in constant time.
+///
+pub external fn prepend(to: BitBuilder, prefix: BitString) -> BitBuilder =
+  "gleam_stdlib" "iodata_prepend"
+
+/// Append a bit string to the end of a builder.
+///
+/// Runs in constant time.
+///
+pub external fn append(to: BitBuilder, suffix: BitString) -> BitBuilder =
+  "gleam_stdlib" "iodata_append"
+
+/// Prepend a builder onto the start of another.
+///
+/// Runs in constant time.
+///
+pub external fn prepend_builder(
+  to: BitBuilder,
+  prefix: BitBuilder,
+) -> BitBuilder =
+  "gleam_stdlib" "iodata_prepend"
+
+/// Append a builder onto the end of another.
+///
+/// Runs in constant time.
+///
+pub external fn append_builder(
+  to: BitBuilder,
+  suffix: BitBuilder,
+) -> BitBuilder =
+  "gleam_stdlib" "iodata_append"
+
+/// Prepend a string onto the start of a builder.
+///
+/// Runs in constant time.
+///
+pub external fn prepend_string(to: BitBuilder, prefix: String) -> BitBuilder =
+  "gleam_stdlib" "iodata_prepend"
+
+/// Append a string onto the end of a builder.
+///
+/// Runs in constant time.
+///
+pub external fn append_string(to: BitBuilder, suffix: String) -> BitBuilder =
+  "gleam_stdlib" "iodata_append"
+
+/// Joins a list of builders into a single builders.
+///
+/// Runs in constant time.
+///
+pub external fn concat(List(BitBuilder)) -> BitBuilder =
+  "gleam_stdlib" "identity"
+
+/// Create a new builder from a bit string.
+///
+/// Runs in constant time.
+///
+pub external fn from_bit_string(BitString) -> BitBuilder =
+  "gleam_stdlib" "identity"
+
+/// Turns an builder into a bit string.
+///
+/// This function is implemented natively by the virtual machine and is highly
+/// optimised.
+///
+pub external fn to_bit_string(BitBuilder) -> BitString =
+  "erlang" "list_to_bitstring"
+
+/// Returns the size of the builder's content in bytes.
+///
+pub external fn byte_size(BitBuilder) -> Int =
+  "erlang" "iolist_size"
diff --git a/src/gleam/bit_string.gleam b/src/gleam/bit_string.gleam
index 1176418..99d91b1 100644
--- a/src/gleam/bit_string.gleam
+++ b/src/gleam/bit_string.gleam
@@ -2,8 +2,7 @@
 //// The BitString type should be used instead of a String type when not utf8
 //// encoded.
 
-// TODO: determine which of these functions once we have bit string syntax
-pub external type BitString
+pub type BitString = BitString
 
 /// Convert a utf8 String type into a raw BitString type.
 ///