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_builder 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(s: 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_builder 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_left

</>

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"

drop_right

</>

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"

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(s: 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), Ok(b), Ok(c)) = #(
>     utf_codepoint(97),
>     utf_codepoint(98),
>     utf_codepoint(99),
>   )
>   [a, b, c]
> }
> |> from_utf_codepoints
"abc"

inspect

</>

pub fn inspect(term: a) -> 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(s: 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_left

</>

pub fn pad_left(
  string: String,
  to desired_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"

pad_right

</>

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

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

Examples

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

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

> pad_right("123", to: 2, with: ".")
"123"

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.

Note on JavaScript using the function to iterate over a string will likely be slower than using to_graphemes due to string slicing being more expensive on JavaScript than Erlang.

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(
  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)

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(s: 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.

Examples

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

trim_left

</>

pub fn trim_left(string: String) -> String

Removes whitespace on the left of a String.

Examples

> trim_left("  hats  \n")
"hats  \n"

trim_right

</>

pub fn trim_right(string: String) -> String

Removes whitespace on the right of a String.

Examples

> trim_right("  hats  \n")
"  hats"

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