gleam/string - gleam

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"

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 first string does not contain the second string, the first string is returned.

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

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"

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("121", to: 5, with: ".")
"121.."

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

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

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)

Convert a string into an optional string where an empty string becomes None.

Examples

> to_option("")
None

> to_option("")
None

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.