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.
pub external type StringBuilder
Functions
pub external fn append(
to: StringBuilder,
suffix: String,
) -> StringBuilder
Append a String onto the end of some StringBuilder.
Runs in constant time.
pub external fn append_builder(
to: StringBuilder,
suffix: StringBuilder,
) -> StringBuilder
Append some StringBuilder onto the end of another.
Runs in constant time.
pub external fn byte_size(StringBuilder) -> Int
Returns the size of the StringBuilder in bytes.
pub external fn concat(List(StringBuilder)) -> StringBuilder
Joins a list of builders into a single builder.
Runs in constant time.
pub external fn from_float(Float) -> StringBuilder
Creates a builder containing the textual representation of a given float.
pub external fn from_string(String) -> StringBuilder
Convert a string into a builder.
Runs in constant time.
pub external fn from_strings(List(String)) -> StringBuilder
Convert a list of strings into a builder.
Runs in constant time.
pub external fn is_empty(StringBuilder) -> Bool
Inspect a builder to determine if it is equivalent to an empty string.
Examples
> new("ok") |> is_empty
False
> new("") |> is_empty
True
> from_strings([]) |> is_empty
True
pub external fn is_equal(StringBuilder, StringBuilder) -> Bool
Compare 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"]) == new("ab")
False
> is_equal(from_strings(["a", "b"]), new("ab"))
True
pub external fn lowercase(StringBuilder) -> StringBuilder
Converts a builder to a new builder where the contents have been lowercased.
pub external fn prepend(
to: StringBuilder,
prefix: String,
) -> StringBuilder
Prepend a String onto the start of some StringBuilder.
Runs in constant time.
pub external fn prepend_builder(
to: StringBuilder,
prefix: StringBuilder,
) -> StringBuilder
Prepend some StringBuilder onto the start of another.
Runs in constant time.
pub fn replace(
in iodata: StringBuilder,
each pattern: String,
with substitute: String,
) -> StringBuilder
Replaces all instances of a pattern with a given string substitute.
pub external fn reverse(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 external fn to_string(StringBuilder) -> String
Turns an StringBuilder
into a String
This function is implemented natively by the virtual machine and is highly optimised.