diff options
| -rw-r--r-- | src/gleam/atom.gleam | 6 | ||||
| -rw-r--r-- | src/gleam/dynamic.gleam | 18 | ||||
| -rw-r--r-- | src/gleam/function.gleam | 10 | ||||
| -rw-r--r-- | src/gleam/list.gleam | 4 | ||||
| -rw-r--r-- | src/gleam/result.gleam | 6 | ||||
| -rw-r--r-- | src/gleam/string.gleam | 238 |
6 files changed, 182 insertions, 100 deletions
diff --git a/src/gleam/atom.gleam b/src/gleam/atom.gleam index 74a05ad..e73b989 100644 --- a/src/gleam/atom.gleam +++ b/src/gleam/atom.gleam @@ -7,9 +7,9 @@ pub type AtomNotLoaded { pub external fn from_string(String) -> Result(Atom, AtomNotLoaded) = "gleam_stdlib" "atom_from_string"; -// This function can create a new atom if one does not already exist for -// the given string. Atoms are not garbage collected so this can result -// in a memory leak if called over time on new values +/// This function can create a new atom if one does not already exist for +/// the given string. Atoms are not garbage collected so this can result +/// in a memory leak if called over time on new values pub external fn create_from_string(String) -> Atom = "gleam_stdlib" "atom_create_from_string"; diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam index 68fe807..05e523f 100644 --- a/src/gleam/dynamic.gleam +++ b/src/gleam/dynamic.gleam @@ -2,18 +2,20 @@ import gleam/list as list_mod import gleam/atom import gleam/result -// `Dynamic` data is data that we don"t know the type of yet. -// We likely get data like this from interop with Erlang, or from -// IO with the outside world. +/// `Dynamic` data is data that we don"t know the type of yet. +/// We likely get data like this from interop with Erlang, or from +/// IO with the outside world. pub external type Dynamic; -// Convert any Gleam data into `Dynamic` data. +/// Convert any Gleam data into `Dynamic` data. +/// pub external fn from(a) -> Dynamic = "gleam_stdlib" "identity"; -// Unsafely cast a Dynamic value into any other type. -// -// This is an escape hatch for the type system that may be useful when wrapping -// native Erlang APIs. It is to be used as a last measure only. +/// Unsafely cast a Dynamic value into any other type. +/// +/// This is an escape hatch for the type system that may be useful when wrapping +/// native Erlang APIs. It is to be used as a last measure only. +/// pub external fn unsafe_coerce(a) -> b = "gleam_stdlib" "identity"; pub external fn string(from: Dynamic) -> Result(String, String) diff --git a/src/gleam/function.gleam b/src/gleam/function.gleam index 68fc619..6421dd1 100644 --- a/src/gleam/function.gleam +++ b/src/gleam/function.gleam @@ -1,16 +1,16 @@ -// Takes two functions and chains them together to form one function that takes -// the input from the first and returns the output of the second. +/// Takes two functions and chains them together to form one function that takes +/// the input from the first and returns the output of the second. pub fn compose(fun1: fn(a) -> b, fun2: fn(b) -> c) -> fn(a) -> c { fn(a) { fun1(a) |> fun2 } } -// Takes a function that takes two arguments and returns a new function that -// takes the same two arguments, but in reverse order. +/// Takes a function that takes two arguments and returns a new function that +/// takes the same two arguments, but in reverse order. pub fn flip(fun: fn(a, b) -> c) -> fn(b, a) -> c { fn(b, a) { fun(a, b) } } -// A function that always returns its input value. +/// A function that always returns its input value. pub fn identity(x: a) -> a { x } diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam index 33cdf6c..86e88ea 100644 --- a/src/gleam/list.gleam +++ b/src/gleam/list.gleam @@ -7,10 +7,10 @@ pub type LengthMismatch { LengthMismatch } -// Using the Erlang C BIF implementation. +/// Using the Erlang C BIF implementation. pub external fn length(List(a)) -> Int = "erlang" "length" -// Using the Erlang C BIF implementation. +/// Using the Erlang C BIF implementation. pub external fn reverse(List(a)) -> List(a) = "lists" "reverse" pub fn is_empty(list: List(a)) -> Bool { diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam index 9abbaea..1aa7ff5 100644 --- a/src/gleam/result.gleam +++ b/src/gleam/result.gleam @@ -1,5 +1,5 @@ -// Result represents the result of something that may succeed or fail. -// `Ok` means it was successful, `Error` means it failed. +/// Result represents the result of something that may succeed or fail. +/// `Ok` means it was successful, `Error` means it failed. pub fn is_ok(result: Result(a, e)) -> Bool { case result { @@ -59,7 +59,7 @@ pub fn unwrap(result: Result(a, e), or default: a) -> a { } } -// A value that is either there or not there +/// A value that is either there or not there pub type Option(value) = Result(value, Nil) diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam index b4f77de..67459b7 100644 --- a/src/gleam/string.gleam +++ b/src/gleam/string.gleam @@ -17,8 +17,8 @@ import gleam/order /// /// ## Examples /// ``` -/// > is_empty("") == True -/// > is_empty("the world") == False +/// is_empty("") == True +/// is_empty("the world") == False /// ``` /// pub fn is_empty(str: String) -> Bool { @@ -31,22 +31,30 @@ pub fn is_empty(str: String) -> Bool { /// Get the length of a /// -/// > length("innumerable") == 11 -/// > length("") == 0 +/// ## Examples +/// ```gleam +/// length("") == 0 +/// ``` /// pub external fn length(String) -> Int = "string" "length" /// Repeat a string `n` times. /// -/// > repeat(3, "ha") == "hahaha" +/// ## Examples +/// ```gleam +/// repeat(3, "ha") == "hahaha" +/// ``` /// // pub fn repeat(string: String, times: Int) -> String {} /// Reverse a string. /// -/// > reverse("stressed") == "desserts" +/// ## Examples +/// ```gleam +/// reverse("stressed") == "desserts" +/// ``` /// pub fn reverse(string: String) -> String { string @@ -58,8 +66,12 @@ pub fn reverse(string: String) -> 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" +/// ## Examples +/// ```gleam +/// 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: String, all pattern: String, @@ -74,24 +86,31 @@ pub fn replace( /// Convert a string to all lower case. Useful for case-insensitive comparisons. /// -/// > lowercase("X-FILES") == "x-files" -/// +/// ## Examples +/// ```gleam +/// 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" -/// +/// ## Examples +/// ```gleam +/// 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 +/// ## Examples +/// ```gleam +/// compare("Anthony", "Anthony") == order.Eq +/// ``` /// pub external fn compare(String, String) -> order.Order = "gleam_stdlib" "compare_strings" @@ -108,39 +127,51 @@ pub external fn compare(String, String) -> order.Order = /// 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" -/// +/// ## Examples +/// ```gleam +/// 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" -/// +/// ## Examples +/// ```gleam +/// left(num: 2, string: "Mulder") == "Mu" +/// ``` +/// // pub fn left(from string: String, num n: Int) -> String {} /// Take *n* characters from the right side of a /// -/// > right("Scully", 2) == "ly" -/// +/// ## Examples +/// ```gleam +/// right("Scully", 2) == "ly" +/// ``` +/// // pub fn right(from string: String, num_characters: Int) -> String {} /// Drop *n* characters from the left side of a /// -/// > drop_left(from: "The Lone Gunmen", num_characters: 2) == "e Lone Gunmen" -/// +/// ## Examples +/// ```gleam +/// drop_left(from: "The Lone Gunmen", num_characters: 2) == "e Lone Gunmen" +/// ``` +/// // pub fn drop_left(from string: String, num_characters: Int) -> String {} /// Drop *n* characters from the right side of a /// -/// > drop_right("Cigarette Smoking Man", 2) == "Cigarette Smoking M" -/// +/// ## Examples +/// ```gleam +/// drop_right("Cigarette Smoking Man", 2) == "Cigarette Smoking M" +/// ``` +/// // pub fn drop_right(from string: String, num_characters: Int) -> String {} @@ -153,26 +184,31 @@ pub external fn compare(String, String) -> order.Order = /// See if the second string contains the first one. /// -/// > contains("theory", this: "the") == True -/// > contains("theory", this: "hat") == False -/// > contains("theory", this: "THE") == False +/// ## Examples +/// ```gleam +/// contains("theory", this: "THE") == False +/// ``` /// // pub fn contains(this: String, in: String) -> String {} /// See if the second string starts with the first one. /// -/// > starts_with("theory", this: "the") == True -/// > starts_with("theory", this: "ory") == False +/// ## Examples +/// ```gleam +/// starts_with("theory", this: "ory") == False +/// ``` /// // pub fn starts_with(this: String, in: String) -> String {} /// See if the second string ends with the first one. /// -/// > endsWith("theory", this: "the") == False -/// > endsWith("theory", this: "ory") == True -/// +/// ## Examples +/// ```gleam +/// endsWith("theory", this: "ory") == True +/// ``` +/// // pub fn ends_with(this: String, in: String) -> String {} @@ -185,9 +221,11 @@ pub external fn compare(String, String) -> order.Order = /// Split a string using a given separator. /// -/// > split("cat,dog,cow", on: ",") == ["cat","dog","cow"] -/// > split("home/evan/Desktop/", on: "/") == ["home","evan","Desktop", ""] -/// +/// ## Examples +/// ```gleam +/// split("home/evan/Desktop/", on: "/") == ["home","evan","Desktop", ""] +/// ``` +/// pub fn split(string x: String, on pattern: String) -> List(String) { x |> iodata.new @@ -198,7 +236,10 @@ pub fn split(string x: String, on pattern: String) -> List(String) { /// Append two strings. /// -/// > append(to: "butter", suffix: "fly") == "butterfly" +/// ## Examples +/// ```gleam +/// append(to: "butter", suffix: "fly") == "butterfly" +/// ``` /// pub fn append(to first: String, suffix second: String) -> String { first @@ -210,7 +251,10 @@ pub fn append(to first: String, suffix second: String) -> String { /// Concatenate many strings into one. /// -/// > concat(["never","the","less"]) == "nevertheless" +/// ## Examples +/// ```gleam +/// concat(["never","the","less"]) == "nevertheless" +/// ``` /// pub fn concat(strings: List(String)) -> String { strings @@ -221,9 +265,10 @@ pub fn concat(strings: List(String)) -> String { /// Put many strings together with a given separator. /// -/// > join(["H","w","ii","n"], with: "a") == "Hawaiian" -/// > join(["cat","dog","cow"], with: " ") == "cat dog cow" -/// > join(["home","evan","Desktop"], with: "/") == "home/evan/Desktop" +/// ## Examples +/// ```gleam +/// join(["home","evan","Desktop"], with: "/") == "home/evan/Desktop" +/// ``` /// pub fn join(strings: List(String), with separator: String) -> String { strings @@ -236,23 +281,30 @@ pub fn join(strings: List(String), with separator: String) -> String { /// Break a string into words, splitting on chunks of whitespace. /// -/// > words("How are \t you? \n Good?") == ["How","are","you?","Good?"] -/// +/// ## Examples +/// ```gleam +/// 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?"] -/// +/// ## Examples +/// ```gleam +/// 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(of: "i", in:"Mississippi") == [1,4,7,10] -/// > indexes(of: "ss", in: "Mississippi") == [2,5] -/// > indexes(of: "needle", in: "haystack") == [] +/// ## Examples +/// ```gleam +/// indexes(of: "needle", in: "haystack") == [] +/// ``` /// // pub fn indexes(of: String, in: String) -> String {} @@ -266,48 +318,60 @@ pub fn join(strings: List(String), with separator: String) -> String { /// Pad a string on both sides until it has a given length. /// -/// > pad("1", to: 5, with: ' ') == " 1 " -/// > pad("11", to: 5, with: ' ') == " 11 " -/// > pad("121", to: 5, with: ' ') == " 121 " +/// ## Examples +/// ```gleam +/// pad("121", to: 5, with: ' ') == " 121 " +/// ``` /// // pub fn pad(string: String, to size: Int, with: String) -> String {} /// Pad a string on the left until it has a given length. /// -/// > padLeft("1", to: 5, with: '.') == "....1" -/// > padLeft("11", to: 5, with: '.') == "...11" -/// > padLeft("121", to: 5, with: '.') == "..121" +/// ## Examples +/// ```gleam +/// padLeft("121", to: 5, with: '.') == "..121" +/// ``` /// // pub fn pad_left(string: String, to size: Int, with: String) {} /// Pad a string on the right until it has a given length. /// -/// > padRight("1", to: 5, with: '.') == "1...." -/// > padRight("11", to: 5, with: '.') == "11..." -/// > padRight("121", to: 5, with: '.') == "121.." +/// ## Examples +/// ```gleam +/// padRight("121", to: 5, with: '.') == "121.." +/// ``` /// // pub fn pad_right(string: String, to size: Int, with: String) {} /// Get rid of whitespace on both sides of a /// -/// > trim(" hats \n") == "hats" +/// ## Examples +/// ```gleam +/// trim(" hats \n") == "hats" +/// ``` /// // pub fn trim(string: String) -> String {} /// Get rid of whitespace on the left of a /// -/// > trimLeft(" hats \n") == "hats \n" +/// ## Examples +/// ```gleam +/// 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" +/// ## Examples +/// ```gleam +/// trimRight(" hats \n") == " hats" +/// ``` /// // pub fn trim_right(string: String) -> String {} @@ -325,7 +389,7 @@ pub fn join(strings: List(String), with separator: String) -> String { // /// Convert a string to a list of characters. // /// -// /// > to_list("abc") == ['a','b','c'] +// /// to_list("abc") == ['a','b','c'] // /// // pub fn to_list(string: String) -> List(String) {} @@ -333,21 +397,23 @@ pub fn join(strings: List(String), with separator: String) -> String { // /// want to create a string primarily by consing, perhaps for decoding // /// something. // /// -// /// > from_list(['a','b','c']) == "abc" +// /// from_list(['a','b','c']) == "abc" // /// // // pub fn from_list(strings: List(String)) -> String {} // /// Add a character to the beginning of a string. // /// -// /// > cons('T', onto: "he truth is out there") == "The truth is out there" +// /// cons('T', onto: "he truth is out there") == "The truth is out there" // // pub fn cons(char: Char, onto string: 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) +/// ## Examples +/// ```gleam +/// uncons("") == Error(Nil) +/// ``` /// // pub fn uncons(string: String) -> Result(tuple(String, String), Nil) {} @@ -361,45 +427,59 @@ pub fn join(strings: List(String), with separator: String) -> String { /// Transform every character in a string /// -/// > map("a/b/c", with: replace(all: "/", with: ".")) == "a.b.c" +/// ## Examples +/// ```gleam +/// 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" -/// +/// ## Examples +/// ```gleam +/// 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" +/// ## Examples +/// ```gleam +/// 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" +/// ## Examples +/// ```gleam +/// 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 +/// ## Examples +/// ```gleam +/// 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 +/// ## Examples +/// ```gleam +/// all("heart", that: isDigit) == False +/// ``` /// // pub fn all(string: String, that predicate: fn(String) -> Bool) -> Bool {} |