gleam/string
Strings in Gleam are UTF-8 binaries. They can be written in your code a
text surrounded by "double quotes".
Types
String
pub type String = String
UtfCodepoint
A UtfCodepoint is the integer representation of a valid UTF codepoint
pub type UtfCodepoint = UtfCodepoint
Functions
append
pub fn append(to first: String, suffix second: String) -> String
Create 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 external fn compare(String, 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.Gt
concat
pub fn concat(strings: List(String)) -> String
Create 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
Check 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
drop_left
pub fn drop_left( from string: String, up_to num_graphemes: Int, ) -> String
Drop 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
Drop 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 external fn ends_with(String, String) -> Bool
See if the first string ends with the second one.
Examples
> ends_with("theory", "ory")
True
is_empty
pub fn is_empty(str: String) -> Bool
Determine 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
Join many strings together with a given separator.
This function runs in linear time.
Examples
> join(["home","evan","Desktop"], with: "/")
"home/evan/Desktop"
length
pub external fn length(String) -> Int
Get 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 external fn lowercase(String) -> String
Create 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 length: Int, with pad_string: String, ) -> String
Pad 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 length: Int, with pad_string: String, ) -> String
Pad 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 external fn pop_grapheme( string: String, ) -> Result(tuple(String, String), Nil)
Split 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(tuple("g", "leam"))
> pop_grapheme("")
Error(Nil)
repeat
pub fn repeat(string: String, times times: Int) -> String
Create 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
Create 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
Reverse 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
Take 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)
Create 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(tuple(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(tuple("home", "gleam/desktop/"))
> split_once("home/gleam/desktop/", on: "?")
Error(Nil)
starts_with
pub external fn starts_with(String, String) -> Bool
See if the first string starts with the second one.
Examples
> starts_with("theory", "ory")
False
to_graphemes
pub fn to_graphemes(string: String) -> List(String)
Convert a string to a list of Graphemes.
> to_graphemes("abc")
["a", "b", "c"]
trim
pub fn trim(string: String) -> String
Get rid of whitespace on both sides of a String.
Examples
> trim(" hats \n")
"hats"
trim_left
pub fn trim_left(string: String) -> String
Get rid of whitespace on the left of a String.
Examples
> trim_left(" hats \n")
"hats \n"
trim_right
pub fn trim_right(string: String) -> String
Get rid of whitespace on the right of a String.
Examples
> trim_right(" hats \n")
" hats"
uppercase
pub external fn uppercase(String) -> String
Create 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)
Convert an integer to a UtfCodepoint
Returns an error if the integer does not represent a valid UTF codepoint.