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 typically copies both Strings and runs in linear time, but the exact behaviour will depend on how the runtime you are using optimises your code. Benchmark and profile your code if you need to understand its performance better.

If you are joining together large string and want to avoid copying any data you may want to investigate using the string_tree module.

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.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: anything) -> String

Returns a String representation of a term in Gleam syntax.

is_empty

</>

pub fn is_empty(str: String) -> Bool

Determines 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

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