gleam/string

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

Types

pub type String =
  String

A UtfCodepoint is the integer representation of a valid UTF codepoint

pub type UtfCodepoint =
  UtfCodepoint

Functions

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

Creates 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 string_builder module as it can append strings much faster!

Examples

> append(to: "butter", suffix: "fly")
"butterfly"
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.Lt
pub fn concat(strings: List(String)) -> String

Creates 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 string_builder module as it can append strings much faster!

Examples

> concat(["never", "the", "less"])
"nevertheless"
pub fn contains(
  does haystack: String,
  contain needle: String,
) -> Bool

Checks if the first string contains the second.

Examples

> contains(does: "theory", contain: "ory")
True

> contains(does: "theory", contain: "the")
True

> contains(does: "theory", contain: "THE")
False
pub fn crop(
  from string: String,
  before substring: String,
) -> String

Drops contents of the first string that occur before the second string. If the first string does not contain the second string, the first string is returned.

Examples

> crop(from: "The Lone Gunmen", before: "Lone")
"Lone Gunmen"
pub fn drop_left(
  from string: String,
  up_to num_graphemes: Int,
) -> String

Drops n Graphemes from the left side of a string.

Examples

> drop_left(from: "The Lone Gunmen", up_to: 2)
"e Lone Gunmen"
pub fn drop_right(
  from string: String,
  up_to num_graphemes: Int,
) -> String

Drops n Graphemes from the right side of a string.

Examples

> drop_right(from: "Cigarette Smoking Man", up_to: 2)
"Cigarette Smoking M"
pub external fn ends_with(String, String) -> Bool

Checks whether the first string ends with the second one.

Examples

> ends_with("theory", "ory")
True
pub fn is_empty(str: String) -> Bool

Determines if a string is empty.

Examples

> is_empty("")
True

> is_empty("the world")
False
pub fn join(
  strings: List(String),
  with separator: String,
) -> String

Joins many strings together with a given separator.

This function runs in linear time.

Examples

> join(["home","evan","Desktop"], with: "/")
"home/evan/Desktop"
pub external fn length(String) -> Int

Gets 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
pub external fn lowercase(String) -> String

Creates 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"
pub fn pad_left(
  string: String,
  to length: Int,
  with pad_string: String,
) -> String

Pads a string on the left until it has at least given number of Graphemes.

Examples

> pad_left("121", to: 5, with: ".")
"..121"

> pad_left("121", to: 3, with: ".")
"121"

> pad_left("121", to: 2, with: ".")
"121"
pub fn pad_right(
  string: String,
  to length: Int,
  with pad_string: String,
) -> String

Pads a string on the right until it has a given length.

Examples

> pad_right("121", to: 5, with: ".")
"121.."

> pad_right("121", to: 3, with: ".")
"121"

> pad_right("121", to: 2, with: ".")
"121"
pub external fn pop_grapheme(
  string: String,
) -> Result(#(String, String), Nil)

Splits a non-empty string into its head and tail. This lets you pattern match on strings exactly as you would with lists.

Examples

> pop_grapheme("gleam")
Ok(#("g", "leam"))

> pop_grapheme("")
Error(Nil)
pub fn repeat(string: String, times times: Int) -> String

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

This function runs in linear time.

Examples

> repeat("ha", times: 3)
"hahaha"
pub fn replace(
  in string: String,
  each pattern: String,
  with substitute: String,
) -> String

Creates 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"
pub fn reverse(string: String) -> String

Reverses a string.

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

Examples

> reverse("stressed")
"desserts"
pub fn slice(
  from string: String,
  at_index idx: Int,
  length len: Int,
) -> String

Takes a substring given a start and end Grapheme indexes. Negative indexes are taken starting from the end of the list.

Examples

> slice(from: "gleam", at_index: 1, length: 2)
"le"

> slice(from: "gleam", at_index: 1, length: 10)
"leam"

> slice(from: "gleam", at_index: 10, length: 3)
""

> slice(from: "gleam", at_index: -2, length: 2)
"am"

> slice(from: "gleam", at_index: -12, length: 2)
""
pub fn split(x: String, on substring: String) -> List(String)

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

Examples

> split("home/gleam/desktop/", on: "/")
["home", "gleam", "desktop", ""]
pub fn split_once(
  x: String,
  on substring: String,
) -> Result(#(String, String), Nil)

Splits a string a single time on the given substring.

Returns an error if substring not present.

Examples

> split_once("home/gleam/desktop/", on: "/")
Ok(#("home", "gleam/desktop/"))

> split_once("home/gleam/desktop/", on: "?")
Error(Nil)
pub external fn starts_with(String, String) -> Bool

Checks whether the first string starts with the second one.

Examples

> starts_with("theory", "ory")
False
pub fn to_graphemes(string: String) -> List(String)

Converts a string to a list of Graphemes.

> to_graphemes("abc")
["a", "b", "c"]
pub fn trim(string: String) -> String

Removes whitespace on both sides of a String.

Examples

> trim("  hats  \n")
"hats"
pub fn trim_left(string: String) -> String

Removes whitespace on the left of a String.

Examples

> trim_left("  hats  \n")
"hats  \n"
pub fn trim_right(string: String) -> String

Removes whitespace on the right of a String.

Examples

> trim_right("  hats  \n")
"  hats"
pub external fn uppercase(String) -> String

Creates 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"
pub fn utf_codepoint(value: Int) -> Result(UtfCodepoint, Nil)

Converts an integer to a UtfCodepoint

Returns an error if the integer does not represent a valid UTF codepoint.