deprecate string and bytes builder modules

5 files changed, 62 insertions, 34 deletions

diff --git a/src/gleam/bytes_builder.gleam b/src/gleam/bytes_builder.gleam
index fbed16b..e9a8fc4 100644
--- a/src/gleam/bytes_builder.gleam
+++ b/src/gleam/bytes_builder.gleam
@@ -33,6 +33,7 @@ pub opaque type BytesBuilder {
 /// Create an empty `BytesBuilder`. Useful as the start of a pipe chaining many
 /// builders together.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.new` instead.")
 pub fn new() -> BytesBuilder {
   concat([])
 }
@@ -41,6 +42,7 @@ pub fn new() -> BytesBuilder {
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.prepend` instead.")
 pub fn prepend(to second: BytesBuilder, prefix first: BitArray) -> BytesBuilder {
   append_builder(from_bit_array(first), second)
 }
@@ -49,6 +51,7 @@ pub fn prepend(to second: BytesBuilder, prefix first: BitArray) -> BytesBuilder
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.append` instead.")
 pub fn append(to first: BytesBuilder, suffix second: BitArray) -> BytesBuilder {
   append_builder(first, from_bit_array(second))
 }
@@ -57,6 +60,7 @@ pub fn append(to first: BytesBuilder, suffix second: BitArray) -> BytesBuilder {
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.prepend_tree` instead.")
 pub fn prepend_builder(
   to second: BytesBuilder,
   prefix first: BytesBuilder,
@@ -68,6 +72,7 @@ pub fn prepend_builder(
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.append_tree` instead.")
 @external(erlang, "gleam_stdlib", "iodata_append")
 pub fn append_builder(
   to first: BytesBuilder,
@@ -84,6 +89,7 @@ pub fn append_builder(
 /// Runs in constant time when running on Erlang.
 /// Runs in linear time with the length of the string otherwise.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.prepend_string` instead.")
 pub fn prepend_string(
   to second: BytesBuilder,
   prefix first: String,
@@ -96,6 +102,7 @@ pub fn prepend_string(
 /// Runs in constant time when running on Erlang.
 /// Runs in linear time with the length of the string otherwise.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.append_string` instead.")
 pub fn append_string(
   to first: BytesBuilder,
   suffix second: String,
@@ -107,6 +114,7 @@ pub fn append_string(
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.concat` instead.")
 @external(erlang, "gleam_stdlib", "identity")
 pub fn concat(builders: List(BytesBuilder)) -> BytesBuilder {
   Many(builders)
@@ -116,6 +124,7 @@ pub fn concat(builders: List(BytesBuilder)) -> BytesBuilder {
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.concat_bit_arrays` instead.")
 @external(erlang, "gleam_stdlib", "identity")
 pub fn concat_bit_arrays(bits: List(BitArray)) -> BytesBuilder {
   bits
@@ -128,6 +137,7 @@ pub fn concat_bit_arrays(bits: List(BitArray)) -> BytesBuilder {
 /// Runs in constant time when running on Erlang.
 /// Runs in linear time otherwise.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.from_string` instead.")
 @external(erlang, "gleam_stdlib", "wrap_list")
 pub fn from_string(string: String) -> BytesBuilder {
   Text(string_builder.from_string(string))
@@ -138,6 +148,7 @@ pub fn from_string(string: String) -> BytesBuilder {
 /// Runs in constant time when running on Erlang.
 /// Runs in linear time otherwise.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.from_string_tree` instead.")
 @external(erlang, "gleam_stdlib", "wrap_list")
 pub fn from_string_builder(builder: StringBuilder) -> BytesBuilder {
   Text(builder)
@@ -147,6 +158,7 @@ pub fn from_string_builder(builder: StringBuilder) -> BytesBuilder {
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.from_bit_array` instead.")
 @external(erlang, "gleam_stdlib", "wrap_list")
 pub fn from_bit_array(bits: BitArray) -> BytesBuilder {
   Bytes(bits)
@@ -159,6 +171,7 @@ pub fn from_bit_array(bits: BitArray) -> BytesBuilder {
 /// When running on Erlang this function is implemented natively by the
 /// virtual machine and is highly optimised.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.to_bit_array` instead.")
 @external(erlang, "erlang", "list_to_bitstring")
 pub fn to_bit_array(builder: BytesBuilder) -> BitArray {
   [[builder]]
@@ -193,6 +206,7 @@ fn to_list(
 ///
 /// Runs in linear time.
 ///
+@deprecated("This module has been deprecated, use `bytes_tree.byte_size` instead.")
 @external(erlang, "erlang", "iolist_size")
 pub fn byte_size(builder: BytesBuilder) -> Int {
   [[builder]]
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index b64362f..f916016 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -4,7 +4,7 @@ import gleam/int
 import gleam/list
 import gleam/option.{type Option, Some}
 import gleam/result
-import gleam/string_builder
+import gleam/string_tree
 
 /// `Dynamic` data is data that we don't know the type of yet.
 /// We likely get data like this from interop with Erlang, or from
@@ -498,8 +498,8 @@ fn at_least_decode_tuple_error(
   }
   let error =
     ["Tuple of at least ", int.to_string(size), " element", s]
-    |> string_builder.from_strings
-    |> string_builder.to_string
+    |> string_tree.from_strings
+    |> string_tree.to_string
     |> DecodeError(found: classify(data), path: [])
   Error([error])
 }
@@ -567,8 +567,8 @@ fn push_path(error: DecodeError, name: t) -> DecodeError {
     Ok(name) -> name
     Error(_) ->
       ["<", classify(name), ">"]
-      |> string_builder.from_strings
-      |> string_builder.to_string
+      |> string_tree.from_strings
+      |> string_tree.to_string
   }
   DecodeError(..error, path: [name, ..error.path])
 }
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index ddfc89f..5c9575d 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -4,7 +4,7 @@
 import gleam/list
 import gleam/option.{type Option, None, Some}
 import gleam/order
-import gleam/string_builder.{type StringBuilder}
+import gleam/string_tree.{type StringTree}
 
 /// Determines if a `String` is empty.
 ///
@@ -72,9 +72,9 @@ pub fn reverse(string: String) -> String {
 
 fn do_reverse(string: String) -> String {
   string
-  |> string_builder.from_string
-  |> string_builder.reverse
-  |> string_builder.to_string
+  |> string_tree.from_string
+  |> string_tree.reverse
+  |> string_tree.to_string
 }
 
 /// Creates a new `String` by replacing all occurrences of a given substring.
@@ -97,9 +97,9 @@ pub fn replace(
   with substitute: String,
 ) -> String {
   string
-  |> string_builder.from_string
-  |> string_builder.replace(each: pattern, with: substitute)
-  |> string_builder.to_string
+  |> string_tree.from_string
+  |> string_tree.replace(each: pattern, with: substitute)
+  |> string_tree.to_string
 }
 
 /// Creates a new `String` with all the graphemes in the input `String` converted to
@@ -369,9 +369,9 @@ pub fn split(x: String, on substring: String) -> List(String) {
     "" -> to_graphemes(x)
     _ ->
       x
-      |> string_builder.from_string
-      |> string_builder.split(on: substring)
-      |> list.map(with: string_builder.to_string)
+      |> string_tree.from_string
+      |> string_tree.split(on: substring)
+      |> list.map(with: string_tree.to_string)
   }
 }
 
@@ -415,7 +415,7 @@ fn erl_split(a: String, b: String) -> List(String)
 /// Creates a new `String` by joining two `String`s together.
 ///
 /// This function copies both `String`s and runs in linear time. If you find
-/// yourself joining `String`s frequently consider using the [`string_builder`](../gleam/string_builder.html)
+/// yourself joining `String`s frequently consider using the [`string_tree`](../gleam/string_tree.html)
 /// module as it can append `String`s much faster!
 ///
 /// ## Examples
@@ -427,15 +427,15 @@ fn erl_split(a: String, b: String) -> List(String)
 ///
 pub fn append(to first: String, suffix second: String) -> String {
   first
-  |> string_builder.from_string
-  |> string_builder.append(second)
-  |> string_builder.to_string
+  |> string_tree.from_string
+  |> string_tree.append(second)
+  |> string_tree.to_string
 }
 
 /// Creates a new `String` by joining many `String`s together.
 ///
 /// This function copies both `String`s and runs in linear time. If you find
-/// yourself joining `String`s frequently consider using the [`string_builder`](../gleam/string_builder.html)
+/// yourself joining `String`s frequently consider using the [`string_tree`](../gleam/string_tree.html)
 /// module as it can append `String`s much faster!
 ///
 /// ## Examples
@@ -447,8 +447,8 @@ pub fn append(to first: String, suffix second: String) -> String {
 ///
 pub fn concat(strings: List(String)) -> String {
   strings
-  |> string_builder.from_strings
-  |> string_builder.to_string
+  |> string_tree.from_strings
+  |> string_tree.to_string
 }
 
 /// Creates a new `String` by repeating a `String` a given number of times.
@@ -972,12 +972,12 @@ pub fn capitalise(string: String) -> String {
 ///
 pub fn inspect(term: anything) -> String {
   do_inspect(term)
-  |> string_builder.to_string
+  |> string_tree.to_string
 }
 
 @external(erlang, "gleam_stdlib", "inspect")
 @external(javascript, "../gleam_stdlib.mjs", "inspect")
-fn do_inspect(term: anything) -> StringBuilder
+fn do_inspect(term: anything) -> StringTree
 
 /// Returns the number of bytes in a `String`.
 ///
diff --git a/src/gleam/string_builder.gleam b/src/gleam/string_builder.gleam
index 8cfd2ed..f73a92f 100644
--- a/src/gleam/string_builder.gleam
+++ b/src/gleam/string_builder.gleam
@@ -21,6 +21,7 @@ pub type StringBuilder
 /// Create an empty `StringBuilder`. Useful as the start of a pipe chaining many
 /// builders together.
 ///
+@deprecated("This module has been deprecated, use `string_tree.new` instead.")
 pub fn new() -> StringBuilder {
   do_from_strings([])
 }
@@ -29,6 +30,7 @@ pub fn new() -> StringBuilder {
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.prepend` instead.")
 pub fn prepend(
   to builder: StringBuilder,
   prefix prefix: String,
@@ -40,6 +42,7 @@ pub fn prepend(
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.append` instead.")
 pub fn append(to builder: StringBuilder, suffix second: String) -> StringBuilder {
   append_builder(builder, from_string(second))
 }
@@ -48,6 +51,7 @@ pub fn append(to builder: StringBuilder, suffix second: String) -> StringBuilder
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.prepend_tree` instead.")
 pub fn prepend_builder(
   to builder: StringBuilder,
   prefix prefix: StringBuilder,
@@ -59,6 +63,7 @@ pub fn prepend_builder(
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.append_tree` instead.")
 pub fn append_builder(
   to builder: StringBuilder,
   suffix suffix: StringBuilder,
@@ -74,6 +79,7 @@ fn do_append(a: StringBuilder, b: StringBuilder) -> StringBuilder
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.from_strings` instead.")
 pub fn from_strings(strings: List(String)) -> StringBuilder {
   do_from_strings(strings)
 }
@@ -86,6 +92,7 @@ fn do_from_strings(a: List(String)) -> StringBuilder
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.concat` instead.")
 pub fn concat(builders: List(StringBuilder)) -> StringBuilder {
   do_concat(builders)
 }
@@ -98,6 +105,7 @@ fn do_concat(builders: List(StringBuilder)) -> StringBuilder
 ///
 /// Runs in constant time.
 ///
+@deprecated("This module has been deprecated, use `string_tree.from_string` instead.")
 pub fn from_string(string: String) -> StringBuilder {
   do_from_string(string)
 }
@@ -111,6 +119,7 @@ fn do_from_string(string: String) -> StringBuilder
 /// This function is implemented natively by the virtual machine and is highly
 /// optimised.
 ///
+@deprecated("This module has been deprecated, use `string_tree.to_string` instead.")
 pub fn to_string(builder: StringBuilder) -> String {
   do_to_string(builder)
 }
@@ -121,6 +130,7 @@ fn do_to_string(builder: StringBuilder) -> String
 
 /// Returns the size of the `StringBuilder` in bytes.
 ///
+@deprecated("This module has been deprecated, use `string_tree.byte_size` instead.")
 pub fn byte_size(builder: StringBuilder) -> Int {
   do_byte_size(builder)
 }
@@ -131,6 +141,7 @@ fn do_byte_size(builder: StringBuilder) -> Int
 
 /// Joins the given builders into a new builder separated with the given string
 ///
+@deprecated("This module has been deprecated, use `string_tree.join` instead.")
 pub fn join(builders: List(StringBuilder), with sep: String) -> StringBuilder {
   builders
   |> list.intersperse(from_string(sep))
@@ -140,6 +151,7 @@ pub fn join(builders: List(StringBuilder), with sep: String) -> StringBuilder {
 /// Converts a builder to a new builder where the contents have been
 /// lowercased.
 ///
+@deprecated("This module has been deprecated, use `string_tree.lowercase` instead.")
 pub fn lowercase(builder: StringBuilder) -> StringBuilder {
   do_lowercase(builder)
 }
@@ -151,6 +163,7 @@ fn do_lowercase(builder: StringBuilder) -> StringBuilder
 /// Converts a builder to a new builder where the contents have been
 /// uppercased.
 ///
+@deprecated("This module has been deprecated, use `string_tree.uppercase` instead.")
 pub fn uppercase(builder: StringBuilder) -> StringBuilder {
   do_uppercase(builder)
 }
@@ -161,6 +174,7 @@ fn do_uppercase(builder: StringBuilder) -> StringBuilder
 
 /// Converts a builder to a new builder with the contents reversed.
 ///
+@deprecated("This module has been deprecated, use `string_tree.reverse` instead.")
 pub fn reverse(builder: StringBuilder) -> StringBuilder {
   do_reverse(builder)
 }
@@ -179,6 +193,7 @@ fn do_to_graphemes(string: String) -> List(String)
 
 /// Splits a builder on a given pattern into a list of builders.
 ///
+@deprecated("This module has been deprecated, use `string_tree.split` instead.")
 pub fn split(iodata: StringBuilder, on pattern: String) -> List(StringBuilder) {
   do_split(iodata, pattern)
 }
@@ -197,6 +212,7 @@ fn erl_split(a: StringBuilder, b: String, c: Direction) -> List(StringBuilder)
 
 /// Replaces all instances of a pattern with a given string substitute.
 ///
+@deprecated("This module has been deprecated, use `string_tree.replace` instead.")
 @external(erlang, "gleam_stdlib", "string_replace")
 @external(javascript, "../gleam_stdlib.mjs", "string_replace")
 pub fn replace(
@@ -223,6 +239,7 @@ pub fn replace(
 /// // -> True
 /// ```
 ///
+@deprecated("This module has been deprecated, use `string_tree.is_equal` instead.")
 @external(erlang, "string", "equal")
 pub fn is_equal(a: StringBuilder, b: StringBuilder) -> Bool {
   a == b
@@ -247,6 +264,7 @@ pub fn is_equal(a: StringBuilder, b: StringBuilder) -> Bool {
 /// // -> True
 /// ```
 ///
+@deprecated("This module has been deprecated, use `string_tree.is_empty` instead.")
 @external(erlang, "string", "is_empty")
 pub fn is_empty(builder: StringBuilder) -> Bool {
   from_string("") == builder
diff --git a/src/gleam/uri.gleam b/src/gleam/uri.gleam
index 7af8403..75bd68c 100644
--- a/src/gleam/uri.gleam
+++ b/src/gleam/uri.gleam
@@ -14,7 +14,7 @@ import gleam/pair
 import gleam/regex
 import gleam/result
 import gleam/string
-import gleam/string_builder.{type StringBuilder}
+import gleam/string_tree.{type StringTree}
 
 /// Type representing holding the parsed components of an URI.
 /// All components of a URI are optional, except the path.
@@ -217,17 +217,13 @@ fn do_parse_query(a: String) -> Result(List(#(String, String)), Nil)
 pub fn query_to_string(query: List(#(String, String))) -> String {
   query
   |> list.map(query_pair)
-  |> list.intersperse(string_builder.from_string("&"))
-  |> string_builder.concat
-  |> string_builder.to_string
+  |> list.intersperse(string_tree.from_string("&"))
+  |> string_tree.concat
+  |> string_tree.to_string
 }
 
-fn query_pair(pair: #(String, String)) -> StringBuilder {
-  string_builder.from_strings([
-    percent_encode(pair.0),
-    "=",
-    percent_encode(pair.1),
-  ])
+fn query_pair(pair: #(String, String)) -> StringTree {
+  string_tree.from_strings([percent_encode(pair.0), "=", percent_encode(pair.1)])
 }
 
 /// Encodes a string into a percent encoded representation.