gleam/iodata

Types

Iodata

Iodata 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.

Iodata 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 Iodata

Functions

append

pub external fn append(to: Iodata, suffix: String) -> Iodata

Append a String onto the end of some Iodata.

Runs in constant time.

append_iodata

pub external fn append_iodata(
  to: Iodata,
  suffix: Iodata,
) -> Iodata

Append some Iodata onto the end of another.

Runs in constant time.

byte_size

pub external fn byte_size(Iodata) -> Int

Returns the size of the Iodata in bytes.

concat

pub external fn concat(List(Iodata)) -> Iodata

Joins a list of iodata into a single iodata.

Runs in constant time.

from_float

pub external fn from_float(Float) -> Iodata

Creates textual representation of the given float as iodata.

from_strings

pub external fn from_strings(List(String)) -> Iodata

Convert a list of strings into iodata.

Runs in constant time.

is_empty

pub external fn is_empty(Iodata) -> Bool

Inspect some iodata 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

is_equal

pub external fn is_equal(Iodata, Iodata) -> Bool

Compare two pieces of iodata 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

lowercase

pub external fn lowercase(Iodata) -> Iodata

Converts Iodata to a new Iodata where valid UTF-8 string data is lowercased.

new

pub external fn new(String) -> Iodata

Convert a string into iodata.

Runs in constant time.

prepend

pub external fn prepend(to: Iodata, prefix: String) -> Iodata

Prepend a String onto the start of some Iodata.

Runs in constant time.

prepend_iodata

pub external fn prepend_iodata(
  to: Iodata,
  prefix: Iodata,
) -> Iodata

Prepend some Iodata onto the start of another.

Runs in constant time.

replace

pub fn replace(
  in iodata: Iodata,
  each pattern: String,
  with substitute: String,
) -> Iodata

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

reverse

pub external fn reverse(Iodata) -> Iodata

Converts Iodata to a new Iodata where valid UTF-8 string data is reversed.

split

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

Splits iodata on a given pattern into a list of iodata.

to_string

pub external fn to_string(Iodata) -> String

Turns an Iodata into a String

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

uppercase

pub external fn uppercase(Iodata) -> Iodata

Converts Iodata to a new Iodata where valid UTF-8 string data is uppercased.