gleam/string_tree

Types

StringTree

StringTree 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 tree 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 tree. Always benchmark your performance sensitive code.

pub type StringTree

Functions

append

</>

pub fn append(
  to tree: StringTree,
  suffix second: String,
) -> StringTree

Appends a String onto the end of some StringTree.

Runs in constant time.

append_tree

</>

pub fn append_tree(
  to tree: StringTree,
  suffix suffix: StringTree,
) -> StringTree

Appends some StringTree onto the end of another.

Runs in constant time.

byte_size

</>

pub fn byte_size(tree: StringTree) -> Int

Returns the size of the StringTree in bytes.

concat

</>

pub fn concat(trees: List(StringTree)) -> StringTree

Joins a list of trees into a single tree.

Runs in constant time.

from_string

</>

pub fn from_string(string: String) -> StringTree

Converts a string into a StringTree.

Runs in constant time.

from_strings

</>

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

Converts a list of strings into a StringTree.

Runs in constant time.

is_empty

</>

pub fn is_empty(tree: StringTree) -> Bool

Inspects a StringTree 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: StringTree, b: StringTree) -> Bool

Compares two string trees to determine if they have the same textual content.

Comparing two string trees 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(
  trees: List(StringTree),
  with sep: String,
) -> StringTree

Joins the given trees into a new tree separated with the given string.

lowercase

</>

pub fn lowercase(tree: StringTree) -> StringTree

Converts a StringTree to a new one where the contents have been lowercased.

new

</>

pub fn new() -> StringTree

Create an empty StringTree. Useful as the start of a pipe chaining many trees together.

prepend

</>

pub fn prepend(
  to tree: StringTree,
  prefix prefix: String,
) -> StringTree

Prepends a String onto the start of some StringTree.

Runs in constant time.

prepend_tree

</>

pub fn prepend_tree(
  to tree: StringTree,
  prefix prefix: StringTree,
) -> StringTree

Prepends some StringTree onto the start of another.

Runs in constant time.

replace

</>

pub fn replace(
  in tree: StringTree,
  each pattern: String,
  with substitute: String,
) -> StringTree

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

reverse

</>

pub fn reverse(tree: StringTree) -> StringTree

Converts a StringTree to a new one with the contents reversed.

split

</>

pub fn split(
  tree: StringTree,
  on pattern: String,
) -> List(StringTree)

Splits a StringTree on a given pattern into a list of trees.

to_string

</>

pub fn to_string(tree: StringTree) -> String

Turns a StringTree into a String

This function is implemented natively by the virtual machine and is highly optimised.

uppercase

</>

pub fn uppercase(tree: StringTree) -> StringTree

Converts a StringTree to a new one where the contents have been uppercased.