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
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 iodata 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 iodata 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", ""]
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"