gleam/string_builder
Types
StringBuilder
is a type used for efficiently building strings.
When we append one string to another the 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 strings together.
StringBuilder
is different in that it can be joined together in constant time
using minimal memory, and then can be efficiently converted to a string
using the to_string
function.
On Erlang this type is compatible with Erlang’s iodata. On JavaScript this type is compatible with normal strings.
pub type StringBuilder
Functions
pub fn append(
to builder: StringBuilder,
suffix second: String,
) -> StringBuilder
Appends a String
onto the end of some StringBuilder
.
Runs in constant time.
pub fn append_builder(
to builder: StringBuilder,
suffix suffix: StringBuilder,
) -> StringBuilder
Appends some StringBuilder
onto the end of another.
Runs in constant time.
pub fn byte_size(builder: StringBuilder) -> Int
Returns the size of the StringBuilder
in bytes.
pub fn concat(builders: List(StringBuilder)) -> StringBuilder
Joins a list of builders into a single builder.
Runs in constant time.
pub fn from_string(string: String) -> StringBuilder
Converts a string into a builder.
Runs in constant time.
pub fn from_strings(strings: List(String)) -> StringBuilder
Converts a list of strings into a builder.
Runs in constant time.
pub fn is_empty(builder: StringBuilder) -> Bool
Inspects a builder to determine if it is equivalent to an empty string.
Examples
from_string("ok") |> is_empty
// -> False
from_string("") |> is_empty
// -> True
from_strings([]) |> is_empty
// -> True
pub fn is_equal(a: StringBuilder, b: StringBuilder) -> Bool
Compares two builders to determine if they have the same textual content.
Comparing two iodata using the ==
operator may return False
even if they
have the same content as they may have been build in different ways, so
using this function is often preferred.
Examples
from_strings(["a", "b"]) == from_string("ab")
// -> False
is_equal(from_strings(["a", "b"]), from_string("ab"))
// -> True
pub fn join(
builders: List(StringBuilder),
with sep: String,
) -> StringBuilder
Joins the given builders into a new builder separated with the given string
pub fn lowercase(builder: StringBuilder) -> StringBuilder
Converts a builder to a new builder where the contents have been lowercased.
pub fn new() -> StringBuilder
Create an empty StringBuilder
. Useful as the start of a pipe chaining many
builders together.
pub fn prepend(
to builder: StringBuilder,
prefix prefix: String,
) -> StringBuilder
Prepends a String
onto the start of some StringBuilder
.
Runs in constant time.
pub fn prepend_builder(
to builder: StringBuilder,
prefix prefix: StringBuilder,
) -> StringBuilder
Prepends some StringBuilder
onto the start of another.
Runs in constant time.
pub fn replace(
in builder: StringBuilder,
each pattern: String,
with substitute: String,
) -> StringBuilder
Replaces all instances of a pattern with a given string substitute.
pub fn reverse(builder: StringBuilder) -> StringBuilder
Converts a builder to a new builder with the contents reversed.
pub fn split(
iodata: StringBuilder,
on pattern: String,
) -> List(StringBuilder)
Splits a builder on a given pattern into a list of builders.
pub fn to_string(builder: StringBuilder) -> String
Turns an StringBuilder
into a String
This function is implemented natively by the virtual machine and is highly optimised.