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"

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

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

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

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

> utf_codepoint_to_int(128013) |> to_utf_codepoint_int
128013