Documentation of stdlib functions, with forward looking API

string.gleam

/// A built-in representation for efficient string manipulation. String literals
/// are enclosed in `"double quotes"`.
///
import gleam/iodata
import gleam/list
import gleam/order




/// ## Basics




/// Determine if a string is empty.
///
/// > is_empty("") == True
/// > isEmpty("the world") == False
///
pub fn is_empty(str: String) -> Bool {
  case str {
    "" -> True
    _ -> False
  }
}


/// Get the length of a 
///
/// > length("innumerable") == 11
/// > length("") == 0
///
pub external fn length(String) -> Int = "string" "length"


/// Repeat a string `n` times.
///
/// > repeat(3, "ha") == "hahaha"
///
pub fn repeat(string: String, times: Int) -> String {}


/// Reverse a string.
///
/// > reverse("stressed") == "desserts"
///
pub fn reverse(string) {
  string
  |> iodata.new
  |> iodata.reverse
  |> iodata.to_string
}


/// Replace all occurrences of some substring.
///
/// > replace("Json.Decode.succeed", all: ".", with: "-") == "Json-Decode-succeed"
/// > replace("a,b,c,d,e", all: ",", with: "/")           == "a/b/c/d/e"
pub fn replace(in string, all pattern, with substitute) {
  string
  |> iodata.new
  |> iodata.replace(_, all: pattern, with: substitute)
  |> iodata.to_string
}


/// Convert a string to all lower case. Useful for case-insensitive comparisons.
///
/// > lowercase("X-FILES") == "x-files"
/// 
pub external fn lowercase(String) -> String = "string" "lowercase"


/// Convert a string to all upper case. Useful for case-insensitive comparisons
/// and VIRTUAL YELLING.
///
/// > uppercase("skinner") == "SKINNER"
/// 
pub external fn uppercase(String) -> String = "string" "uppercase"


/// Determines the order of the two strings.
///
/// > compare("Billy", "Anthony") == order.Gt
/// > compare("Anthony", "Billy") == order.Lt
/// > compare("Anthony", "Anthony") == order.Eq
///
pub external fn compare(String, String) -> order.Order =
  "gleam_stdlib" "compare_strings"





/// ## Get Substrings




/// Take a substring given a start and end index. Negative indexes
/// are taken starting from the *end* of the list.
///
/// > slice(start: 7, end: 9, "snakes on a plane!") == "on"
/// > slice(start: 0, end: 6, "snakes on a plane!") == "snakes"
/// > slice(start: 0, end: -7, "snakes on a plane!") == "snakes on a"
/// > slice(start: -6, end: -1, "snakes on a plane!") == "plane"
/// 
pub fn slice(string: String, start: Int, end: Int) -> String {}


/// Take *n* characters from the left side of a 
///
/// > left(num: 2, string: "Mulder") == "Mu"
/// 
pub fn left(string: String, num n: Int) -> String {}


/// Take *n* characters from the right side of a 
///
/// > right 2 "Scully" == "ly"
/// 
pub fn right(num_characters: Int, string: String) -> String {}


/// Drop *n* characters from the left side of a 
///
/// > dropLeft 2 "The Lone Gunmen" == "e Lone Gunmen"
/// 
pub fn drop_left(num_characters: Int, string: String) -> String {}


/// Drop *n* characters from the right side of a 
///
/// > dropRight 2 "Cigarette Smoking Man" == "Cigarette Smoking M"
/// 
pub fn drop_right(num_characters: Int, string: String) -> String {}




/// ## Check for Substrings




/// See if the second string contains the first one.
///
/// > contains "the" "theory" == True
/// > contains "hat" "theory" == False
/// > contains "THE" "theory" == False
///
pub fn contains(this: String, in: String) -> String {}


/// See if the second string starts with the first one.
///
/// > startsWith "the" "theory" == True
/// > startsWith "ory" "theory" == False
///
pub fn starts_with(this: String, in: String) -> String {}


/// See if the second string ends with the first one.
///
/// > endsWith "the" "theory" == False
/// > endsWith "ory" "theory" == True
/// 
pub fn ends_with(this: String, in: String) -> String {}




/// ## Building and Splitting




/// Split a string using a given separator.
///
/// > split("cat,dog,cow", on: ",")        == ["cat","dog","cow"]
/// > split("home/evan/Desktop/", on: "/") == ["home","evan","Desktop", ""]
/// 
pub fn split(string x: String, on pattern: String) -> List(String) {
  x
  |> iodata.new
  |> iodata.split(_, on: pattern)
  |> list.map(_, with: iodata.to_string)
}


/// Append two strings.
///
/// > append(to: "butter", suffix: "fly") == "butterfly"
///
pub fn append(to first: String, suffix second: String) -> String {
  first
  |> iodata.new
  |> iodata.append(_, second)
  |> iodata.to_string
}


/// Concatenate many strings into one.
///
/// > concat ["never","the","less"] == "nevertheless"
///
pub fn concat(strings: List(String)) -> String {}


/// Put many strings together with a given separator.
///
/// > join "a" ["H","w","ii","n"]        == "Hawaiian"
/// > join " " ["cat","dog","cow"]       == "cat dog cow"
/// > join "/" ["home","evan","Desktop"] == "home/evan/Desktop"
///
pub fn join(seperator: String, chunks: List(String)) -> String {}


