gleam/string · gleam_stdlib

append

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_tree module as it can append Strings much faster!

Examples

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

byte_size

</>

pub fn byte_size(string: String) -> Int

Returns the number of bytes in a String.

This function runs in constant time on Erlang and in linear time on JavaScript.

Examples

byte_size("🏳️‍⚧️🏳️‍🌈👩🏾‍❤️‍👨🏻")
// -> 58

capitalise

</>

pub fn capitalise(string: String) -> String

Creates a new String with the first grapheme in the input String converted to uppercase and the remaining graphemes to lowercase.

Examples

capitalise("mamouna")
// -> "Mamouna"

compare

</>

pub fn compare(a: String, b: String) -> 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

concat

</>

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

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

crop

</>

pub fn crop(
  from string: String,
  before substring: String,
) -> String

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

Examples

crop(from: "The Lone Gunmen", before: "Lone")
// -> "Lone Gunmen"

drop_end

</>

pub fn drop_end(
  from string: String,
  up_to num_graphemes: Int,
) -> String

Drops n graphemes from the end of a String.

Examples

drop_end(from: "Cigarette Smoking Man", up_to: 2)
// -> "Cigarette Smoking M"

drop_start

</>

pub fn drop_start(
  from string: String,
  up_to num_graphemes: Int,
) -> String

Drops n graphemes from the start of a String.

Examples

drop_start(from: "The Lone Gunmen", up_to: 2)
// -> "e Lone Gunmen"

ends_with

</>

pub fn ends_with(string: String, suffix: String) -> Bool

Checks whether the first String ends with the second one.

Examples

ends_with("theory", "ory")
// -> True

first

</>

pub fn first(string: String) -> Result(String, Nil)

Returns the first grapheme cluster in a given String and wraps it in a Result(String, Nil). If the String is empty, it returns Error(Nil). Otherwise, it returns Ok(String).

Examples

first("")
// -> Error(Nil)

first("icecream")
// -> Ok("i")

from_utf_codepoints

</>

pub fn from_utf_codepoints(
  utf_codepoints: List(UtfCodepoint),
) -> String

Converts a List of UtfCodepoints to a String.

See https://en.wikipedia.org/wiki/Code_point and https://en.wikipedia.org/wiki/Unicode#Codespace_and_Code_Points for an explanation on code points.

Examples

let assert Ok(a) = utf_codepoint(97)
let assert Ok(b) = utf_codepoint(98)
let assert Ok(c) = utf_codepoint(99)
from_utf_codepoints([a, b, c])
// -> "abc"

inspect

</>

pub fn inspect(term: a) -> String

Returns a String representation of a term in Gleam syntax.

Examples

is_empty("")
// -> True

is_empty("the world")
// -> False

join

</>

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"

last

</>

pub fn last(string: String) -> Result(String, Nil)

Returns the last grapheme cluster in a given String and wraps it in a Result(String, Nil). If the String is empty, it returns Error(Nil). Otherwise, it returns Ok(String).

Examples

last("")
// -> Error(Nil)

last("icecream")
// -> Ok("m")

length

</>

pub fn length(string: 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

lowercase

</>

pub fn lowercase(string: 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"

pad_end

</>

pub fn pad_end(
  string: String,
  to desired_length: Int,
  with pad_string: String,
) -> String

Pads the end of a String until it has a given length.

Examples

pad_end("123", to: 5, with: ".")
// -> "123.."

pad_end("123", to: 3, with: ".")
// -> "123"

pad_end("123", to: 2, with: ".")
// -> "123"

pad_start

</>

pub fn pad_start(
  string: String,
  to desired_length: Int,
  with pad_string: String,
) -> String

Pads the start of a String until it has a given length.

Examples

pad_start("121", to: 5, with: ".")
// -> "..121"

pad_start("121", to: 3, with: ".")
// -> "121"

pad_start("121", to: 2, with: ".")
// -> "121"

pop_grapheme

</>

pub fn pop_grapheme(
  string: String,
) -> Result(#(String, String), Nil)

Splits a non-empty String into its first element (head) and rest (tail). This lets you pattern match on Strings exactly as you would with lists.

Performance

There is a notable overhead to using this function, so you may not want to use it in a tight loop. If you wish to efficiently parse a string you may want to use alternatives such as the splitter package.

Examples

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

pop_grapheme("")
// -> Error(Nil)

repeat

</>

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"

replace

</>

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"

reverse

</>

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"

slice

</>

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

Takes a substring given a start grapheme index and a length. 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)
// -> ""

split

</>

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", ""]

split_once

</>

pub fn split_once(
  string: 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)

starts_with

</>

pub fn starts_with(string: String, prefix: String) -> Bool

Checks whether the first String starts with the second one.

Examples

starts_with("theory", "ory")
// -> False

to_graphemes

</>

pub fn to_graphemes(string: String) -> List(String)

Converts a String to a list of graphemes.

to_graphemes("abc")
// -> ["a", "b", "c"]

to_option

</>

pub fn to_option(string: String) -> Option(String)

Converts a String into Option(String) where an empty String becomes None.

Examples

to_option("")
// -> None

to_option("hats")
// -> Some("hats")

to_utf_codepoints

</>

pub fn to_utf_codepoints(string: String) -> List(UtfCodepoint)

Converts a String to a List of UtfCodepoint.

See https://en.wikipedia.org/wiki/Code_point and https://en.wikipedia.org/wiki/Unicode#Codespace_and_Code_Points for an explanation on code points.

Examples

"a" |> to_utf_codepoints
// -> [UtfCodepoint(97)]

// Semantically the same as:
// ["🏳", "️", "‍", "🌈"] or:
// [waving_white_flag, variant_selector_16, zero_width_joiner, rainbow]
"🏳️‍🌈" |> to_utf_codepoints
// -> [
//   UtfCodepoint(127987),
//   UtfCodepoint(65039),
//   UtfCodepoint(8205),
//   UtfCodepoint(127752),
// ]

trim

</>

pub fn trim(string: String) -> String

Removes whitespace on both sides of a String.

Whitespace in this function is the set of nonbreakable whitespace codepoints, defined as Pattern_White_Space in Unicode Standard Annex #31.

Examples

trim("  hats  \n")
// -> "hats"

trim_end

</>

pub fn trim_end(string: String) -> String

Removes whitespace at the end of a String.

Examples

trim_end("  hats  \n")
// -> "  hats"

trim_start

</>

pub fn trim_start(string: String) -> String

Removes whitespace at the start of a String.

Examples

trim_start("  hats  \n")
// -> "hats  \n"

uppercase

</>

pub fn uppercase(string: 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"

utf_codepoint

</>

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.

utf_codepoint_to_int

</>

pub fn utf_codepoint_to_int(cp: UtfCodepoint) -> Int

Converts an UtfCodepoint to its ordinal code point value.

Examples

let assert [utf_codepoint, ..] = to_utf_codepoints("💜")
utf_codepoint_to_int(utf_codepoint)
// -> 128156