gleam/string_builder

Types

StringBuilder

StringBuilder is a type used for efficiently building text content to be written to a file or a socket. Internally it is represented as tree so to append or prepend to a string 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.

On Erlang this type is compatible with Erlang’s iodata. On JavaScript this type is compatible with normal strings.

The BEAM virtual machine has an optimisation for appending strings, where it will mutate the string buffer when safe to do so, so if you are looking to build a string through appending many small strings then you may get better performance by not using a string builder. Always benchmark your performance sensitive code.

pub type StringBuilder

Functions

append

</>

pub fn append(
  to builder: StringBuilder,
  suffix second: String,
) -> StringBuilder

Appends a String onto the end of some StringBuilder.

Runs in constant time.

append_builder

</>

pub fn append_builder(
  to builder: StringBuilder,
  suffix suffix: StringBuilder,
) -> StringBuilder

Appends some StringBuilder onto the end of another.

Runs in constant time.

byte_size

</>

pub fn byte_size(builder: StringBuilder) -> Int

Returns the size of the StringBuilder in bytes.

concat

</>

pub fn concat(builders: List(StringBuilder)) -> StringBuilder

Joins a list of builders into a single builder.

Runs in constant time.

from_string

</>

pub fn from_string(string: String) -> StringBuilder

Converts a string into a builder.

Runs in constant time.

from_strings

</>

pub fn from_strings(strings: List(String)) -> StringBuilder

Converts a list of strings into a builder.

Runs in constant time.

is_empty

</>

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

is_equal

</>

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

join

</>

pub fn join(
  builders: List(StringBuilder),
  with sep: String,
) -> StringBuilder

Joins the given builders into a new builder separated with the given string

lowercase

</>

pub fn lowercase(builder: StringBuilder) -> StringBuilder

Converts a builder to a new builder where the contents have been lowercased.

new

</>

pub fn new() -> StringBuilder

Create an empty StringBuilder. Useful as the start of a pipe chaining many builders together.

prepend

</>

pub fn prepend(
  to builder: StringBuilder,
  prefix prefix: String,
) -> StringBuilder

Prepends a String onto the start of some StringBuilder.

Runs in constant time.

prepend_builder

</>

pub fn prepend_builder(
  to builder: StringBuilder,
  prefix prefix: StringBuilder,
) -> StringBuilder

Prepends some StringBuilder onto the start of another.

Runs in constant time.

replace

</>

pub fn replace(
  in builder: StringBuilder,
  each pattern: String,
  with substitute: String,
) -> StringBuilder

Replaces all instances of a pattern with a given string substitute.

reverse

</>

pub fn reverse(builder: StringBuilder) -> StringBuilder

Converts a builder to a new builder with the contents reversed.

split

</>

pub fn split(
  iodata: StringBuilder,
  on pattern: String,
) -> List(StringBuilder)

Splits a builder on a given pattern into a list of builders.

to_string

</>

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.

uppercase

</>

pub fn uppercase(builder: StringBuilder) -> StringBuilder

Converts a builder to a new builder where the contents have been uppercased.