/// Break a string into words, splitting on chunks of whitespace.
///
/// > words("How are \t you? \n Good?") == ["How","are","you?","Good?"]
/// 
pub fn words(string: String) -> List(String) {}


/// Break a string into lines, splitting on newlines.
///
/// > lines("How are you?\nGood?") == ["How are you?", "Good?"]
/// 
pub fn lines(string: String): List(String) {}


/// Get all of the indexes for a substring in another 
///
/// > indexes "i" "Mississippi"   == [1,4,7,10]
/// > indexes "ss" "Mississippi"  == [2,5]
/// > indexes "needle" "haystack" == []
///
pub fn indexes(of: String, in: String) -> String {}




/// ## Formatting




/// Pad a string on both sides until it has a given length.
///
/// > pad 5 ' ' "1"   == "  1  "
/// > pad 5 ' ' "11"  == "  11 "
/// > pad 5 ' ' "121" == " 121 "
///
pub fn pad(size: Int, with: String, string: String) -> String {}


/// Pad a string on the left until it has a given length.
///
/// > padLeft 5 '.' "1"   == "....1"
/// > padLeft 5 '.' "11"  == "...11"
/// > padLeft 5 '.' "121" == "..121"
///
pub fn pad_left(size: Int, with: String, string: String) {}


/// Pad a string on the right until it has a given length.
///
/// > padRight 5 '.' "1"   == "1...."
/// > padRight 5 '.' "11"  == "11..."
/// > padRight 5 '.' "121" == "121.."
///
pub fn pad_right(size: Int, with: String, string: String) {}


/// Get rid of whitespace on both sides of a 
///
/// > trim "  hats  \n" == "hats"
///
pub fn trim(string: String) -> String {}


/// Get rid of whitespace on the left of a 
///
/// > trimLeft "  hats  \n" == "hats  \n"
///
pub fn trim_left(string: String) -> String {}


/// Get rid of whitespace on the right of a 
///
/// > trimRight "  hats  \n" == "  hats"
///
pub fn trim_right(string: String) -> String {}



/// ## Numeric Conversions




/// Try to convert a string into an int, failing on improperly formatted strings.
///
/// > to_int("123") == Ok(123)
/// > to_int("-42") == Ok(-42)
/// > to_int("3.1") == Error(Nil)
/// > to_int("31a") == Error(Nil)
///
pub fn to_int(string: String) -> Result(Int, Nil) {}


/// Convert an `Int` to a `String`.
///
/// > from_int(123) == "123"
/// > from_int(-42) == "-42"
///
pub fn from_int(int: Int) -> String {}


/// Try to convert a string into a float, failing on improperly formatted strings.
///
/// > to_float("123") == Ok(123.0)
/// > to_float("-42") == Ok(-42.0)
/// > to_float("3.1") == Ok(3.1)
/// > to_float("31a") == Error(Nil)
///
pub fn to_float(string: String) -> Result(Float, Nil) {}


/// Convert a `Float` to a `String`.
///
/// > from_float(123) == "123"
/// > from_float(-42) == "-42"
/// > from_float(3.9) == "3.9"
///
pub fn from_float(float: Float) -> String {}





/// ## List Conversions




/// Convert a string to a list of characters.
///
/// > to_list("abc") == ['a','b','c']
/// > to_list("🙈🙉🙊") == ['🙈','🙉','🙊']
///
pub fn to_list(string: String) -> List(String) {}

/// Convert a list of characters into a  Can be useful if you
/// want to create a string primarily by consing, perhaps for decoding
/// something.
///
/// > from_list(['a','b','c']) == "abc"
/// > from_list(['🙈','🙉','🙊']) == "🙈🙉🙊"
///
pub fn from_list(strings: List(String)) -> String {}

/// Split a non-empty string into its head and tail. This lets you
/// pattern match on strings exactly as you would with lists.
///
/// > uncons("abc") == Ok(('a',"bc"))
/// > uncons("")    == Error(Nil)
///
pub fn uncons(string: String) -> Result(tuple(String, String), Nil) {}




/// ## Higher-Order Functions




/// Transform every character in a string
///
/// > map("a/b/c", with: replace(all: "/", with: ".")) == "a.b.c"
///
pub fn map(string: String, with: fn(String) -> String) -> String {}


/// Keep only the characters that pass the test.
///
/// > filter("R2-D2", where: isDigit) == "22"
/// 
pub fn filter(string: String, where: fn(String) -> Bool) -> String {}


/// Reduce a string from the left.
///
/// > foldl("time", into: "", with: append) == "emit"
///
pub fn foldl(string: String, into accumulator: b, with: fn(String, b) -> b) -> b {}


/// Reduce a string from the right.
///
/// > foldr("time", into: "", with: append)  == "time"
///
pub fn foldr(string: String, into accumulator: b, with: fn(String, b) -> b) -> b {}


/// Determine whether *any* characters pass the test.
///
/// > any("90210", that: isDigit) == True
/// > any("R2-D2", that: isDigit) == True
/// > any("heart", that: isDigit) == False
///
pub fn any(string: String, that predicate: fn(String) -> Bool) -> Bool {}


/// Determine whether *all* characters pass the test.
///
/// > all("90210", that: isDigit) == True
/// > all("R2-D2", that: isDigit) == False
/// > all("heart", that: isDigit) == False
///
pub fn all(string: String, that predicate: fn(String) -> Bool) -> Bool {}