gleam/string

Strings in Gleam are UTF-8 binaries. They can be written in your code a text surrounded by "double quotes".

Types

String

pub type String =
  String

Functions

append

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

Create a new string by joining two strings together.

This function copies both strings and runs in linear time. If you find yourself joining strings frequently consider using the iodata module as it can append strings much faster!

Examples

> append(to: "butter", suffix: "fly")
"butterfly"

compare

pub external fn compare(String, String) -> order.Order

Compares two strings to see which is "larger" by comparing their graphemes.

This does not compare the size or length of the given strings.

Examples

> compare("Anthony", "Anthony")
order.Eq

> compare("A", "B")
order.Gt

concat

pub fn concat(strings: List(String)) -> String

Create a new string by joining many strings together.

This function copies both strings and runs in linear time. If you find yourself joining strings frequently consider using the iodata module as it can append strings much faster!

Examples

> concat(["never", "the", "less"])
"nevertheless"

contains

pub fn contains(
  does haystack: String,
  contain needle: String,
) -> Bool

is_empty

pub fn is_empty(str: String) -> Bool

Determine if a string is empty.

Examples

> is_empty("")
True

> is_empty("the world")
False

join

pub fn join(
  strings: List(String),
  with separator: String,
) -> String

Join many strings together with a given separator.

This function runs in linear time.

Examples

> join(["home","evan","Desktop"], with: "/")
"home/evan/Desktop"

length

pub external fn length(String) -> Int

Get the number of grapheme clusters in a given string.

This function has to iterate across the whole string to count the number of graphemes, so it runs in linear time.

Examples

> length("Gleam")
5

> length("ß↑e̊")
3

> length("")
0

lowercase

pub external fn lowercase(String) -> String

Create a new string with all the graphemes in the input string converted to lowercase.

Useful for case-insensitive comparisons.

Examples

> lowercase("X-FILES")
"x-files"

repeat

pub fn repeat(string: String, times times: Int) -> String

Create a new string by repeating a string a given number of times.

This function runs in linear time.

Examples

> repeat("ha", times: 3)
"hahaha"

replace

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

Create a new string by replacing all occurrences of a given substring.

Examples

> replace("www.example.com", each: ".", with: "-")
"www-example-com"

> replace("a,b,c,d,e", each: ",", with: "/")
"a/b/c/d/e"

reverse

pub fn reverse(string: String) -> String

Reverse a string.

This function has to iterate across the whole string so it runs in linear time.

Examples

> reverse("stressed")
"desserts"

split

pub fn split(x: String, on substring: String) -> List(String)

Create a list of strings by splitting a given string on a given substring.

Examples

> split("home/gleam/desktop/", on: "/")
["home","gleam","desktop", ""]

uppercase

pub external fn uppercase(String) -> String

Create a new string with all the graphemes in the input string converted to uppercase.

Useful for case-insensitive comparisons and VIRTUAL YELLING.

Examples

> uppercase("skinner")
"SKINNER"