diff --git a/src/Tablecloth.res b/src/Tablecloth.res index d92ccab..64868d3 100644 --- a/src/Tablecloth.res +++ b/src/Tablecloth.res @@ -1,46 +1,46 @@ -@ocaml.doc(" Functions for working with boolean ([true] or [false]) values. ") +/** Functions for working with boolean ([true] or [false]) values. */ module Bool = TableclothBool -@ocaml.doc(" Functions for working with single characters. ") +/** Functions for working with single characters. */ module Char = TableclothChar -@ocaml.doc(" Functions for working with [\"strings\"] ") +/** Functions for working with ["strings"] */ module String = TableclothString -@ocaml.doc(" Fixed precision integers ") +/** Fixed precision integers */ module Int = TableclothInt -@ocaml.doc(" Functions for working with floating point numbers. ") +/** Functions for working with floating point numbers. */ module Float = TableclothFloat -@ocaml.doc(" Interfaces for use with container types like {!Array} or {!List} ") +/** Interfaces for use with container types like [Array](Array.mdx#) or [List](List.mdx#) */ module Container = TableclothContainer -@ocaml.doc(" A fixed lenfth collection of values ") +/** A fixed lenfth collection of values */ module Array = TableclothArray -@ocaml.doc(" Arbitrary length, singly linked lists ") +/** Arbitrary length, singly linked lists */ module List = TableclothList -@ocaml.doc(" Functions for working with optional values. ") +/** Functions for working with optional values. */ module Option = TableclothOption -@ocaml.doc(" Functions for working with computations which may fail. ") +/** Functions for working with computations which may fail. */ module Result = TableclothResult -@ocaml.doc(" Functions for manipulating tuples of length two ") +/** Functions for manipulating tuples of length two */ module Tuple2 = TableclothTuple2 -@ocaml.doc(" Functions for manipulating tuples of length three ") +/** Functions for manipulating tuples of length three */ module Tuple3 = TableclothTuple3 module Comparator = TableclothComparator -@ocaml.doc(" A collection of unique values ") +/** A collection of unique values */ module Set = TableclothSet -@ocaml.doc(" A collection of key-value pairs ") +/** A collection of key-value pairs */ module Map = TableclothMap -@ocaml.doc(" Functions for working with functions. ") +/** Functions for working with functions. */ module Fun = TableclothFun diff --git a/src/TableclothArray.resi b/src/TableclothArray.resi index bdf8fad..135f0e4 100644 --- a/src/TableclothArray.resi +++ b/src/TableclothArray.resi @@ -1,831 +1,820 @@ -@@ocaml.text(" ") +/** A mutable vector of elements which must have the same type. -@@ocaml.text(" A mutable vector of elements which must have the same type. - - Has constant time (O(1)) {!get}, {!set} and {!length} operations. - - Arrays have a fixed length, if you want to be able to add an arbitrary number of elements maybe you want a {!List}. -") + Has constant time (O(1)) [get](#get), [set](#set) and [length](#length) operations. + Arrays have a fixed length, if you want to be able to add an arbitrary number of elements maybe you want a [List](List.mdx#)}. + You can create an `array` in Rescript with the `[1, 2, 3]` syntax. +*/ type t<'a> = array<'a> -@@ocaml.text(" {1 Create} - - You can create an [array] in Rescript with the [[1, 2, 3]] syntax. -") +/** Create an array with only one element. -@ocaml.doc(" Create an array with only one element. + ## Examples - {2 Examples} - - {[ - Array.singleton(1234) == [1234] - Array.singleton(\"hi\") == [\"hi\"] - ]} -") + ```rescript + Array.singleton(1234) == [1234] + Array.singleton("hi") == ["hi"] + ``` +*/ let singleton: 'a => t<'a> -@ocaml.doc(" Creates an array of length [length] with the value [x] populated at each index. +/** Creates an array of length `length` with the value `x` populated at each index. - {2 Examples} + ## Examples - {[ - Array.repeat('a', ~length=5) == ['a', 'a', 'a', 'a', 'a'] - Array.repeat(7, ~length=0) == [] - Array.repeat(\"Why?\", ~length=-1) == [] - ]} -") + ```rescript + Array.repeat('a', ~length=5) == ['a', 'a', 'a', 'a', 'a'] + Array.repeat(7, ~length=0) == [] + Array.repeat("Why?", ~length=-1) == [] + ``` +*/ let repeat: ('a, ~length: int) => t<'a> -@ocaml.doc(" Creates an array containing all of the integers from [from] if it is provided or [0] if not, up to but not including [to]. +/** Creates an array containing all of the integers from `from` if it is provided or `0` if not, up to but not including `to`. - {2 Examples} + ## Examples - {[ - Array.range(5) == [0, 1, 2, 3, 4] - Array.range(5, ~from=2) == [2, 3, 4] - Array.range(3, ~from=-2) == [-2, -1, 0, 1, 2] - ]} -") + ```rescript + Array.range(5) == [0, 1, 2, 3, 4] + Array.range(5, ~from=2) == [2, 3, 4] + Array.range(3, ~from=-2) == [-2, -1, 0, 1, 2] + ``` +*/ let range: (~from: int=?, int) => t -@ocaml.doc(" Initialize an array. [Array.initialize n ~f] creates an array of length [n] with - the element at index [i] initialized to the result of [(f i)]. +/** Initialize an array. `Array.initialize(n, ~f)` creates an array of length `n` with + the element at index `i` initialized to the result of `f(i)`. - {2 Examples} + ## Examples - {[ - Array.initialize(4, ~f=identity) == [0, 1, 2, 3] - Array.initialize(4, ~f=n => n * n) == [0, 1, 4, 9] - ]} -") + ```rescript + Array.initialize(4, ~f=identity) == [0, 1, 2, 3] + Array.initialize(4, ~f=n => n * n) == [0, 1, 4, 9] + ``` +*/ let initialize: (int, ~f: int => 'a) => t<'a> -@ocaml.doc(" Create an array from a {!List}. +/** Create an array from a [List](List.mdx#). - {2 Examples} + ## Examples - {[ - Array.fromList(list{1, 2, 3}) == [1, 2, 3] - ]} -") + ```rescript + Array.fromList(list{1, 2, 3}) == [1, 2, 3] + ``` +*/ let fromList: list<'a> => t<'a> -@ocaml.doc(" Create a shallow copy of an array. +/** Create a shallow copy of an array. - {2 Examples} + ## Examples - {[ - let numbers = [1, 2, 3] - let otherNumbers = Array.copy(numbers) - numbers[1] == 9 - numbers == [1, 9, 3] - otherNumbers == [1, 2, 3] + ```rescript + let numbers = [1, 2, 3] + let otherNumbers = Array.copy(numbers) + numbers[1] == 9 + numbers == [1, 9, 3] + otherNumbers == [1, 2, 3] - let numberGrid = [ - [1, 2, 3], - [4, 5, 6], - [7, 8, 9] - ] + let numberGrid = [ + [1, 2, 3], + [4, 5, 6], + [7, 8, 9] + ] - let numberGridCopy = Array.copy(numberGrid) + let numberGridCopy = Array.copy(numberGrid) - numberGrid[1][1] == 0 - numberGridCopy[1][1] == 9 - ]} -") + numberGrid[1][1] == 0 + numberGridCopy[1][1] == 9 + ``` +*/ let clone: t<'a> => t<'a> -@@ocaml.text(" {1 Basic operations} ") - -@ocaml.doc(" Get the element at the specified index. +/** Get the element at the specified index. - The first element has index number 0. + The first element has index number 0. - The last element has index number [Array.length(a) - 1]. + The last element has index number `Array.length(a) - 1`. - You should prefer using the dedicated literal syntax: + You should prefer using the dedicated literal syntax: - {[ - array[n] - ]} + ```rescript + array[n] + ``` - Or using the safer {!Array.getAt} function. + Or using the safer [Array.getAt](#get-at) function. - {3 Exceptions} + ### Exceptions - Raises [Invalid_argument(\"index out of bounds\")] for indexes outside of the range [0] to [(Array.length a - 1)]. + Raises `Invalid_argument("index out of bounds")` for indexes outside of the range `0` to `(Array.length(a) - 1)`. - {2 Examples} + ## Examples - {[ - [1, 2, 3, 2, 1][3] == 2 + ```rescript + [1, 2, 3, 2, 1][3] == 2 - let animals = [\"cat\", \"dog\", \"eel\"] - animals[2] == \"eel\" - ]} -") + let animals = ["cat", "dog", "eel"] + animals[2] == "eel" + ``` +*/ let get: (t<'a>, int) => 'a -@ocaml.doc(" Returns, as an {!Option}, the element at index number [n] of array [a]. +/** Returns, as an [Option](Option.mdx#), the element at index number `n` of array `a`. - Returns [None] if [n] is outside the range [0] to [(Array.length(a) - 1)]. + Returns `None` if `n` is outside the range `0` to `Array.length(a) - 1`. - {2 Examples} + ## Examples - {[ - Array.getAt([0, 1, 2], ~index=5) == None - Array.getAt([], ~index=0) == None - ]} -") + ```rescript + Array.getAt([0, 1, 2], ~index=5) == None + Array.getAt([], ~index=0) == None + ``` +*/ let getAt: (t<'a>, ~index: int) => option<'a> -@ocaml.doc(" Modifies an array in place, replacing the element at [index] with [value]. +/** Modifies an array in place, replacing the element at `index` with `value`. - You should prefer either to write + You should prefer either to write - {[ - array[index] = value - ]} + ```rescript + array[index] = value + ``` - Or use the {!setAt} function instead. + Or use the [Array.setAt](#set-at) function instead. - {3 Exceptions} + ### Exceptions - Raises [Invalid_argument(\"index out of bounds\")] if [n] is outside the range [0] to [Array.length(a) - 1]. + Raises `Invalid_argument("index out of bounds")` if `n` is outside the range `0` to `Array.length(a) - 1`. - {2 Examples} + ## Examples - {[ - let numbers = [1, 2, 3] - Array.set(numbers, 1, 1) - numbers[2] = 0 + ```rescript + let numbers = [1, 2, 3] + Array.set(numbers, 1, 1) + numbers[2] = 0 - numbers == [1, 1, 0] - ]} -") + numbers == [1, 1, 0] + ``` +*/ let set: (t<'a>, int, 'a) => unit -@ocaml.doc(" Like {!set} but with labelled arguments. ") +/** Like [Array.set](#set) but with labelled arguments. */ let setAt: (t<'a>, ~index: int, ~value: 'a) => unit -@ocaml.doc(" Get the first element of an array. +/** Get the first element of an array. - Returns [None] if the array is empty. + Returns `None` if the array is empty. - {2 Examples} + ## Examples - {[ - Array.first([1, 2, 3]) == Some(1) - Array.first([1]) == Some(1) - Array.first([]) == None - ]} -") + ```rescript + Array.first([1, 2, 3]) == Some(1) + Array.first([1]) == Some(1) + Array.first([]) == None + ``` +*/ let first: t<'a> => option<'a> -@ocaml.doc(" Get the last element of an array. +/** Get the last element of an array. - Returns [None] if the array is empty. + Returns `None` if the array is empty. - {2 Examples} + ## Examples - {[ - Array.last([1, 2, 3]) == Some(3) - Array.last([1]) == Some(1) - Array.last([]) == None - ]} -") + ```rescript + Array.last([1, 2, 3]) == Some(3) + Array.last([1]) == Some(1) + Array.last([]) == None + ``` +*/ let last: t<'a> => option<'a> -@ocaml.doc(" Get a sub-section of an array. [from] is a zero-based index where we will start our slice. +/** Get a sub-section of an array. `from` is a zero-based index where we will start our slice. - The [to_] is a zero-based index that indicates the end of the slice. + The `to_` is a zero-based index that indicates the end of the slice. - The slice extracts up to but not including [to_]. + The slice extracts up to but not including `to_`. - Both the [from] and [to_] indexes can be negative, indicating an offset from the end of the array. + Both the `from` and `to_` indexes can be negative, indicating an offset from the end of the array. - {2 Examples} + ## Examples - {[ - Array.slice([0, 1, 2, 3, 4], ~from=0, ~to_=3) == [0, 1, 2] - Array.slice([0, 1, 2, 3, 4], ~from=1, ~to_=4) == [1, 2, 3] - Array.slice([0, 1, 2, 3, 4], ~from=5, ~to_=3) == [] - Array.slice([0, 1, 2, 3, 4], ~from=1, ~to_=-1) == [1, 2, 3] - Array.slice([0, 1, 2, 3, 4], ~from=-2, ~to_=5) == [3, 4] - Array.slice([0, 1, 2, 3, 4], ~from=-2, ~to_=-1) == [3] - ]} -") + ```rescript + Array.slice([0, 1, 2, 3, 4], ~from=0, ~to_=3) == [0, 1, 2] + Array.slice([0, 1, 2, 3, 4], ~from=1, ~to_=4) == [1, 2, 3] + Array.slice([0, 1, 2, 3, 4], ~from=5, ~to_=3) == [] + Array.slice([0, 1, 2, 3, 4], ~from=1, ~to_=-1) == [1, 2, 3] + Array.slice([0, 1, 2, 3, 4], ~from=-2, ~to_=5) == [3, 4] + Array.slice([0, 1, 2, 3, 4], ~from=-2, ~to_=-1) == [3] + ``` +*/ let slice: (~to_: int=?, t<'a>, ~from: int) => t<'a> -@ocaml.doc(" Swaps the values at the provided indicies. +/** Swaps the values at the provided indicies. - {3 Exceptions} + ### Exceptions - Raises an [Invalid_argument] exception of either index is out of bounds for the array. + Raises an `Invalid_argument` exception of either index is out of bounds for the array. - {2 Examples} + ## Examples - {[ - Array.swap([1, 2, 3], 1, 2) == [1, 3, 2] - ]} -") + ```rescript + Array.swap([1, 2, 3], 1, 2) == [1, 3, 2] + ``` +*/ let swap: (t<'a>, int, int) => unit -@ocaml.doc(" Reverses an array {b in place}, mutating the existing array. +/** Reverses an array *in place*, mutating the existing array. - {2 Examples} + ## Examples - {[ - let numbers = [1, 2, 3] - Array.reverse(numbers) - numbers == [3, 2, 1] - ]} -") + ```rescript + let numbers = [1, 2, 3] + Array.reverse(numbers) + numbers == [3, 2, 1] + ``` +*/ let reverse: t<'a> => unit -@ocaml.doc(" Sort in place, modifying the existing array, using the provided [compare] function to determine order. +/** Sort in place, modifying the existing array, using the provided `compare` function to determine order. - The time and space complexity of the sort cannot be guaranteed as it depends on the implementation. + The time and space complexity of the sort cannot be guaranteed as it depends on the implementation. - {2 Examples} + ## Examples - {[ - Array.sort([5, 6, 8, 3, 6], ~compare) == [3, 5, 6, 6, 8] - ]} -") + ```rescript + Array.sort([5, 6, 8, 3, 6], ~compare) == [3, 5, 6, 6, 8] + ``` +*/ let sort: (t<'a>, ~compare: ('a, 'a) => int) => unit -@@ocaml.text(" {1 Query} ") - -@ocaml.doc(" Check if an array is empty. +/** Check if an array is empty. - {2 Examples} + ## Examples - {[ - Array.isEmpty([1, 2, 3]) == false - Array.isEmpty([]) == true - ]} -") + ```rescript + Array.isEmpty([1, 2, 3]) == false + Array.isEmpty([]) == true + ``` +*/ let isEmpty: t<'a> => bool -@ocaml.doc(" Return the length of an array. +/** Return the length of an array. - {2 Examples} + ## Examples - {[ - Array.length([1, 2, 3]) == 3 - Array.length([]) == 0 - ]} -") + ```rescript + Array.length([1, 2, 3]) == 3 + Array.length([]) == 0 + ``` +*/ let length: t<'a> => int -@ocaml.doc(" Determine if [f] returns true for [any] values in an array. +/** Determine if `f` returns true for `any` values in an array. - Iteration is stopped as soon as [f] returns [true]. + Iteration is stopped as soon as `f` returns `true`. - {2 Examples} + ## Examples - {[ - Array.any([1, 2, 3, 5], ~f=Int.isEven) == true - Array.any([1, 3, 5, 7], ~f=Int.isEven) == false - Array.any([], ~f=Int.isEven) == false - ]} -") + ```rescript + Array.any([1, 2, 3, 5], ~f=Int.isEven) == true + Array.any([1, 3, 5, 7], ~f=Int.isEven) == false + Array.any([], ~f=Int.isEven) == false + ``` +*/ let any: (t<'a>, ~f: 'a => bool) => bool -@ocaml.doc(" Determine if [f] returns true for [all] values in an array. +/** Determine if `f` returns true for `all` values in an array. - Iteration is stopped as soon as [f] returns [false]. + Iteration is stopped as soon as `f` returns `false`. - {2 Examples} + ## Examples - {[ - Array.all([2, 4], ~f=Int.isEven) == true - Array.all([2, 3], ~f=Int.isEven) == false - Array.all([], ~f=Int.isEven) == true - ]} -") + ```rescript + Array.all([2, 4], ~f=Int.isEven) == true + Array.all([2, 3], ~f=Int.isEven) == false + Array.all([], ~f=Int.isEven) == true + ``` +*/ let all: (t<'a>, ~f: 'a => bool) => bool -@ocaml.doc(" Count the number of elements which function [f] will return [true]. +/** Count the number of elements which function `f` will return `true`. - {2 Examples} + ## Examples - {[ - Array.count([7, 5, 8, 6], ~f=Int.isEven) == 2 - ]} -") + ```rescript + Array.count([7, 5, 8, 6], ~f=Int.isEven) == 2 + ``` +*/ let count: (t<'a>, ~f: 'a => bool) => int -@ocaml.doc(" Returns, as an {!Option}, the first element for which [f] evaluates to [true]. +/** Returns, as an [Option](Option.mdx#), the first element for which `f` evaluates to `true`. - If [f] doesn't return [true] for any of the elements [find] will return [None] + If `f` doesn't return `true` for any of the elements `find` will return `None` - {2 Examples} + ## Examples - {[ - Array.find([1, 3, 4, 8], ~f=Int.isEven) == Some(4) - Array.find([0, 2, 4, 8], ~f=Int.isOdd) == None - Array.find([], ~f=Int.isEven) == None - ]} -") + ```rescript + Array.find([1, 3, 4, 8], ~f=Int.isEven) == Some(4) + Array.find([0, 2, 4, 8], ~f=Int.isOdd) == None + Array.find([], ~f=Int.isEven) == None + ``` +*/ let find: (t<'a>, ~f: 'a => bool) => option<'a> -@ocaml.doc(" Similar to {!Array.find} but [f] is also called with the current index, and the return value will be a tuple of the index the passing value was found at and the passing value. +/** Similar to [Array.find](#find) but `f` is also called with the current index, and the return value will be a tuple of the index the passing value was found at and the passing value. - {2 Examples} + ## Examples - {[ - Array.findIndex([1, 3, 4, 8], ~f=(index, number) => index > 2 && Int.isEven(number)) == Some(3, 8) - ]} -") + ```rescript + Array.findIndex([1, 3, 4, 8], ~f=(index, number) => index > 2 && Int.isEven(number)) == Some(3, 8) + ``` +*/ let findIndex: (t<'a>, ~f: (int, 'a) => bool) => option<(int, 'a)> -@ocaml.doc(" Test if an array contains the specified element using the provided [equal] to test for equality. +/** Test if an array contains the specified element using the provided `equal` to test for equality. - {2 Examples} + ## Examples - {[ - Array.includes([1, 2, 3], 2, ~equal=Int.equal) == true - ]} -") + ```rescript + Array.includes([1, 2, 3], 2, ~equal=Int.equal) == true + ``` +*/ let includes: (t<'a>, 'a, ~equal: ('a, 'a) => bool) => bool -@ocaml.doc(" Find the smallest element using the provided [compare] function. +/** Find the smallest element using the provided `compare` function. - Returns [None] if called on an empty array. + Returns `None` if called on an empty array. - {2 Examples} + ## Examples - {[ - Array.minimum([7, 5, 8, 6], ~compare=Int.compare) == Some(5) - Array.minimum([], ~compare=Int.compare) == None - ]} -") + ```rescript + Array.minimum([7, 5, 8, 6], ~compare=Int.compare) == Some(5) + Array.minimum([], ~compare=Int.compare) == None + ``` +*/ let minimum: (t<'a>, ~compare: ('a, 'a) => int) => option<'a> -@ocaml.doc(" Find the largest element using the provided [compare] function. +/** Find the largest element using the provided `compare` function. - Returns [None] if called on an empty array. + Returns `None` if called on an empty array. - {2 Examples} + ## Examples - {[ - Array.maximum([7, 5, 8, 6], ~compare=Int.compare) == Some(8) - Array.maximum([], ~compare=Int.compare) == None - ]} -") + ```rescript + Array.maximum([7, 5, 8, 6], ~compare=Int.compare) == Some(8) + Array.maximum([], ~compare=Int.compare) == None + ``` +*/ let maximum: (t<'a>, ~compare: ('a, 'a) => int) => option<'a> -@ocaml.doc(" Find a {!Tuple2} of the {!minimum} and {!maximum} in a single pass. +/** Find a [Tuple2](#Tuple2.mdx) of the [Array.minimum](#minimum) and [Array.maximum](#maximum) in a single pass. - Returns [None] if called on an empty array. + Returns `None` if called on an empty array. - {2 Examples} + ## Examples - {[ - Array.extent([7, 5, 8, 6], ~compare=Int.compare) == Some(5, 8) - Array.extent([7], ~compare=Int.compare) == Some(7, 7) - Array.extent([], ~compare=Int.compare) == None - ]} -") + ```rescript + Array.extent([7, 5, 8, 6], ~compare=Int.compare) == Some(5, 8) + Array.extent([7], ~compare=Int.compare) == Some(7, 7) + Array.extent([], ~compare=Int.compare) == None + ``` +*/ let extent: (t<'a>, ~compare: ('a, 'a) => int) => option<('a, 'a)> -@ocaml.doc(" Calculate the sum of an array using the provided modules [zero] value and [add] function. - - {2 Examples} - - {[ - Array.sum([1, 2, 3], module(Int)) == 6 - Array.sum([4.0, 4.5, 5.0], module(Float)) == 13.5 - - Array.sum( - [\"a\", \"b\", \"c\"], - module( - { - type rec t = string - let zero = \"\" - let add = (x, y) => x ++ y - } - ), - ) == \"abc\" - ]} -") +/** Calculate the sum of an array using the provided modules `zero` value and `add` function. + + ## Examples + + ```rescript + Array.sum([1, 2, 3], module(Int)) == 6 + Array.sum([4.0, 4.5, 5.0], module(Float)) == 13.5 + + Array.sum( + ["a", "b", "c"], + module( + { + type rec t = string + let zero = "" + let add = (x, y) => x ++ y + } + ), + ) == "abc" + ``` +*/ let sum: (t<'a>, module(TableclothContainer.Sum with type t = 'a)) => 'a -@@ocaml.text(" {1 Transform} ") +/** Create a new array which is the result of applying a function `f` to every element. -@ocaml.doc(" Create a new array which is the result of applying a function [f] to every element. + ## Examples - {2 Examples} - - {[ - Array.map([1.0, 4.0, 9.0], ~f=Float.squareRoot) == [1.0, 2.0, 3.0] - ]} -") + ```rescript + Array.map([1.0, 4.0, 9.0], ~f=Float.squareRoot) == [1.0, 2.0, 3.0] + ``` +*/ let map: (t<'a>, ~f: 'a => 'b) => t<'b> -@ocaml.doc(" Apply a function [f] to every element with its index as the first argument. +/** Apply a function `f` to every element with its index as the first argument. - {2 Examples} + ## Examples - {[ - Array.mapWithIndex([5, 5, 5], ~f=Int.multiply) == [0, 5, 10] - ]} -") + ```rescript + Array.mapWithIndex([5, 5, 5], ~f=Int.multiply) == [0, 5, 10] + ``` +*/ let mapWithIndex: (t<'a>, ~f: (int, 'a) => 'b) => t<'b> -@ocaml.doc(" Keep elements where function [f] will return [true]. +/** Keep elements where function `f` will return `true`. - {2 Examples} + ## Examples - {[ - Array.filter([1, 2, 3, 4, 5, 6], ~f=Int.isEven) == [2, 4, 6] - ]} -") + ```rescript + Array.filter([1, 2, 3, 4, 5, 6], ~f=Int.isEven) == [2, 4, 6] + ``` +*/ let filter: (t<'a>, ~f: 'a => bool) => t<'a> -@ocaml.doc(" Allows you to combine {!map} and {!filter} into a single pass. +/** Allows you to combine [Array.map](#map) and [Array.filter](#filter) into a single pass. - The output array only contains elements for which [f] returns [Some]. + The output array only contains elements for which `f` returns `Some`. - Why [filterMap] and not just {!filter} then {!map}? + Why `Array.filterMap` and not just [Array.filter](#filter) then [Array.map](#map)? - {!filterMap} removes the {!Option} layer automatically. + `filterMap` removes the [Option](Option.mdx#) layer automatically. - If your mapping is already returning an {!Option} and you want to skip over [None]s, then [filterMap] is much nicer to use. + If your mapping is already returning an [Option](Option.mdx#) and you want to skip over `None`s, then `filterMap` is much nicer to use. - {2 Examples} + ## Examples - {[ - let characters = ['a', '9', '6', ' ', '2', 'z'] - Array.filterMap(characters, ~f=Char.toDigit) == [9, 6, 2] + ```rescript + let characters = ['a', '9', '6', ' ', '2', 'z'] + Array.filterMap(characters, ~f=Char.toDigit) == [9, 6, 2] - Array.filterMap([3, 4, 5, 6], ~f=number => - Int.isEven(number) ? Some(number * number) : None - ) == [16, 36] - ]} -") + Array.filterMap([3, 4, 5, 6], ~f=number => + Int.isEven(number) ? Some(number * number) : None + ) == [16, 36] + ``` +*/ let filterMap: (t<'a>, ~f: 'a => option<'b>) => t<'b> -@ocaml.doc(" {!map} [f] onto an array and {!flatten} the resulting arrays. +/** [Array.map](#map) `f` onto an array and [Array.flatten](#flatten) the resulting arrays. - {2 Examples} + ## Examples - {[ - Array.flatMap([1, 2, 3], ~f=n => [n, n]) == [1, 1, 2, 2, 3, 3] - ]} -") + ```rescript + Array.flatMap([1, 2, 3], ~f=n => [n, n]) == [1, 1, 2, 2, 3, 3] + ``` +*/ let flatMap: (t<'a>, ~f: 'a => t<'b>) => t<'b> -@ocaml.doc(" Just as {{: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce } Array.prototype.reduce() } from the JS, - [fold] will produce a new value from an array. +/** Just as [Array.prototype.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce) from the JS, + `fold` will produce a new value from an array. - [fold] takes two arguments, an [initial] 'accumulator' value and a function [f]. + `fold` takes two arguments, an `initial` 'accumulator' value and a function `f`. - For each element of the array [f] will be called with two arguments: the current accumulator and an element. + For each element of the array `f` will be called with two arguments: the current accumulator and an element. - [f] returns the value that the accumulator should have for the next iteration. + `f` returns the value that the accumulator should have for the next iteration. - The [initial] value is the value the accumulator will have on the first call to [f]. + The `initial` value is the value the accumulator will have on the first call to `f`. - After applying [f] to every element of the array, [fold] returns the accumulator. + After applying `f` to every element of the array, `fold` returns the accumulator. - [fold] iterates over the elements of the array from first to last. + `fold` iterates over the elements of the array from first to last. - Folding is useful whenever you have a collection of something, and want to produce a single value from it. + Folding is useful whenever you have a collection of something, and want to produce a single value from it. - For example, if we have: + For example, if we have: - {[ - let numbers = [(1, 2, 3)] - let sum = Array.fold(numbers, ~initial=0, ~f=(accumulator, element) => accumulator + element) + ```rescript + let numbers = [(1, 2, 3)] + let sum = Array.fold(numbers, ~initial=0, ~f=(accumulator, element) => accumulator + element) - sum == 6 - ]} + sum == 6 + ``` - Walking though each iteration step by step: + Walking though each iteration step by step: - + [accumulator: 0, element: 1, result: 1] - + [accumulator: 1, element: 2, result: 3] - + [accumulator: 3, element: 3, result: 6] + + `accumulator: 0, element: 1, result: 1` + + `accumulator: 1, element: 2, result: 3` + + `accumulator: 3, element: 3, result: 6` - And so the final result is [6]. (Note that in reality you probably want to use {!Array.sum}) + And so the final result is `6`. (Note that in reality you probably want to use [Array.Array.sum](#Array.sum)) - {2 Examples} + ## Examples - {[ - Array.fold([3, 4, 5], ~f=Int.multiply, ~initial=2) == 120 + ```rescript + Array.fold([3, 4, 5], ~f=Int.multiply, ~initial=2) == 120 - Array.fold([1, 1, 2, 2, 3], ~initial=Set.Int.empty, ~f=Set.add) -> Set.toArray == [1, 2, 3] + Array.fold([1, 1, 2, 2, 3], ~initial=Set.Int.empty, ~f=Set.add) -> Set.toArray == [1, 2, 3] - let lastEven = integers => - Array.fold(integers, ~initial=None, ~f=(last, int) => - int->Int.isEven ? Some(int) : last - ) + let lastEven = integers => + Array.fold(integers, ~initial=None, ~f=(last, int) => + int->Int.isEven ? Some(int) : last + ) - lastEven([1, 2, 3, 4, 5]) == Some(4) - ]} -") + lastEven([1, 2, 3, 4, 5]) == Some(4) + ``` +*/ let fold: (t<'a>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b -@ocaml.doc(" This method is like {!fold} except that it iterates over the elements of the array from last to first. +/** This method is like [Array.fold](#fold) except that it iterates over the elements of the array from last to first. - {2 Examples} + ## Examples - {[ - Array.repeat(~length=3, 5) -> Array.foldRight(~f=Int.add, ~initial=0) == 15 - Array.foldRight([3, 4, 5], ~f=Int.multiply, ~initial=2) == 120 - ]} -") + ```rescript + Array.repeat(~length=3, 5) -> Array.foldRight(~f=Int.add, ~initial=0) == 15 + Array.foldRight([3, 4, 5], ~f=Int.multiply, ~initial=2) == 120 + ``` +*/ let foldRight: (t<'a>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b -@ocaml.doc(" Creates a new array which is the result of appending the second array onto the end of the first. +/** Creates a new array which is the result of appending the second array onto the end of the first. - {2 Examples} + ## Examples - {[ - let fortyTwos = Array.repeat(42, ~length=2) - let eightyOnes = Array.repeat(81, ~length=3) - Array.append(fourtyTwos, eightyOnes) == [42, 42, 81, 81, 81] - ]} -") + ```rescript + let fortyTwos = Array.repeat(42, ~length=2) + let eightyOnes = Array.repeat(81, ~length=3) + Array.append(fourtyTwos, eightyOnes) == [42, 42, 81, 81, 81] + ``` +*/ let append: (t<'a>, t<'a>) => t<'a> -@ocaml.doc(" Flatten an array of arrays into a single array: +/** Flatten an array of arrays into a single array: - {2 Examples} + ## Examples - {[ - Array.flatten([[1, 2], [3], [4, 5]]) == [1, 2, 3, 4, 5] - ]} -") + ```rescript + Array.flatten([[1, 2], [3], [4, 5]]) == [1, 2, 3, 4, 5] + ``` +*/ let flatten: t> => t<'a> -@ocaml.doc(" Combine two arrays by merging each pair of elements into a {!Tuple2}. +/** Combine two arrays by merging each pair of elements into a [Tuple2](Tuple2.mdx#). - If one array is longer, the extra elements are dropped. + If one array is longer, the extra elements are dropped. - The same as [Array.map2(~f=Tuple2.make)] + The same as `Array.map2(~f=Tuple2.make)` - {2 Examples} + ## Examples - {[ - Array.zip([1, 2, 3, 4, 5], [\"Dog\", \"Eagle\", \"Ferret\"]) == [(1, \"Dog\"), (2, \"Eagle\"), (3, \"Ferret\")] - ]} -") + ```rescript + Array.zip([1, 2, 3, 4, 5], ["Dog", "Eagle", "Ferret"]) == [(1, "Dog"), (2, "Eagle"), (3, "Ferret")] + ``` +*/ let zip: (t<'a>, t<'b>) => t<('a, 'b)> -@ocaml.doc(" Combine two arrays, using [f] to combine each pair of elements. +/** Combine two arrays, using `f` to combine each pair of elements. - If one array is longer, the extra elements are dropped. + If one array is longer, the extra elements are dropped. - {2 Examples} + ## Examples - {[ - let totals = (xs, ys) => Array.map2(~f=Int.add, xs, ys) + ```rescript + let totals = (xs, ys) => Array.map2(~f=Int.add, xs, ys) - totals([1, 2, 3], [4, 5, 6]) == [5, 7, 9] + totals([1, 2, 3], [4, 5, 6]) == [5, 7, 9] - Array.map2(~f=Tuple2.make, [\"alice\", \"bob\", \"chuck\"], [2, 5, 7, 8]) - == [(\"alice\", 2), (\"bob\", 5), (\"chuck\", 7)]; - ]} -") + Array.map2(~f=Tuple2.make, ["alice", "bob", "chuck"], [2, 5, 7, 8]) + == [("alice", 2), ("bob", 5), ("chuck", 7)]; + ``` +*/ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> -@ocaml.doc(" Combine three arrays, using [f] to combine each trio of elements. +/** Combine three arrays, using `f` to combine each trio of elements. - If one array is longer, the extra elements are dropped. + If one array is longer, the extra elements are dropped. - {2 Examples} + ## Examples - {[ - Array.map3( - ~f=Tuple3.make, - [\"alice\", \"bob\", \"chuck\"], - [2, 5, 7, 8], - [true, false, true, false], - ) - == [(\"alice\", 2, true), (\"bob\", 5, false), (\"chuck\", 7, true)]; - ]} -") + ```rescript + Array.map3( + ~f=Tuple3.make, + ["alice", "bob", "chuck"], + [2, 5, 7, 8], + [true, false, true, false], + ) + == [("alice", 2, true), ("bob", 5, false), ("chuck", 7, true)]; + ``` +*/ let map3: (t<'a>, t<'b>, t<'c>, ~f: ('a, 'b, 'c) => 'd) => t<'d> -@@ocaml.text(" {1 Deconstruct} ") - -@ocaml.doc(" Split an array into a {!Tuple2} of arrays. Values which [f] returns true for will end up in {!Tuple2.first}. +/** Split an array into a [Tuple2](Tuple2.mdx#) of arrays. Values which `f` returns true for will end up in [Tuple2.first](Tuple2.mdx#first). - {2 Examples} + ## Examples - {[ - Array.partition([1, 2, 3, 4, 5, 6], ~f=Int.isOdd) == ([1, 3, 5], [2, 4, 6]) - ]} -") + ```rescript + Array.partition([1, 2, 3, 4, 5, 6], ~f=Int.isOdd) == ([1, 3, 5], [2, 4, 6]) + ``` +*/ let partition: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) -@ocaml.doc(" Divides an array into a {!Tuple2} of arrays. +/** Divides an array into a [Tuple2](Tuple2.mdx#) of arrays. - Elements which have index upto (but not including) [index] will be in the first component of the tuple. + Elements which have index upto (but not including) `index` will be in the first component of the tuple. - Elements with an index greater than or equal to [index] will be in the second. + Elements with an index greater than or equal to `index` will be in the second. - {3 Exceptions} + ### Exceptions - Raises an [Invalid_argument] exception if [index] is less than zero. + Raises an `Invalid_argument` exception if `index` is less than zero. - {2 Examples} + ## Examples - {[ - Array.splitAt([1, 2, 3, 4, 5], ~index=2) == ([1, 2], [3, 4, 5]) - Array.splitAt([1, 2, 3, 4, 5], ~index=10) == ([1, 2, 3, 4, 5], []) - Array.splitAt([1, 2, 3, 4, 5], ~index=0) == ([], [1, 2, 3, 4, 5]) - ]} -") + ```rescript + Array.splitAt([1, 2, 3, 4, 5], ~index=2) == ([1, 2], [3, 4, 5]) + Array.splitAt([1, 2, 3, 4, 5], ~index=10) == ([1, 2, 3, 4, 5], []) + Array.splitAt([1, 2, 3, 4, 5], ~index=0) == ([], [1, 2, 3, 4, 5]) + ``` +*/ let splitAt: (t<'a>, ~index: int) => (t<'a>, t<'a>) -@ocaml.doc(" Divides an array at the first element [f] returns [true] for. +/** Divides an array at the first element `f` returns `true` for. - Returns a {!Tuple2}, the first component contains the elements [f] returned false for, - the second component includes the element that [f] retutned [true] for an all the remaining elements. + Returns a [Tuple2](Tuple2.mdx#), the first component contains the elements `f` returned false for, + the second component includes the element that `f` retutned `true` for an all the remaining elements. - {2 Examples} + ## Examples - {[ - Array.splitWhen([5, 7, 8, 6, 4], ~f=Int.isEven) == ([5, 7], [8, 6, 4]) + ```rescript + Array.splitWhen([5, 7, 8, 6, 4], ~f=Int.isEven) == ([5, 7], [8, 6, 4]) - Array.splitWhen([\"Ant\", \"Bat\", \"Cat\"], ~f=animal => String.length(animal) > 3) == - ([\"Ant\", \"Bat\", \"Cat\"], []) + Array.splitWhen(["Ant", "Bat", "Cat"], ~f=animal => String.length(animal) > 3) == + (["Ant", "Bat", "Cat"], []) - Array.splitWhen([2., Float.pi, 1.111], ~f=Float.isInteger) == ([], [2., Float.pi, 1.111]) - ]} -") + Array.splitWhen([2., Float.pi, 1.111], ~f=Float.isInteger) == ([], [2., Float.pi, 1.111]) + ``` +*/ let splitWhen: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) -@ocaml.doc(" Decompose an array of {!Tuple2}s into a {!Tuple2} of arrays. +/** Decompose an array of [Tuple2](Tuple2.mdx#)s into a [Tuple2](Tuple2.mdx#) of arrays. - {2 Examples} + ## Examples - {[ - Array.unzip([(0, true), (17, false), (1337, true)]) == ([0, 17, 1337], [true, false, true]) - ]} -") + ```rescript + Array.unzip([(0, true), (17, false), (1337, true)]) == ([0, 17, 1337], [true, false, true]) + ``` +*/ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) -@@ocaml.text(" {1 Iterate} ") - -@ocaml.doc(" Iterates over the elements of invokes [f] for each element. +/** Iterates over the elements of invokes `f` for each element. - {2 Examples} + ## Examples - {[ - Array.forEach([1, 2, 3], ~f=int => Js.log(int)) - ]} -") + ```rescript + Array.forEach([1, 2, 3], ~f=int => Js.log(int)) + ``` +*/ let forEach: (t<'a>, ~f: 'a => unit) => unit -@ocaml.doc(" Iterates over the elements of invokes [f] for each element. +/** Iterates over the elements of invokes `f` for each element. - {2 Examples} + ## Examples - {[ - Array.forEachWithIndex([1, 2, 3], ~f=(index, int) => Js.log2(index, int)) - (* - 0 1 - 1 2 - 2 3 - *) - ]} -") + ```rescript + Array.forEachWithIndex([1, 2, 3], ~f=(index, int) => Js.log2(index, int)) + (* + 0 1 + 1 2 + 2 3 + *) + ``` +*/ let forEachWithIndex: (t<'a>, ~f: (int, 'a) => unit) => unit -@ocaml.doc(" Return all of the [Some] values from an array of options. +/** Return all of the `Some` values from an array of options. - {2 Examples} + ## Examples - {[ - Array.values([Some(\"Ant\"), None, Some(\"Cat\")]) == [\"Ant\", \"Cat\"] - Array.values([None, None, None]) == [] - ]} -") + ```rescript + Array.values([Some("Ant"), None, Some("Cat")]) == ["Ant", "Cat"] + Array.values([None, None, None]) == [] + ``` +*/ let values: t> => t<'a> -@ocaml.doc(" Places [sep] between all the elements of the given array. +/** Places `sep` between all the elements of the given array. - {2 Examples} + ## Examples - {[ - Array.intersperse(~sep=\"on\", [\"turtles\", \"turtles\", \"turtles\"]) - == [\"turtles\", \"on\", \"turtles\", \"on\", \"turtles\"]; + ```rescript + Array.intersperse(~sep="on", ["turtles", "turtles", "turtles"]) + == ["turtles", "on", "turtles", "on", "turtles"]; - Array.intersperse(~sep=0, []) == [] - ]} -") + Array.intersperse(~sep=0, []) == [] + ``` +*/ let intersperse: (t<'a>, ~sep: 'a) => t<'a> -@ocaml.doc(" Split an array into equally sized chunks. +/** Split an array into equally sized chunks. - If there aren't enough elements to make the last 'chunk', those elements are ignored. + If there aren't enough elements to make the last 'chunk', those elements are ignored. - {2 Examples} + ## Examples - {[ - Array.chunksOf([\"#FFBA49\", \"#9984D4\", \"#20A39E\", \"#EF5B5B\", \"#23001E\"], ~size=2) == [ - [\"#FFBA49\", \"#9984D4\"], - [\"#20A39E\", \"#EF5B5B\"], - ] - ]} - ") + ```rescript + Array.chunksOf(["#FFBA49", "#9984D4", "#20A39E", "#EF5B5B", "#23001E"], ~size=2) == [ + ["#FFBA49", "#9984D4"], + ["#20A39E", "#EF5B5B"], + ] + ``` + */ let chunksOf: (t<'a>, ~size: int) => t> -@ocaml.doc(" Provides a sliding 'window' of sub-arrays over an array. +/** Provides a sliding 'window' of sub-arrays over an array. - The first sub-array starts at index [0] of the array and takes the first [size] elements. + The first sub-array starts at index `0` of the array and takes the first `size` elements. - The sub-array then advances the index [step] (which defaults to 1) positions before taking the next [size] elements. + The sub-array then advances the index `step` (which defaults to 1) positions before taking the next `size` elements. - The sub-arrays are guaranteed to always be of length [size] and iteration stops once a sub-array would extend beyond the end of the array. + The sub-arrays are guaranteed to always be of length `size` and iteration stops once a sub-array would extend beyond the end of the array. - {2 Examples} + ## Examples - {[ - Array.sliding([1, 2, 3, 4, 5], ~size=1) == [[1], [2], [3], [4], [5]] - Array.sliding([1, 2, 3, 4, 5], ~size=2) == [[1, 2], [2, 3], [3, 4], [4, 5]] - Array.sliding([1, 2, 3, 4, 5], ~size=3) == [[1, 2, 3], [2, 3, 4], [3, 4, 5]] - Array.sliding([1, 2, 3, 4, 5], ~size=2, ~step=2) == [[1, 2], [3, 4]] - Array.sliding([1, 2, 3, 4, 5], ~size=1, ~step=3) == [[1], [4]] - ]} -") + ```rescript + Array.sliding([1, 2, 3, 4, 5], ~size=1) == [[1], [2], [3], [4], [5]] + Array.sliding([1, 2, 3, 4, 5], ~size=2) == [[1, 2], [2, 3], [3, 4], [4, 5]] + Array.sliding([1, 2, 3, 4, 5], ~size=3) == [[1, 2, 3], [2, 3, 4], [3, 4, 5]] + Array.sliding([1, 2, 3, 4, 5], ~size=2, ~step=2) == [[1, 2], [3, 4]] + Array.sliding([1, 2, 3, 4, 5], ~size=1, ~step=3) == [[1], [4]] + ``` +*/ let sliding: (~step: int=?, t<'a>, ~size: int) => t> -@@ocaml.text(" {1 Convert} ") +/** Converts an array of strings into a [String](String.mdx#), placing `sep` between each string in the result. -@ocaml.doc(" Converts an array of strings into a {!String}, placing [sep] between each string in the result. + ## Examples - {2 Examples} - - {[ - Array.join([\"Ant\", \"Bat\", \"Cat\"], ~sep=\", \") == \"Ant, Bat, Cat\" - ]} - ") + ```rescript + Array.join(["Ant", "Bat", "Cat"], ~sep=", ") == "Ant, Bat, Cat" + ``` + */ let join: (t, ~sep: string) => string -@ocaml.doc(" Collect elements where function [f] will produce the same key. +/** Collect elements where function `f` will produce the same key. - Produces a map from ['key] to a {!List} of all elements which produce the same ['key]. + Produces a map from `'key` to a [List](List.mdx#) of all elements which produce the same `'key`. - {2 Examples} + ## Examples - {[ - let animals = [\"Ant\", \"Bear\", \"Cat\", \"Dewgong\"] - Array.groupBy(animals, module(Int), ~f=String.length) == - Map.Int.fromArray([ - (3, list{\"Cat\", \"Ant\"}), - (4, list{\"Bear\"}), - (7, list{\"Dewgong\"}) - ]) - ]} -") + ```rescript + let animals = ["Ant", "Bear", "Cat", "Dewgong"] + Array.groupBy(animals, module(Int), ~f=String.length) == + Map.Int.fromArray([ + (3, list{"Cat", "Ant"}), + (4, list{"Bear"}), + (7, list{"Dewgong"}) + ]) + ``` +*/ let groupBy: ( t<'value>, TableclothComparator.s<'key, 'id>, ~f: 'value => 'key, ) => TableclothMap.t<'key, list<'value>, 'id> -@ocaml.doc(" Create a {!List} of elements from an array. +/** Create a [List](List.mdx#) of elements from an array. - {2 Examples} + ## Examples - {[ - Array.toList([1, 2, 3]) == list{1, 2, 3} - Array.toList(Array.fromList(list{3, 5, 8})) == list{3, 5, 8} - ]} -") + ```rescript + Array.toList([1, 2, 3]) == list{1, 2, 3} + Array.toList(Array.fromList(list{3, 5, 8})) == list{3, 5, 8} + ``` +*/ let toList: t<'a> => list<'a> -@ocaml.doc(" Create an indexed {!List} from an array. Each element of the array will be paired with its index as a {!Tuple2}. +/** Create an indexed [List](List.mdx#) from an array. Each element of the array will be paired with its index as a [Tuple2](Tuple2.mdx#). - {2 Examples} + ## Examples - {[ - Array.toIndexedList([\"cat\", \"dog\"]) == list{(0, \"cat\"), (1, \"dog\")} - ]} -") + ```rescript + Array.toIndexedList(["cat", "dog"]) == list{(0, "cat"), (1, "dog")} + ``` +*/ let toIndexedList: t<'a> => list<(int, 'a)> -@ocaml.doc(" Test two arrays for equality using the provided function to test pairs of elements. ") +/** Test two arrays for equality using the provided function to test pairs of elements. + + ## Examples + + ```rescript + Array.equal(["cat", "dog"], ["cat", "dog"], String.equal) === true + Array.equal(["cat", "dog"], ["parrot", "dog"], String.equal) === false + ``` +*/ let equal: (t<'a>, t<'a>, ('a, 'a) => bool) => bool -@ocaml.doc(" Compare two arrays using the provided [f] function to compare pairs of elements. +/** Compare two arrays using the provided `f` function to compare pairs of elements. - A shorter array is 'less' than a longer one. + A shorter array is 'less' than a longer one. - {2 Examples} + ## Examples - {[ - Array.compare([1, 2, 3], [1, 2, 3, 4], Int.compare) == -1 - Array.compare([1, 2, 3], [1, 2, 3], Int.compare) == 0 - Array.compare([1, 2, 5], [1, 2, 3], Int.compare) == 1 - ]} -") + ```rescript + Array.compare([1, 2, 3], [1, 2, 3, 4], Int.compare) == -1 + Array.compare([1, 2, 3], [1, 2, 3], Int.compare) == 0 + Array.compare([1, 2, 5], [1, 2, 3], Int.compare) == 1 + ``` +*/ let compare: (t<'a>, t<'a>, ('a, 'a) => int) => int diff --git a/src/TableclothBool.resi b/src/TableclothBool.resi index 92cb80e..5846c31 100644 --- a/src/TableclothBool.resi +++ b/src/TableclothBool.resi @@ -1,151 +1,139 @@ -@@ocaml.text(" ") - -@@ocaml.text(" Functions for working with boolean values. - - Booleans in Rescript are represented by the [true] and [false] literals. - - Whilst a bool isnt a variant, you will get warnings if you haven't - exhaustively pattern match on them: - - {[ - let bool = false - let string = switch bool { - | false => \"false\" - } - - (* - Warning number 8 - You forgot to handle a possible case here, for example: - true - *) - ]} -") - +/** Functions for working with boolean values. + + Booleans in Rescript are represented by the `true` and `false` literals. + + Whilst a bool isnt a variant, you will get warnings if you haven't + exhaustively pattern match on them: + + ```rescript + let bool = false + let string = switch bool { + | false => "false" + } + + (* + Warning number 8 + You forgot to handle a possible case here, for example: + true + *) + ``` +*/ type t = bool -@@ocaml.text(" {1 Create} ") +/** Convert an [Int](Int.mdx#) into a [Bool](Bool.mdx#). -@ocaml.doc(" Convert an {!Int} into a {!Bool}. + ## Examples - {2 Examples} - - {[ - Bool.fromInt(0) == Some(false) - Bool.fromInt(1) == Some(true) - Bool.fromInt(8) == None - Bool.fromInt(-3) == None - ]} -") + ```rescript + Bool.fromInt(0) == Some(false) + Bool.fromInt(1) == Some(true) + Bool.fromInt(8) == None + Bool.fromInt(-3) == None + ``` +*/ let fromInt: int => option -@ocaml.doc(" Convert a {!String} into a {!Bool}. +/** Convert a [String](String.mdx#) into a [Bool](Bool.mdx#). - {2 Examples} + ## Examples - {[ - Bool.fromString(\"true\") == Some(true) - Bool.fromString(\"false\") == Some(false) - Bool.fromString(\"True\") == None - Bool.fromString(\"False\") == None - Bool.fromString(\"0\") == None - Bool.fromString(\"1\") == None - Bool.fromString(\"Not even close\") == None - ]} -") + ```rescript + Bool.fromString("true") == Some(true) + Bool.fromString("false") == Some(false) + Bool.fromString("True") == None + Bool.fromString("False") == None + Bool.fromString("0") == None + Bool.fromString("1") == None + Bool.fromString("Not even close") == None + ``` +*/ let fromString: string => option -@@ocaml.text(" {1 Basic operations} ") - -@ocaml.doc(" The exclusive or operator. +/** The exclusive or operator. - Returns [true] if {b exactly one} of its operands is [true]. + Returns `true` if *exactly one* of its operands is `true`. - {2 Examples} + ## Examples - {[ - Bool.xor(true, true) == false - Bool.xor(true, false) == true - Bool.xor(false, true) == true - Bool.xor(false, false) == false - ]} -") + ```rescript + Bool.xor(true, true) == false + Bool.xor(true, false) == true + Bool.xor(false, true) == true + Bool.xor(false, false) == false + ``` +*/ let xor: (bool, bool) => bool -@ocaml.doc(" Negate a [bool]. +/** Negate a `bool`. - {2 Examples} + ## Examples - {[ - Bool.not(false) == true - Bool.not(true) == false - ]} -") + ```rescript + Bool.not(false) == true + Bool.not(true) == false + ``` +*/ let not: t => bool -@ocaml.doc(" The logical conjunction [AND] operator. +/** The logical conjunction `AND` operator. - Returns [true] if {b both} of its operands are [true]. - If the 'left' operand evaluates to [false], the 'right' operand is not evaluated. + Returns `true` if *both* of its operands are `true`. + If the 'left' operand evaluates to `false`, the 'right' operand is not evaluated. - {2 Examples} + ## Examples - {[ - Bool.and_(true, true) == true - Bool.and_(true, false) == false - Bool.and_(false, true) == false - Bool.and_(false, false) == false - ]} -") + ```rescript + Bool.and_(true, true) == true + Bool.and_(true, false) == false + Bool.and_(false, true) == false + Bool.and_(false, false) == false + ``` +*/ let and_: (bool, bool) => bool -@@ocaml.text(" {1 Convert} ") - -@ocaml.doc(" Convert a [bool] to a {!String} +/** Convert a `bool` to a [String](String.mdx#) - {2 Examples} + ## Examples - {[ - Bool.toString(true) == \"true\" - Bool.toString(false) == \"false\" - ]} -") + ```rescript + Bool.toString(true) == "true" + Bool.toString(false) == "false" + ``` +*/ let toString: bool => string -@ocaml.doc(" Convert a [bool] to an {!Int}. +/** Convert a `bool` to an [Int](Int.mdx#). - {2 Examples} + ## Examples - {[ - Bool.toInt(true) == 1 - Bool.toInt(false) == 0 - ]} -") + ```rescript + Bool.toInt(true) == 1 + Bool.toInt(false) == 0 + ``` +*/ let toInt: bool => int -@@ocaml.text(" {1 Compare} ") +/** Test for the equality of two `bool` values. -@ocaml.doc(" Test for the equality of two [bool] values. + ## Examples - {2 Examples} - - {[ - Bool.equal(true, true) == true - Bool.equal(false, false) == true - Bool.equal(false, true) == false - ]} -") + ```rescript + Bool.equal(true, true) == true + Bool.equal(false, false) == true + Bool.equal(false, true) == false + ``` +*/ let equal: (bool, bool) => bool -@ocaml.doc(" Compare two [bool] values. +/** Compare two `bool` values. - {2 Examples} + ## Examples - {[ - Bool.compare(true, false) == 1 - Bool.compare(false, true) == -1 - Bool.compare(true, true) == 0 - Bool.compare(false, false) == 0 - ]} -") + ```rescript + Bool.compare(true, false) == 1 + Bool.compare(false, true) == -1 + Bool.compare(true, true) == 0 + Bool.compare(false, false) == 0 + ``` +*/ let compare: (bool, bool) => int - diff --git a/src/TableclothChar.resi b/src/TableclothChar.resi index 19351a7..61aa1df 100644 --- a/src/TableclothChar.resi +++ b/src/TableclothChar.resi @@ -1,245 +1,232 @@ -@@ocaml.text(" ") +/** Functions for working with single characters. -@@ocaml.text(" Functions for working with single characters. + Character literals are enclosed in ['a'] pair of single quotes. - Character literals are enclosed in ['a'] pair of single quotes. + ```rescript + let digit = '7' + ``` - {[ - let digit = '7' - ]} - - The functions in this module work on ASCII characters (range 0-255) only, - {b not Unicode}. - - Note that in Rescript source code you can include only the characters from 0-127 range. - Full list of available characters is available {{: https://www.w3schools.com/charsets/ref_html_ascii.asp } here}. - - Characters from 128-255 range can still be handled, but only as codes. -") + The functions in this module work on ASCII characters (range 0-255) only, + *not Unicode*. + + Note that in Rescript source code you can include only the characters from 0-127 range. + Full list of available characters is available [here](https://www.w3schools.com/charsets/ref_html_ascii.asp). + Characters from 128-255 range can still be handled, but only as codes. +*/ type t = char -@@ocaml.text(" {1 Create} - - You can also create a {!Char} using single quotes: +/** Convert an ASCII [code point](https://en.wikipedia.org/wiki/Code_point) to a character. - {[ - let char = 'c' - ]} -") + The full range of extended ASCII is from `0` to `255`. + For numbers outside that range, you get `None`. -@ocaml.doc(" Convert an ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point } to a character. + ## Examples - The full range of extended ASCII is from [0] to [255]. - For numbers outside that range, you get [None]. - - {2 Examples} - - {[ - Char.fromCode(65) == Some('A') - Char.fromCode(66) == Some('B') - Char.fromCode(3000) == None - Char.fromCode(-1) == None - ]} -") + ```rescript + Char.fromCode(65) == Some('A') + Char.fromCode(66) == Some('B') + Char.fromCode(3000) == None + Char.fromCode(-1) == None + ``` +*/ let fromCode: int => option -@ocaml.doc(" Converts a string to character. +/** Converts a string to character. - Returns [None] when the [string] isn't of length one. + Returns `None` when the `string` isn't of length one. - {2 Examples} + ## Examples - {[ - Char.fromString(\"A\") == Some('A') - Char.fromString(\" \") == Some(' ') - Char.fromString(\"\") == None - Char.fromString(\"abc\") == None - Char.fromString(\" a\") == None - ]} -") + ```rescript + Char.fromString("A") == Some('A') + Char.fromString(" ") == Some(' ') + Char.fromString("") == None + Char.fromString("abc") == None + Char.fromString(" a") == None + ``` +*/ let fromString: string => option -@ocaml.doc(" Detect lower case ASCII characters. +/** Detect lower case ASCII characters. - {2 Examples} + ## Examples - {[ - Char.isLowercase('a') == true - Char.isLowercase('b') == true - Char.isLowercase('z') == true - Char.isLowercase('0') == false - Char.isLowercase('A') == false - Char.isLowercase('-') == false - ]} -") + ```rescript + Char.isLowercase('a') == true + Char.isLowercase('b') == true + Char.isLowercase('z') == true + Char.isLowercase('0') == false + Char.isLowercase('A') == false + Char.isLowercase('-') == false + ``` +*/ let isLowercase: char => bool -@ocaml.doc(" Detect upper case ASCII characters. +/** Detect upper case ASCII characters. - {2 Examples} + ## Examples - {[ - Char.isUppercase('A') == true - Char.isUppercase('B') == true - Char.isUppercase('Z') == true - Char.isUppercase('h') == false - Char.isUppercase('0') == false - Char.isUppercase('-') == false - ]} -") + ```rescript + Char.isUppercase('A') == true + Char.isUppercase('B') == true + Char.isUppercase('Z') == true + Char.isUppercase('h') == false + Char.isUppercase('0') == false + Char.isUppercase('-') == false + ``` +*/ let isUppercase: char => bool -@ocaml.doc(" Detect upper and lower case ASCII alphabetic characters. +/** Detect upper and lower case ASCII alphabetic characters. - {2 Examples} + ## Examples - {[ - Char.isLetter('a') == true - Char.isLetter('b') == true - Char.isLetter('E') == true - Char.isLetter('Y') == true - Char.isLetter('0') == false - Char.isLetter('-') == false - ]} -") + ```rescript + Char.isLetter('a') == true + Char.isLetter('b') == true + Char.isLetter('E') == true + Char.isLetter('Y') == true + Char.isLetter('0') == false + Char.isLetter('-') == false + ``` +*/ let isLetter: char => bool -@ocaml.doc(" Detect when a character is a number. +/** Detect when a character is a number. - {2 Examples} + ## Examples - {[ - Char.isDigit('0') == true - Char.isDigit('1') == true - Char.isDigit('9') == true - Char.isDigit('a') == false - Char.isDigit('b') == false - ]} -") + ```rescript + Char.isDigit('0') == true + Char.isDigit('1') == true + Char.isDigit('9') == true + Char.isDigit('a') == false + Char.isDigit('b') == false + ``` +*/ let isDigit: char => bool -@ocaml.doc(" Detect upper case, lower case and digit ASCII characters. +/** Detect upper case, lower case and digit ASCII characters. - {2 Examples} + ## Examples - {[ - Char.isAlphanumeric('a') == true - Char.isAlphanumeric('b') == true - Char.isAlphanumeric('E') == true - Char.isAlphanumeric('Y') == true - Char.isAlphanumeric('0') == true - Char.isAlphanumeric('7') == true - Char.isAlphanumeric('-') == false - ]} -") + ```rescript + Char.isAlphanumeric('a') == true + Char.isAlphanumeric('b') == true + Char.isAlphanumeric('E') == true + Char.isAlphanumeric('Y') == true + Char.isAlphanumeric('0') == true + Char.isAlphanumeric('7') == true + Char.isAlphanumeric('-') == false + ``` +*/ let isAlphanumeric: char => bool -@ocaml.doc(" Detect if a character is a {{: https://en.wikipedia.org/wiki/ASCII#Printable_characters } printable } character +/** Detect if a character is a [printable](https://en.wikipedia.org/wiki/ASCII#Printable_characters) character - A Printable character has a {!Char.toCode} in the range 32 to 127, inclusive ([' '] to ['~']). + A Printable character has a [Char.toCode](Char.mdx#toCode) in the range 32 to 127, inclusive (`' '` to `'~'`). - {2 Examples} + ## Examples - {[ - Char.isPrintable('G') == true - Char.isPrintable('%') == true - Char.isPrintable(' ') == true - Char.isPrintable('\t') == false - Char.isPrintable('\007') == false - ]} -") + ```rescript + Char.isPrintable('G') == true + Char.isPrintable('%') == true + Char.isPrintable(' ') == true + Char.isPrintable('\t') == false + Char.isPrintable('\007') == false + ``` +*/ let isPrintable: char => bool -@ocaml.doc(" Detect one of the following characters: - - ['\t'] (tab) - - ['\n'] (newline) - - ['\011'] (vertical tab) - - ['\012'] (form feed) - - ['\r'] (carriage return) - - [' '] (space) - - {2 Examples} - - {[ - Char.isWhitespace('\t') == true - Char.isWhitespace(' ') == true - Char.isWhitespace('?') == false - Char.isWhitespace('G') == false - ]} -") +/** Detect one of the following characters: + - `'\t'` (tab) + - `'\n'` (newline) + - `'\011'` (vertical tab) + - `'\012'` (form feed) + - `'\r'` (carriage return) + - `' '` (space) + + ## Examples + + ```rescript + Char.isWhitespace('\t') == true + Char.isWhitespace(' ') == true + Char.isWhitespace('?') == false + Char.isWhitespace('G') == false + ``` +*/ let isWhitespace: char => bool -@ocaml.doc(" Converts an ASCII character to lower case, preserving non alphabetic ASCII characters. +/** Converts an ASCII character to lower case, preserving non alphabetic ASCII characters. - {2 Examples} + ## Examples - {[ - Char.toLowercase('A') == 'a' - Char.toLowercase('B') == 'b' - Char.toLowercase('7') == '7' - ]} -") + ```rescript + Char.toLowercase('A') == 'a' + Char.toLowercase('B') == 'b' + Char.toLowercase('7') == '7' + ``` +*/ let toLowercase: char => char -@ocaml.doc(" Convert an ASCII character to upper case, preserving non alphabetic ASCII characters. +/** Convert an ASCII character to upper case, preserving non alphabetic ASCII characters. - {2 Examples} + ## Examples - {[ - Char.toUppercase('a') == 'A' - Char.toUppercase('b') == 'B' - Char.toUppercase('7') == '7' - ]} -") + ```rescript + Char.toUppercase('a') == 'A' + Char.toUppercase('b') == 'B' + Char.toUppercase('7') == '7' + ``` +*/ let toUppercase: char => char -@ocaml.doc(" Convert [char] to the corresponding ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point}. +/** Convert `char` to the corresponding ASCII [code point](https://en.wikipedia.org/wiki/Code_point). - {2 Examples} + ## Examples - {[ - Char.toCode('A') == 65 - Char.toCode('B') == 66 - ]} -") + ```rescript + Char.toCode('A') == 65 + Char.toCode('B') == 66 + ``` +*/ let toCode: char => int -@ocaml.doc(" Convert a character into a [string]. +/** Convert a character into a `string`. - {2 Examples} + ## Examples - {[ - Char.toString('A') == \"A\" - Char.toString('{') == \"{\" - Char.toString('7') == \"7\" - ]} -") + ```rescript + Char.toString('A') == "A" + Char.toString('{') == "{" + Char.toString('7') == "7" + ``` +*/ let toString: char => string -@ocaml.doc(" Converts a digit character to its corresponding {!Int}. +/** Converts a digit character to its corresponding [Int](Int.mdx#). - Returns [None] when the character isn't a digit. + Returns `None` when the character isn't a digit. - {2 Examples} + ## Examples - {[ - Char.toDigit(\"7\") == Some(7) - Char.toDigit(\"0\") == Some(0) - Char.toDigit(\"A\") == None - Char.toDigit(\"\") == None - ]} -") + ```rescript + Char.toDigit('7') == Some(7) + Char.toDigit('0') == Some(0) + Char.toDigit('A') == None + Char.toDigit('') == None + ``` +*/ let toDigit: char => option -@ocaml.doc(" Test two {!Char}s for equality ") +/** Test two [Char](Char.mdx#)s for equality */ let equal: (t, t) => bool -@ocaml.doc(" Compare two {!Char}s ") +/** Compare two [Char](Char.mdx#)s */ let compare: (t, t) => int -@ocaml.doc(" The unique identity for {!Comparator} ") +/** The unique identity for [Comparator](Comparator.mdx#) */ type identity let comparator: TableclothComparator.t - diff --git a/src/TableclothComparator.resi b/src/TableclothComparator.resi index 09aa75f..fc991d1 100644 --- a/src/TableclothComparator.resi +++ b/src/TableclothComparator.resi @@ -1,54 +1,50 @@ -@@ocaml.text(" ") +/** Comparator provide a way for custom data structures to be used with [Map](Map.mdx#)s and [Set](Set.mdx#)s. -@@ocaml.text(" Comparator provide a way for custom data structures to be used with {!Map}s and {!Set}s. + Say we have a module [Book] which we want to be able to create a [Set](Set.mdx#) of - Say we have a module [Book] which we want to be able to create a {!Set} of + ```rescript + module Book = { + type t = { + isbn: string, + title: string, + } - {[ - module Book = { - type t = { - isbn: string, - title: string, - } + let compare = (bookA, bookB) => String.compare(bookA.isbn, bookB.isbn) + } + ``` - let compare = (bookA, bookB) => String.compare(bookA.isbn, bookB.isbn) - } - ]} + First we need to make our module conform to the [S](#S) signature. - First we need to make our module conform to the {!S} signature. + This can be done by using the [Make](Make.mdx#) functor. - This can be done by using the {!Make} functor. + ```rescript + module Book = { + type t = { + isbn: string, + title: string, + } - {[ - module Book = { - type t = { - isbn: string, - title: string, - } + let compare = (bookA, bookB) => String.compare(bookA.isbn, bookB.isbn) - let compare = (bookA, bookB) => String.compare(bookA.isbn, bookB.isbn) + include Comparator.Make({ + type t = t - include Comparator.Make({ - type t = t + let compare = compare + }) + } + ``` - let compare = compare - }) - } - ]} - - Now we can create a Set of books: - - {[ - Set.fromArray(module(Book), - [ - {isbn: \"9788460767923\", title: \"Moby Dick or The Whale\"} - ]) - ]} -") + Now we can create a Set of books: + ```rescript + Set.fromArray(module(Book), + [ + {isbn: "9788460767923", title: "Moby Dick or The Whale"} + ]) + ``` +*/ module type T = { - @@ocaml.text(" T represents the input for the {!Make} functor. ") - + /** T represents the input for the [Make](Make.mdx#) functor. */ type t let compare: (t, t) => int @@ -56,12 +52,11 @@ module type T = { type t<'a, 'identity> -@ocaml.doc(" This just is an alias for {!t}. ") +/** This just is an alias for [t](#t). */ type comparator<'a, 'identity> = t<'a, 'identity> module type S = { - @@ocaml.text(" The output type of {!Make}. ") - + /** The output type of [Make](Make.mdx#). */ type t type identity @@ -70,29 +65,29 @@ module type S = { } @ocaml.doc( - " A type alias that is useful typing functions which accept first class modules like {!Map.empty} or {!Set.fromArray}. " + " A type alias that is useful typing functions which accept first class modules like [Map.empty](Map.mdx#empty) or [Set.fromArray](Set.mdx#fromArray). " ) type s<'a, 'identity> = module(S with type identity = 'identity and type t = 'a) -@ocaml.doc(" Create a new comparator by providing a module which satisifies {!T}. +/** Create a new comparator by providing a module which satisifies [T](#T). - {2 Examples} + ## Examples - {[ - module Book = { - module T = { - type t = { - isbn: string, - title: string, - } - let compare = (bookA, bookB) => String.compare(bookA.isbn, bookB.isbn) - } + ```rescript + module Book = { + module T = { + type t = { + isbn: string, + title: string, + } + let compare = (bookA, bookB) => String.compare(bookA.isbn, bookB.isbn) + } - include T - include Comparator.Make(T) - } + include T + include Comparator.Make(T) + } - let books = Set.empty(module(Book)) - ]} -") + let books = Set.empty(module(Book)) + ``` +*/ module Make: (M: T) => (S with type t := M.t) diff --git a/src/TableclothContainer.res b/src/TableclothContainer.res index 9d2eb56..060ef29 100644 --- a/src/TableclothContainer.res +++ b/src/TableclothContainer.res @@ -1,12 +1,10 @@ -@@ocaml.text(" This module contains module signatures which are used in functions which +/** This module contains module signatures which are used in functions which accept first class modules. -") - +*/ module type Sum = { - @@ocaml.text(" Modules which conform to this signature can be used with functions like - {!Array.sum} or {!List.sum}. - ") - + /** Modules which conform to this signature can be used with functions like + [Array.sum](Array.mdx#sum) or [List.sum](List.mdx#sum). + */ type t let zero: t diff --git a/src/TableclothFloat.resi b/src/TableclothFloat.resi index 01bc80e..d848075 100644 --- a/src/TableclothFloat.resi +++ b/src/TableclothFloat.resi @@ -1,577 +1,555 @@ -@@ocaml.text(" ") - -@@ocaml.text(" A module for working with {{: https://en.wikipedia.org/wiki/Floating-point_arithmetic } floating-point numbers}. - - Valid syntax for [float]s includes: - {[ - 0. - 42. - 42.0 - 3.14 - -0.1234 - 123_456.123_456 - 6.022e23 // = (6.022 * 10^23) - 6.022e+23 // = (6.022 * 10^23) - 1.602e-19 // = (1.602 * 10^-19) - 1e3 // = (1 * 10 ** 3) = 1000. - ]} - - {b Historical Note: } The particular details of floats (e.g. [NaN]) are - specified by {{: https://en.wikipedia.org/wiki/IEEE_754 } IEEE 754 } which is literally hard-coded into almost all - CPUs in the world. -") - +/** A module for working with [ floating-point numbers](https://en.wikipedia.org/wiki/Floating-point_arithmetic). + + Valid syntax for `float`s includes: + ```rescript + 0. + 42. + 42.0 + 3.14 + -0.1234 + 123_456.123_456 + 6.022e23 // = (6.022 * 10^23) + 6.022e+23 // = (6.022 * 10^23) + 1.602e-19 // = (1.602 * 10^-19) + 1e3 // = (1 * 10 ** 3) = 1000. + ``` + + *Historical Note: * The particular details of floats (e.g. `NaN`) are + specified by [ IEEE 754 ](https://en.wikipedia.org/wiki/IEEE_754) which is literally hard-coded into almost all + CPUs in the world. +*/ type t = float -@@ocaml.text(" {1 Constants} ") - -@ocaml.doc(" The literal [0.0] as a named value. ") +/** The literal `0.0` as a named value. */ let zero: t -@ocaml.doc(" The literal [1.0] as a named value. ") +/** The literal `1.0` as a named value. */ let one: t -@ocaml.doc(" [NaN] as a named value. NaN stands for {{: https://en.wikipedia.org/wiki/NaN } not a number}. +/** `NaN` as a named value. NaN stands for [ not a number](https://en.wikipedia.org/wiki/NaN). - {b Note } comparing values with {!Float.nan} will {b always return } [false] even if the value you are comparing against is also [NaN]. + *Note:* comparing values with [Float.nan](Float.mdx#nan) will *always return* `false` even if the value you are comparing against is also `NaN`. - For detecting [NaN] you should use {!Float.isNaN} + For detecting `NaN` you should use [Float.isNaN](Float.mdx#isNaN) - {2 Examples} + ## Examples - {[ - let isNotANumber = x => Float.equal(x, nan) + ```rescript + let isNotANumber = x => Float.equal(x, nan) - isNotANumber(nan) == false - ]} -") + isNotANumber(nan) == false + ``` +*/ let nan: t -@ocaml.doc(" Positive {{: https://en.wikipedia.org/wiki/IEEE_754-1985#Positive_and_negative_infinity } infinity}. +/** Positive [ infinity](https://en.wikipedia.org/wiki/IEEE_754-1985#Positive_and_negative_infinity). - {[ - Float.divide(Float.pi, ~by=0.0) == Float.infinity - ]} -") + ```rescript + Float.divide(Float.pi, ~by=0.0) == Float.infinity + ``` +*/ let infinity: t -@ocaml.doc(" Negative infinity, see {!Float.infinity}. ") +/** Negative infinity, see [Float.infinity](Float.mdx#infinity). */ let negativeInfinity: t -@ocaml.doc( - " An approximation of {{: https://en.wikipedia.org/wiki/E_(mathematical_constant) } Euler's number}. " -) +/** An approximation of [ Euler's number](https://en.wikipedia.org/wiki/E_(mathematical_constant)). */ let e: t -@ocaml.doc(" An approximation of {{: https://en.wikipedia.org/wiki/Pi } pi}. ") +/** An approximation of [ pi](https://en.wikipedia.org/wiki/Pi). */ let pi: t -@ocaml.doc(" The smallest interval between two representable numbers. ") +/** The smallest interval between two representable numbers. */ let epsilon: t -@ocaml.doc(" The largest (furthest from zero) representable positive [float]. - Has a value of approximately [1.79E+308], or 1.7976931348623157 * 10^308. - Values larger than [largestValue] are represented as Infinity. -") +/** The largest (furthest from zero) representable positive `float`. + Has a value of approximately `1.79E+308`, or 1.7976931348623157 * 10^308. + Values larger than `largestValue` are represented as Infinity. +*/ let largestValue: t -@ocaml.doc(" The smallest representable positive [float]. - The closest to zero without actually being zero. - Has a value of approximately [5E-324], in browsers and in Node.js is 2^-1074 - ") +/** The smallest representable positive `float`. + The closest to zero without actually being zero. + Has a value of approximately `5E-324`, in browsers and in Node.js is 2^-1074 + */ let smallestValue: t -@ocaml.doc(" Represents the maximum safe integer in JS. [Number]s in JS are represented as a 64-bit floating point - {{: https://en.wikipedia.org/wiki/IEEE_754 } IEEE 754 } numbers. - [maximumSafeInteger] has a value of 2^53 - 1 === [9_007_199_254_740_991.0]. - Values larger cannot be represented exactly and cannot be correctly compared. +/** Represents the maximum safe integer in JS. [Number]s in JS are represented as a 64-bit floating point + [ IEEE 754 ](https://en.wikipedia.org/wiki/IEEE_754) numbers. + `maximumSafeInteger` has a value of 2^53 - 1 === `9_007_199_254_740_991.0`. + Values larger cannot be represented exactly and cannot be correctly compared. - Defined as Float since integers in Rescript are limited to 32-bits, their max value is 2^31 - 1 === [2_147_483_647] - See also: {!Int.maximumValue} -") + Defined as Float since integers in Rescript are limited to 32-bits, their max value is 2^31 - 1 === `2_147_483_647` + See also: [Int.maximumValue](Int.mdx#maximumValue) +*/ let maximumSafeInteger: t -@ocaml.doc(" Represents the minimum safe integer in JS. [Number]s in JS are represented as a 64-bit floating point - {{: https://en.wikipedia.org/wiki/IEEE_754 } IEEE 754 } numbers. - [minimumSafeInteger] has a value of -2^53 - 1 === [-9_007_199_254_740_991.0]. - Values larger cannot be represented exactly and cannot be correctly compared. +/** Represents the minimum safe integer in JS. [Number]s in JS are represented as a 64-bit floating point + [ IEEE 754 ](https://en.wikipedia.org/wiki/IEEE_754) numbers. + `minimumSafeInteger` has a value of -2^53 - 1 === `-9_007_199_254_740_991.0`. + Values larger cannot be represented exactly and cannot be correctly compared. - Defined as Float since Rescript integers are limited to 32-bits, their min value is -2^31 - 1 === [-2_147_483_647] - See also: {!Int.minimumValue} -") + Defined as Float since Rescript integers are limited to 32-bits, their min value is -2^31 - 1 === `-2_147_483_647` + See also: [Int.minimumValue](Int.mdx#minimumValue) +*/ let minimumSafeInteger: t -@@ocaml.text(" {1 Create} ") +/** Convert an [Int](Int.mdx#) to a `float`. -@ocaml.doc(" Convert an {!Int} to a [float]. + ## Examples - {2 Examples} - - {[ - Float.fromInt(5) == 5.0 - Float.fromInt(0) == 0.0 - Float.fromInt(-7) == -7.0 - ]} -") + ```rescript + Float.fromInt(5) == 5.0 + Float.fromInt(0) == 0.0 + Float.fromInt(-7) == -7.0 + ``` +*/ let fromInt: int => t -@ocaml.doc(" Convert a {!String} to a [float]. - The behaviour of this function is platform specific. - Parses [Infinity] case-sensitive, [NaN] is case-insensitive. - - {2 Examples} - - {[ - Float.fromString(\"4.667\") == Some(4.667) - Float.fromString(\"-4.667\") == Some(-4.667) - Float.fromString(\"Hamster\") == None - Float.fromString(\"NaN\") == Some(Float.nan) - Float.fromString(\"nan\") == Some(Float.nan) - Float.fromString(\"Infinity\") == Some(Float.infinity) - ]} -") -let fromString: string => option +/** Convert a [String](String.mdx#) to a `float`. + Parses `Infinity` case-sensitive, `NaN` is case-insensitive. -@@ocaml.text(" {1 Basic arithmetic and operators} ") + ## Examples -@ocaml.doc(" Addition for floating point numbers. + ```rescript + Float.fromString("4.667") == Some(4.667) + Float.fromString("-4.667") == Some(-4.667) + Float.fromString("Hamster") == None + Float.fromString("NaN") == Some(Float.nan) + Float.fromString("nan") == Some(Float.nan) + Float.fromString("Infinity") == Some(Float.infinity) + ``` +*/ +let fromString: string => option + +/** Addition for floating point numbers. - Although [int]s and [float]s support many of the same basic operations such as - addition and subtraction you {b cannot} [add] an [int] and a [float] directly which - means you need to use functions like {!Int.toFloat} to convert both values to the same type. + Although `int`s and `float`s support many of the same basic operations such as + addition and subtraction you *cannot* `add` an `int` and a `float` directly which + means you need to use functions like [Int.toFloat](Int.mdx#toFloat) to convert both values to the same type. - So if you needed to add a {!Array.length} to a [float] for some reason, you - could: + So if you needed to add a [Array.length](Array.mdx#length) to a `float` for some reason, you + could: - {[ - [1, 2, 3]->Array.length->Int.toFloat->Float.add(3.5) == 6.5 - ]} + ```rescript + [1, 2, 3]->Array.length->Int.toFloat->Float.add(3.5) == 6.5 + ``` - Languages like Java and JavaScript automatically convert [int] values - to [float] values when you mix and match. This can make it difficult to be sure - exactly what type of number you are dealing with and cause unexpected behavior. + Languages like Java and JavaScript automatically convert `int` values + to `float` values when you mix and match. This can make it difficult to be sure + exactly what type of number you are dealing with and cause unexpected behavior. - Rescript has opted for a design that makes all conversions explicit. + Rescript has opted for a design that makes all conversions explicit. - {2 Examples} + ## Examples - {[ - Float.add(3.14, 3.14) == 6.28 + ```rescript + Float.add(3.14, 3.14) == 6.28 - 3.2 - ->Float.round - ->Float.toInt - ->Option.map(~f=int => int + Array.length([1, 2, 3])) == Some(6) - ]} -") + 3.2 + ->Float.round + ->Float.toInt + ->Option.map(~f=int => int + Array.length([1, 2, 3])) == Some(6) + ``` +*/ let add: (t, t) => t -@ocaml.doc(" Subtract numbers. +/** Subtract numbers. - {2 Examples} + ## Examples - {[ - Float.subtract(4.0, 3.0) == 1.0 - ]} -") + ```rescript + Float.subtract(4.0, 3.0) == 1.0 + ``` +*/ let subtract: (t, t) => t -@ocaml.doc(" Multiply numbers. +/** Multiply numbers. - {2 Examples} + ## Examples - {[ - Float.multiply(2.0, 7.0) == 14.0 - ]} -") + ```rescript + Float.multiply(2.0, 7.0) == 14.0 + ``` +*/ let multiply: (t, t) => t -@ocaml.doc(" Floating-point division. +/** Floating-point division. - {2 Examples} + ## Examples - {[ - Float.divide(3.14, ~by=2.0) == 1.57 - ]} -") + ```rescript + Float.divide(3.14, ~by=2.0) == 1.57 + ``` +*/ let divide: (t, ~by: t) => t -@ocaml.doc(" Exponentiation, takes the base first, then the exponent. +/** Exponentiation, takes the base first, then the exponent. - {2 Examples} + ## Examples - {[ - Float.power(~base=7.0, ~exponent=3.0) == 343.0 - ]} -") + ```rescript + Float.power(~base=7.0, ~exponent=3.0) == 343.0 + ``` +*/ let power: (~base: t, ~exponent: t) => t -@ocaml.doc(" Flips the 'sign' of a [float] so that positive floats become negative and negative integers become positive. Zero stays as it is. +/** Flips the 'sign' of a `float` so that positive floats become negative and negative integers become positive. Zero stays as it is. - {2 Examples} + ## Examples - {[ - Float.negate(8.) == -8. - Float.negate(-7.) == 7. - Float.negate(0.) == 0. - ]} -") + ```rescript + Float.negate(8.) == -8. + Float.negate(-7.) == 7. + Float.negate(0.) == 0. + ``` +*/ let negate: t => t -@ocaml.doc(" Get the {{: https://en.wikipedia.org/wiki/Absolute_value } absolute value} of a number. +/** Get the [ absolute value](https://en.wikipedia.org/wiki/Absolute_value) of a number. - {2 Examples} + ## Examples - {[ - Float.absolute(8.) == 8. - Float.absolute(-7) = 7 - Float.absolute(0) == 0 - ]} -") + ```rescript + Float.absolute(8.) == 8. + Float.absolute(-7) = 7 + Float.absolute(0) == 0 + ``` +*/ let absolute: t => t -@ocaml.doc(" Returns the larger of two [float]s, if both arguments are equal, returns the first argument +/** Returns the larger of two `float`s, if both arguments are equal, returns the first argument - If either (or both) of the arguments are [NaN], returns [NaN] + If either (or both) of the arguments are `NaN`, returns `NaN` - {2 Examples} + ## Examples - {[ - Float.maximum(7., 9.) == 9. - Float.maximum(-4., -1.) == -1. - Float.maximum(7., Float.nan)->Float.isNaN == true - ]} -") + ```rescript + Float.maximum(7., 9.) == 9. + Float.maximum(-4., -1.) == -1. + Float.maximum(7., Float.nan)->Float.isNaN == true + ``` +*/ let maximum: (t, t) => t -@ocaml.doc(" Returns the smaller of two [float]s, if both arguments are equal, returns the first argument. +/** Returns the smaller of two `float`s, if both arguments are equal, returns the first argument. - If either (or both) of the arguments are [NaN], returns [NaN]. + If either (or both) of the arguments are `NaN`, returns `NaN`. - {2 Examples} + ## Examples - {[ - Float.minimum(7.0, 9.0) == 7.0 - Float.minimum(-4.0, -1.0) == -4.0 - Float.minimum(7., Float.nan)->Float.isNaN == true - ]} -") + ```rescript + Float.minimum(7.0, 9.0) == 7.0 + Float.minimum(-4.0, -1.0) == -4.0 + Float.minimum(7., Float.nan)->Float.isNaN == true + ``` +*/ let minimum: (t, t) => t -@ocaml.doc(" Clamps [n] within the inclusive [lower] and [upper] bounds. +/** Clamps `n` within the inclusive `lower` and `upper` bounds. - {3 Exceptions} + ### Exceptions - Throws an [Invalid_argument] exception if [lower > upper]. + Throws an `Invalid_argument` exception if `lower > upper`. - {2 Examples} + ## Examples - {[ - Float.clamp(5.0, ~lower=0., ~upper=8.) == 5. - Float.clamp(9.0, ~lower=0., ~upper=8.) == 8. - Float.clamp(5.0, ~lower=-10., ~upper=-5.) == -5. - ]} -") + ```rescript + Float.clamp(5.0, ~lower=0., ~upper=8.) == 5. + Float.clamp(9.0, ~lower=0., ~upper=8.) == 8. + Float.clamp(5.0, ~lower=-10., ~upper=-5.) == -5. + ``` +*/ let clamp: (t, ~lower: t, ~upper: t) => t -@@ocaml.text(" {1 Fancier math} ") - -@ocaml.doc(" Take the square root of a number. +/** Take the square root of a number. - [squareRoot] returns [NaN] when its argument is negative. See {!Float.nan} for more. + `squareRoot` returns `NaN` when its argument is negative. See [Float.nan](Float.mdx#nan) for more. - {2 Examples} + ## Examples - {[ - Float.squareRoot(4.0) == 2.0 - Float.squareRoot(9.0) == 3.0 - ]} -") + ```rescript + Float.squareRoot(4.0) == 2.0 + Float.squareRoot(9.0) == 3.0 + ``` +*/ let squareRoot: t => t -@ocaml.doc(" Calculate the logarithm of a number with a given base. +/** Calculate the logarithm of a number with a given base. - {2 Examples} + ## Examples - {[ - Float.log(100., ~base=10.) == 2. - Float.log(256., ~base=2.) == 8. - ]} -") + ```rescript + Float.log(100., ~base=10.) == 2. + Float.log(256., ~base=2.) == 8. + ``` +*/ let log: (t, ~base: t) => t -@@ocaml.text(" {1 Query} ") +/** Determine whether a `float` is an `undefined` or unrepresentable number. -@ocaml.doc(" Determine whether a [float] is an [undefined] or unrepresentable number. + *Note:* this function is more useful than it might seem since `NaN` *does not* equal `NaN`: - {b Note: } this function is more useful than it might seem since [NaN] {b does not } equal [NaN]: + ```rescript + (Float.nan == Float.nan) == false + ``` - {[ - (Float.nan == Float.nan) == false - ]} + ## Examples - {2 Examples} - - {[ - Float.isNaN(0.0 /. 0.0) == true - Float.squareRoot(-1.0)->Float.isNaN == true - Float.isNaN(1.0 /. 0.0) == false (* Float.infinity {b is} a number *) - Float.isNaN(1.) == false - ]} -") + ```rescript + Float.isNaN(0.0 /. 0.0) == true + Float.squareRoot(-1.0)->Float.isNaN == true + Float.isNaN(1.0 /. 0.0) == false (* Float.infinity *is* a number *) + Float.isNaN(1.) == false + ``` +*/ let isNaN: t => bool -@ocaml.doc(" Determine whether a float is finite number. True for any float except [Infinity], [-Infinity] or [NaN] +/** Determine whether a float is finite number. True for any float except `Infinity`, `-Infinity` or `NaN` - Notice that [NaN] is not finite! + Notice that `NaN` is not finite! - {2 Examples} + ## Examples - {[ - Float.isFinite(0. /. 0.) == false - Float.squareRoot(-1.)->Float.isFinite == false - Float.isFinite(1. /. 0.) == false - Float.isFinite(1.) == true - Float.nan->Float.isFinite == false - ]} -") + ```rescript + Float.isFinite(0. /. 0.) == false + Float.squareRoot(-1.)->Float.isFinite == false + Float.isFinite(1. /. 0.) == false + Float.isFinite(1.) == true + Float.nan->Float.isFinite == false + ``` +*/ let isFinite: t => bool -@ocaml.doc(" Determine whether a float is positive or negative infinity. +/** Determine whether a float is positive or negative infinity. - {2 Examples} + ## Examples - {[ - Float.isInfinite(0. /. 0.) == false - Float.squareRoot(-1.)->Float.isInfinite == false - Float.isInfinite(1. /. 0.) == true - Float.isInfinite(1.) == false - Float.nan->Float.isInfinite == false - ]} -") + ```rescript + Float.isInfinite(0. /. 0.) == false + Float.squareRoot(-1.)->Float.isInfinite == false + Float.isInfinite(1. /. 0.) == true + Float.isInfinite(1.) == false + Float.nan->Float.isInfinite == false + ``` +*/ let isInfinite: t => bool -@ocaml.doc(" Determine whether the passed value is an integer. +/** Determine whether the passed value is an integer. - {2 Examples} + ## Examples - {[ - Float.isInteger(4.0) == true - Float.pi->Float.isInteger == false - ]} -") + ```rescript + Float.isInteger(4.0) == true + Float.pi->Float.isInteger == false + ``` +*/ let isInteger: t => bool -@ocaml.doc(" Determine whether the passed value is a safe integer (number between -(2**53 - 1) and 2**53 - 1). +/** Determine whether the passed value is a safe integer (number between -(2^53 - 1) and 2^53 - 1). - {2 Examples} + ## Examples - {[ - Float.isSafeInteger(4.0) == true - Float.isSafeInteger(Float.pi) == false - Float.isSafeInteger(Float.maximumSafeInteger +. 1.) == false - ]} -") + ```rescript + Float.isSafeInteger(4.0) == true + Float.isSafeInteger(Float.pi) == false + Float.isSafeInteger(Float.maximumSafeInteger +. 1.) == false + ``` +*/ let isSafeInteger: t => bool -@ocaml.doc(" Checks if a float is between [lower] and up to, but not including, [upper]. +/** Checks if a float is between `lower` and up to, but not including, `upper`. - If [lower] is not specified, it's set to to [0.0]. + If `lower` is not specified, it's set to to `0.0`. - {3 Exceptions} + ### Exceptions - Throws an [Invalid_argument] exception if [lower > upper] + Throws an `Invalid_argument` exception if `lower > upper` - {2 Examples} + ## Examples - {[ - Float.inRange(3., ~lower=2., ~upper=4.) == true - Float.inRange(2., ~lower=1., ~upper=2.) == false - Float.inRange(9.6, ~lower=5.2, ~upper=7.9) == false - ]} -") + ```rescript + Float.inRange(3., ~lower=2., ~upper=4.) == true + Float.inRange(2., ~lower=1., ~upper=2.) == false + Float.inRange(9.6, ~lower=5.2, ~upper=7.9) == false + ``` +*/ let inRange: (t, ~lower: t, ~upper: t) => bool -@@ocaml.text(" {1 Angles} ") - -@ocaml.doc(" This type is just an alias for [float]. +/** This type is just an alias for [float]. - Its purpose is to make understanding the signatures of the following - functions a little easier. -") + Its purpose is to make understanding the signatures of the following + functions a little easier. +*/ type radians = float -@ocaml.doc(" [hypotenuse x y] returns the length of the hypotenuse of a right-angled triangle with sides of length [x] and [y], or, equivalently, the distance of the point [(x, y)] to [(0, 0)]. +/** `hypotenuse(x,y)` returns the length of the hypotenuse of a right-angled triangle with sides of length `x` and `y`, or, equivalently, the distance of the point `(x, y)` to `(0, 0)`. - {2 Examples} + ## Examples - {[ - Float.hypotenuse(3., 4.) == 5. - ]} -") + ```rescript + Float.hypotenuse(3., 4.) == 5. + ``` +*/ let hypotenuse: (t, t) => t -@ocaml.doc(" Converts an angle in {{: https://en.wikipedia.org/wiki/Degree_(angle) } degrees} to {!Float.radians}. +/** Converts an angle in [ degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [Float.radians](Float.mdx#radians). - {2 Examples} + ## Examples - {[ - Float.degrees(180.) == Float.pi - Float.degrees(360.) == Float.pi *. 2. - Float.degrees(90.) == Float.pi /. 2. - ]} -") + ```rescript + Float.degrees(180.) == Float.pi + Float.degrees(360.) == Float.pi *. 2. + Float.degrees(90.) == Float.pi /. 2. + ``` +*/ let degrees: t => radians -@ocaml.doc(" Convert a {!Float.t} to {{: https://en.wikipedia.org/wiki/Radian } radians}. +/** Convert a [Float.t](Float.t.mdx#) to [ radians](https://en.wikipedia.org/wiki/Radian). - {b Note } This function doesn't actually do anything to its argument, but can be useful to indicate intent when inter-mixing angles of different units within the same function. + *Note:* This function doesn't actually do anything to its argument, but can be useful to indicate intent when inter-mixing angles of different units within the same function. - {2 Examples} + ## Examples - {[ - Float.pi->Float.radians == 3.141592653589793 - ]} -") + ```rescript + Float.pi->Float.radians == 3.141592653589793 + ``` +*/ let radians: t => radians -@ocaml.doc(" Convert an angle in {{: https://en.wikipedia.org/wiki/Turn_(geometry) } turns} into {!Float.radians}. +/** Convert an angle in [ turns](https://en.wikipedia.org/wiki/Turn_(geometry)) into [Float.radians](Float.mdx#radians). - One turn is equal to 360 degrees. + One turn is equal to 360 degrees. - {2 Examples} + ## Examples - {[ - Float.turns(1. /. 2.) == Float.pi - Float.turns(1.) == Float.degrees(360.) - ]} -") + ```rescript + Float.turns(1. /. 2.) == Float.pi + Float.turns(1.) == Float.degrees(360.) + ``` +*/ let turns: t => radians -@@ocaml.text(" {1 Polar coordinates} ") - -@ocaml.doc(" Convert {{: https://en.wikipedia.org/wiki/Polar_coordinate_system } polar coordinates } (radius, radians) to {{: https://en.wikipedia.org/wiki/Cartesian_coordinate_system } Cartesian coordinates } (x,y). +/** Convert [ polar coordinates ](https://en.wikipedia.org/wiki/Polar_coordinate_system) `(radius, radians)` to [ Cartesian coordinates ](https://en.wikipedia.org/wiki/Cartesian_coordinate_system) `(x,y)`. - {2 Examples} + ## Examples - {[ - Float.fromPolar((Float.squareRoot(2.), Float.degrees(45.))) == (1.0000000000000002, 1.) - ]} -") + ```rescript + Float.fromPolar((Float.squareRoot(2.), Float.degrees(45.))) == (1.0000000000000002, 1.) + ``` +*/ let fromPolar: ((float, radians)) => (float, float) -@ocaml.doc(" Convert {{: https://en.wikipedia.org/wiki/Cartesian_coordinate_system } Cartesian coordinates } [(x, y)] to {{: https://en.wikipedia.org/wiki/Polar_coordinate_system } polar coordinates } [(radius, radians)]. +/** Convert [ Cartesian coordinates ](https://en.wikipedia.org/wiki/Cartesian_coordinate_system) `(x, y)` to [ polar coordinates ](https://en.wikipedia.org/wiki/Polar_coordinate_system) `(radius, radians)`. - {2 Examples} + ## Examples - {[ - Float.toPolar((-1.0, 0.0)) == (1.0, Float.pi) - Float.toPolar((3.0, 4.0)) == (5.0, 0.9272952180016122) - Float.toPolar((5.0, 12.0)) == (13.0, 1.1760052070951352) - ]} -") + ```rescript + Float.toPolar((-1.0, 0.0)) == (1.0, Float.pi) + Float.toPolar((3.0, 4.0)) == (5.0, 0.9272952180016122) + Float.toPolar((5.0, 12.0)) == (13.0, 1.1760052070951352) + ``` +*/ let toPolar: ((float, float)) => (float, radians) -@ocaml.doc(" Figure out the cosine given an angle in {{: https://en.wikipedia.org/wiki/Radian } radians}. +/** Figure out the cosine given an angle in [ radians](https://en.wikipedia.org/wiki/Radian). - {2 Examples} + ## Examples - {[ - Float.degrees(60.)->Float.cos == 0.5000000000000001 - (Float.pi /. 3.)->Float.radians->Float.cos == 0.5000000000000001 - ]} -") + ```rescript + Float.degrees(60.)->Float.cos == 0.5000000000000001 + (Float.pi /. 3.)->Float.radians->Float.cos == 0.5000000000000001 + ``` +*/ let cos: radians => t -@ocaml.doc(" Figure out the arccosine for [adjacent / hypotenuse] in {{: https://en.wikipedia.org/wiki/Radian } radians}: +/** Figure out the arccosine for `adjacent / hypotenuse` in [ radians](https://en.wikipedia.org/wiki/Radian): - {2 Examples} + ## Examples - {[ - (Float.radians(1.0) /. 2.0)->Float.acos == Float.radians(1.0471975511965979) // 60 degrees or pi/3 radians - ]} -") + ```rescript + (Float.radians(1.0) /. 2.0)->Float.acos == Float.radians(1.0471975511965979) // 60 degrees or pi/3 radians + ``` +*/ let acos: radians => t -@ocaml.doc(" Figure out the sine given an angle in {{: https://en.wikipedia.org/wiki/Radian } radians}. +/** Figure out the sine given an angle in [ radians](https://en.wikipedia.org/wiki/Radian). - {2 Examples} + ## Examples - {[ - Float.degrees(30.)->Float.sin == 0.49999999999999994 - (Float.pi /. 6.)->Float.radians->Float.sin == 0.49999999999999994 - ]} -") + ```rescript + Float.degrees(30.)->Float.sin == 0.49999999999999994 + (Float.pi /. 6.)->Float.radians->Float.sin == 0.49999999999999994 + ``` +*/ let sin: radians => t -@ocaml.doc(" Figure out the arcsine for [opposite / hypotenuse] in {{: https://en.wikipedia.org/wiki/Radian } radians}: +/** Figure out the arcsine for `opposite / hypotenuse` in [ radians](https://en.wikipedia.org/wiki/Radian): - {2 Examples} + ## Examples - {[ - Float.asin(1.0 /. 2.0) == 0.5235987755982989 (* 30 degrees or pi / 6 radians *) - ]} -") + ```rescript + Float.asin(1.0 /. 2.0) == 0.5235987755982989 (* 30 degrees or pi / 6 radians *) + ``` +*/ let asin: radians => t -@ocaml.doc(" Figure out the tangent given an angle in radians. +/** Figure out the tangent given an angle in radians. - {2 Examples} + ## Examples - {[ - Float.degrees(45.)->Float.tan == 0.9999999999999999 - (Float.pi /. 4.)->Float.radians->Float.tan == 0.9999999999999999 - (Float.pi /. 4.)->Float.tan == 0.9999999999999999 - ]} -") + ```rescript + Float.degrees(45.)->Float.tan == 0.9999999999999999 + (Float.pi /. 4.)->Float.radians->Float.tan == 0.9999999999999999 + (Float.pi /. 4.)->Float.tan == 0.9999999999999999 + ``` +*/ let tan: radians => t -@ocaml.doc(" This helps you find the angle (in radians) to an [(x, y)] coordinate, but - in a way that is rarely useful in programming. +/** This helps you find the angle (in radians) to an `(x, y)` coordinate, but + in a way that is rarely useful in programming. - {b You probably want} {!atan2} instead! + *You probably want* [atan2](#atan2) instead! - This version takes [y / x] as its argument, so there is no way to know whether - the negative signs comes from the [y] or [x] value. So as we go counter-clockwise - around the origin from point [(1, 1)] to [(1, -1)] to [(-1,-1)] to [(-1,1)] we do - not get angles that go in the full circle: + This version takes `y / x` as its argument, so there is no way to know whether + the negative signs comes from the `y` or `x` value. So as we go counter-clockwise + around the origin from point `(1, 1)` to `(1, -1)` to `(-1,-1)` to `(-1,1)` we do + not get angles that go in the full circle: - Notice that everything is between [pi / 2] and [-pi/2]. That is pretty useless - for figuring out angles in any sort of visualization, so again, check out - {!Float.atan2} instead! + Notice that everything is between `pi / 2` and `-pi/2`. That is pretty useless + for figuring out angles in any sort of visualization, so again, check out + [Float.atan2](Float.mdx#atan2) instead! - {2 Examples} + ## Examples - {[ - Float.atan(1. /. 1.) == 0.7853981633974483 (* 45 degrees or pi/4 radians *) - Float.atan(1. /. -1.) == -0.7853981633974483 (* 315 degrees or 7 * pi / 4 radians *) - Float.atan(-1. /. -1.) == 0.7853981633974483 (* 45 degrees or pi/4 radians *) - Float.atan(-1. /. 1.) == -0.7853981633974483 (* 315 degrees or 7 * pi/4 radians *) - ]} -") + ```rescript + Float.atan(1. /. 1.) == 0.7853981633974483 (* 45 degrees or pi/4 radians *) + Float.atan(1. /. -1.) == -0.7853981633974483 (* 315 degrees or 7 * pi / 4 radians *) + Float.atan(-1. /. -1.) == 0.7853981633974483 (* 45 degrees or pi/4 radians *) + Float.atan(-1. /. 1.) == -0.7853981633974483 (* 315 degrees or 7 * pi/4 radians *) + ``` +*/ let atan: t => radians -@ocaml.doc(" This helps you find the angle (in radians) to an [(x, y)] coordinate. +/** This helps you find the angle (in radians) to an `(x, y)` coordinate. - So rather than [Float.(atan (y / x))] you can [Float.atan2 ~y ~x] and you can get a full range of angles: + So rather than `Float.(atan (y / x))` you can `Float.atan2(~y, ~x)` and you can get a full range of angles: - {2 Examples} + ## Examples - {[ - Float.atan2(~y=1., ~x=1.) == 0.7853981633974483 (* 45 degrees or pi/4 radians *) - Float.atan2(~y=1., ~x=-1.) == 2.3561944901923449 (* 135 degrees or 3 * pi/4 radians *) - Float.atan2(~y=-1., ~x=-1.) == -2.3561944901923449 (* 225 degrees or 5 * pi/4 radians *) - Float.atan2(~y=-1., ~x=1.) == -0.7853981633974483 (* 315 degrees or 7 * pi/4 radians *) - ]} -") + ```rescript + Float.atan2(~y=1., ~x=1.) == 0.7853981633974483 (* 45 degrees or pi/4 radians *) + Float.atan2(~y=1., ~x=-1.) == 2.3561944901923449 (* 135 degrees or 3 * pi/4 radians *) + Float.atan2(~y=-1., ~x=-1.) == -2.3561944901923449 (* 225 degrees or 5 * pi/4 radians *) + Float.atan2(~y=-1., ~x=1.) == -0.7853981633974483 (* 315 degrees or 7 * pi/4 radians *) + ``` +*/ let atan2: (~y: t, ~x: t) => radians -@@ocaml.text(" {1 Rounding} ") +/** The possible `direction`s availible when doing [Float.round](Float.mdx#round). -@ocaml.doc(" The possible [direction]s availible when doing {!Float.round}. - - See {!Float.round} for what each variant represents. - ") + See [Float.round](Float.mdx#round) for what each variant represents. + */ type direction = [ | #Zero | #AwayFromZero @@ -580,193 +558,189 @@ type direction = [ | #Closest([#Zero | #AwayFromZero | #Up | #Down | #ToEven]) ] -@ocaml.doc(" Round a number, by default to the to the closest [int] with halves rounded [#Up] (towards positive infinity). +/** Round a number, by default to the to the closest `int` with halves rounded `#Up` (towards positive infinity). - Other rounding strategies are available by using the optional [~direction] labelelled. + Other rounding strategies are available by using the optional `~direction` labelelled. - {2 Examples} + ## Examples - {[ - Float.round(1.2) == 1.0 - Float.round(1.5) == 2.0 - Float.round(1.8) == 2.0 - Float.round(-1.2) == -1.0 - Float.round(-1.5) == -1.0 - Float.round(-1.8) == -2.0 - ]} + ```rescript + Float.round(1.2) == 1.0 + Float.round(1.5) == 2.0 + Float.round(1.8) == 2.0 + Float.round(-1.2) == -1.0 + Float.round(-1.5) == -1.0 + Float.round(-1.8) == -2.0 + ``` - {3 Towards zero} + ### Towards zero - {[ - Float.round(1.2, ~direction=#Zero) == 1.0 - Float.round(1.5, ~direction=#Zero) == 1.0 - Float.round(1.8, ~direction=#Zero) == 1.0 - Float.round(-1.2, ~direction=#Zero) == -1.0 - Float.round(-1.5, ~direction=#Zero) == -1.0 - Float.round(-1.8, ~direction=#Zero) == -1.0 - ]} + ```rescript + Float.round(1.2, ~direction=#Zero) == 1.0 + Float.round(1.5, ~direction=#Zero) == 1.0 + Float.round(1.8, ~direction=#Zero) == 1.0 + Float.round(-1.2, ~direction=#Zero) == -1.0 + Float.round(-1.5, ~direction=#Zero) == -1.0 + Float.round(-1.8, ~direction=#Zero) == -1.0 + ``` - {3 Away from zero} + ### Away from zero - {[ - Float.round(1.2, ~direction=#AwayFromZero) == 2.0 - Float.round(1.5, ~direction=#AwayFromZero) == 2.0 - Float.round(1.8, ~direction=#AwayFromZero) == 2.0 - Float.round(-1.2, ~direction=#AwayFromZero) == -2.0 - Float.round(-1.5, ~direction=#AwayFromZero) == -2.0 - Float.round(-1.8, ~direction=#AwayFromZero) == -2.0 - ]} + ```rescript + Float.round(1.2, ~direction=#AwayFromZero) == 2.0 + Float.round(1.5, ~direction=#AwayFromZero) == 2.0 + Float.round(1.8, ~direction=#AwayFromZero) == 2.0 + Float.round(-1.2, ~direction=#AwayFromZero) == -2.0 + Float.round(-1.5, ~direction=#AwayFromZero) == -2.0 + Float.round(-1.8, ~direction=#AwayFromZero) == -2.0 + ``` - {3 Towards infinity} + ### Towards infinity - This is also known as {!Float.ceiling}. + This is also known as [Float.ceiling](Float.mdx#ceiling). - {[ - Float.round(1.2, ~direction=#Up) == 2.0 - Float.round(1.5, ~direction=#Up) == 2.0 - Float.round(1.8, ~direction=#Up) == 2.0 - Float.round(-1.2, ~direction=#Up) == -1.0 - Float.round(-1.5, ~direction=#Up) == -1.0 - Float.round(-1.8, ~direction=#Up) == -1.0 - ]} + ```rescript + Float.round(1.2, ~direction=#Up) == 2.0 + Float.round(1.5, ~direction=#Up) == 2.0 + Float.round(1.8, ~direction=#Up) == 2.0 + Float.round(-1.2, ~direction=#Up) == -1.0 + Float.round(-1.5, ~direction=#Up) == -1.0 + Float.round(-1.8, ~direction=#Up) == -1.0 + ``` - {3 Towards negative infinity} + ### Towards negative infinity - This is also known as {!Float.floor}. + This is also known as [Float.floor](Float.mdx#floor). - {[ - Array.map( - [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], - ~f=Float.round(~direction=#Down), - ) == [-2.0, -2.0, -2.0, 1.0, 1.0, 1.0] - ]} + ```rescript + Array.map( + [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], + ~f=Float.round(~direction=#Down), + ) == [-2.0, -2.0, -2.0, 1.0, 1.0, 1.0] + ``` - {3 To the closest integer} + ### To the closest integer - Rounding a number [x] to the closest integer requires some tie-breaking for when the [fraction] part of [x] is exactly [0.5]. + Rounding a number `x` to the closest integer requires some tie-breaking for when the [fraction] part of `x` is exactly [0.5]. - {3 Halves rounded towards zero} + ### Halves rounded towards zero - {[ - Array.map( - [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], - ~f=Float.round(~direction=#Closest(#Zero)), - ) == [-2.0, -1.0, -1.0, 1.0, 1.0, 2.0] - ]} + ```rescript + Array.map( + [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], + ~f=Float.round(~direction=#Closest(#Zero)), + ) == [-2.0, -1.0, -1.0, 1.0, 1.0, 2.0] + ``` - {3 Halves rounded away from zero} + ### Halves rounded away from zero - This method is often known as {b commercial rounding}. + This method is often known as *commercial rounding*. - {[ - Array.map( - [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], - ~f=Float.round(~direction=#Closest(#AwayFromZero)), - ) == [-2.0, -2.0, -1.0, 1.0, 2.0, 2.0] - ]} + ```rescript + Array.map( + [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], + ~f=Float.round(~direction=#Closest(#AwayFromZero)), + ) == [-2.0, -2.0, -1.0, 1.0, 2.0, 2.0] + ``` - {3 Halves rounded down} + ### Halves rounded down - {[ - Array.map( - [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], - ~f=Float.round(~direction=#Closest(#Down)), - ) == [-2.0, -2.0, -1.0, 1.0, 1.0, 2.0] - ]} + ```rescript + Array.map( + [-1.8, -1.5, -1.2, 1.2, 1.5, 1.8], + ~f=Float.round(~direction=#Closest(#Down)), + ) == [-2.0, -2.0, -1.0, 1.0, 1.0, 2.0] + ``` - {3 Halves rounded up} + ### Halves rounded up - This is the default. + This is the default. - [Float.round(1.5)] is the same as [Float.round(1.5, ~direction=#Closest(#Up))] + `Float.round(1.5)` is the same as `Float.round(1.5, ~direction=#Closest(#Up))` - {3 Halves rounded towards the closest even number} + ### Halves rounded towards the closest even number - {[ - Float.round(-1.5, ~direction=#Closest(#ToEven)) == -2.0 - Float.round(-2.5, ~direction=#Closest(#ToEven)) == -2.0 - ]} -") + ```rescript + Float.round(-1.5, ~direction=#Closest(#ToEven)) == -2.0 + Float.round(-2.5, ~direction=#Closest(#ToEven)) == -2.0 + ``` +*/ let round: (~direction: direction=?, t) => t -@ocaml.doc(" Floor function, equivalent to [Float.round(~direction=#Down)]. +/** Floor function, equivalent to `Float.round(~direction=#Down)`. - {2 Examples} + ## Examples - {[ - Float.floor(1.2) == 1.0 - Float.floor(1.5) == 1.0 - Float.floor(1.8) == 1.0 - Float.floor(-1.2) == -2.0 - Float.floor(-1.5) == -2.0 - Float.floor(-1.8) == -2.0 - ]} -") + ```rescript + Float.floor(1.2) == 1.0 + Float.floor(1.5) == 1.0 + Float.floor(1.8) == 1.0 + Float.floor(-1.2) == -2.0 + Float.floor(-1.5) == -2.0 + Float.floor(-1.8) == -2.0 + ``` +*/ let floor: t => t -@ocaml.doc(" Ceiling function, equivalent to [Float.round(~direction=#Up)]. +/** Ceiling function, equivalent to `Float.round(~direction=#Up)`. - {2 Examples} + ## Examples - {[ - Float.ceiling(1.2) == 2.0 - Float.ceiling(1.5) == 2.0 - Float.ceiling(1.8) == 2.0 - Float.ceiling(-1.2) == -1.0 - Float.ceiling(-1.5) == -1.0 - Float.ceiling(-1.8) == -1.0 - ]} -") + ```rescript + Float.ceiling(1.2) == 2.0 + Float.ceiling(1.5) == 2.0 + Float.ceiling(1.8) == 2.0 + Float.ceiling(-1.2) == -1.0 + Float.ceiling(-1.5) == -1.0 + Float.ceiling(-1.8) == -1.0 + ``` +*/ let ceiling: t => t -@ocaml.doc(" Ceiling function, equivalent to [Float.round(~direction=#Zero)]. +/** Ceiling function, equivalent to `Float.round(~direction=#Zero)`. - {2 Examples} + ## Examples - {[ - Float.truncate(1.0) == 1. - Float.truncate(1.2) == 1. - Float.truncate(1.5) == 1. - Float.truncate(1.8) == 1. - Float.truncate(-1.2) == -1. - Float.truncate(-1.5) == -1. - Float.truncate(-1.8) == -1. - ]} -") + ```rescript + Float.truncate(1.0) == 1. + Float.truncate(1.2) == 1. + Float.truncate(1.5) == 1. + Float.truncate(1.8) == 1. + Float.truncate(-1.2) == -1. + Float.truncate(-1.5) == -1. + Float.truncate(-1.8) == -1. + ``` +*/ let truncate: t => t -@@ocaml.text(" {1 Convert} ") - -@ocaml.doc(" Converts a [float] to an {!Int} by {b ignoring the decimal portion}. See {!Float.truncate} for examples. +/** Converts a `float` to an [Int](Int.mdx#) by *ignoring the decimal portion*. See [Float.truncate](Float.mdx#truncate) for examples. - Returns [None] when trying to round a [float] which can't be represented as an [int] such as {!Float.nan} or {!Float.infinity} or numbers which are too large or small. + Returns `None` when trying to round a `float` which can't be represented as an `int` such as [Float.nan](Float.mdx#nan) or [Float.infinity](Float.mdx#infinity) or numbers which are too large or small. - You probably want to use some form of {!Float.round} prior to using this function. + You probably want to use some form of [Float.round](Float.mdx#round) prior to using this function. - {2 Examples} + ## Examples - {[ - Float.toInt(1.6) == Some(1) - Float.toInt(2.0) == Some(2)) - Float.toInt(5.683) == Some(5) - Float.nan->Float.toInt == None - Float.infinity->Float.toInt == None - Float.round(1.6)->Float.toInt) = Some(2) - ]} -") + ```rescript + Float.toInt(1.6) == Some(1) + Float.toInt(2.0) == Some(2)) + Float.toInt(5.683) == Some(5) + Float.nan->Float.toInt == None + Float.infinity->Float.toInt == None + Float.round(1.6)->Float.toInt) = Some(2) + ``` +*/ let toInt: t => option -@ocaml.doc(" Convert a [float] to a {!String} - The behaviour of this function is platform specific +/** Convert a `float` to a [String](String.mdx#) + The behaviour of this function is platform specific - Returns a string representation of the float in base 10. -") + Returns a string representation of the float in base 10. +*/ let toString: t => string -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two floats for equality. ") +/** Test two floats for equality. */ let equal: (t, t) => bool -@ocaml.doc(" Compare two floats. ") +/** Compare two floats. */ let compare: (t, t) => int diff --git a/src/TableclothFun.resi b/src/TableclothFun.resi index ecbeb6f..d718fe4 100644 --- a/src/TableclothFun.resi +++ b/src/TableclothFun.resi @@ -1,205 +1,202 @@ -@@ocaml.text(" ") +/** Functions for working with functions. -@@ocaml.text(" Functions for working with functions. + While the functions in this module can often make code more concise, this + often imposes a readability burden on future readers. +*/ +/** Given a value, returns exactly the same value. This may seem pointless at first glance but it can often be useful when an api offers you more control than you actually need. - While the functions in this module can often make code more concise, this - often imposes a readability burden on future readers. -") + Perhaps you want to create an array of integers -@ocaml.doc(" Given a value, returns exactly the same value. This may seem pointless at first glance but it can often be useful when an api offers you more control than you actually need. + ```rescript + Array.initialize(6, ~f=Fun.identity) == [0, 1, 2, 3, 4, 5] + ``` - Perhaps you want to create an array of integers + (In this particular case you probably want to use [Array.range](Array.mdx#range).) - {[ - Array.initialize(6, ~f=Fun.identity) == [0, 1, 2, 3, 4, 5] - ]} + Or maybe you need to register a callback, but dont want to do anything: - (In this particular case you probably want to use {!Array.range}.) - - Or maybe you need to register a callback, but dont want to do anything: - - {[ - let httpMiddleware = HttpLibrary.createMiddleWare( - ~onEventYouDoCareAbout=transformAndReturn, - ~onEventYouDontCareAbout=Fun.identity, - ) - ]} -") + ```rescript + let httpMiddleware = HttpLibrary.createMiddleWare( + ~onEventYouDoCareAbout=transformAndReturn, + ~onEventYouDontCareAbout=Fun.identity, + ) + ``` +*/ external identity: 'a => 'a = "%identity" -@ocaml.doc(" Discards the value it is given and returns [()] +/** Discards the value it is given and returns `()` - This is primarily useful when working with imperative side-effecting code - or to avoid [unused value] compiler warnings when you really meant it, - and haven't just made a mistake. + This is primarily useful when working with imperative side-effecting code + or to avoid `unused value` compiler warnings when you really meant it, + and haven't just made a mistake. - {2 Examples} + ## Examples - {[ - (* Pretend we have a module with the following signature: - module type PretendMutableQueue = { - type t<'a> + ```rescript + (* Pretend we have a module with the following signature: + module type PretendMutableQueue = { + type t<'a> - (** Adds an element to the queue, returning the new length of the queue *) - let pushReturningLength: (t<'a>, 'a) => int - } - *) + (** Adds an element to the queue, returning the new length of the queue *) + let pushReturningLength: (t<'a>, 'a) => int + } + *) - let addArrayToQueue = (queue, array) => - Array.forEach(array, ~f=element => - PretendMutableQueue.pushReturningLength(queue, element) - )->Fun.ignore - ]} -") + let addArrayToQueue = (queue, array) => + Array.forEach(array, ~f=element => + PretendMutableQueue.pushReturningLength(queue, element) + )->Fun.ignore + ``` +*/ external ignore: _ => unit = "%ignore" -@ocaml.doc(" Create a function that {b always} returns the same value. +/** Create a function that *always* returns the same value. - Useful with functions like {!List.map} or {!Array.initialize}. + Useful with functions like [List.map](List.mdx#map) or [Array.initialize](Array.mdx#initialize). - {2 Examples} + ## Examples - {[ - Array.map([1, 2, 3, 4, 5], ~f=Fun.constant(0)) == [0, 0, 0, 0, 0] - Array.initialize(6, ~f=Fun.constant(0)) == [0, 0, 0, 0, 0, 0] - ]} -") + ```rescript + Array.map([1, 2, 3, 4, 5], ~f=Fun.constant(0)) == [0, 0, 0, 0, 0] + Array.initialize(6, ~f=Fun.constant(0)) == [0, 0, 0, 0, 0, 0] + ``` +*/ let constant: ('a, 'b) => 'a -@ocaml.doc(" A function which always returns its second argument. ") +/** A function which always returns its second argument. */ let sequence: ('a, 'b) => 'b -@ocaml.doc(" Reverses the argument order of a function. +/** Reverses the argument order of a function. - For any arguments [x] and [y], [flip(f)(x, y)] is the same as [f(y, x)]. + For any arguments `x` and `y`, `flip(f)(x, y)` is the same as `f(y, x)`. - Perhaps you want to [fold] something, but the arguments of a function you - already have access to are in the wrong order. -") + Perhaps you want to `fold` something, but the arguments of a function you + already have access to are in the wrong order. +*/ let flip: (('a, 'b) => 'c, 'b, 'a) => 'c -@ocaml.doc(" Negate a function. +/** Negate a function. - This can be useful in combination with {!List.filter} / {!Array.filter} or {!List.find} / {!Array.find}. + This can be useful in combination with [List.filter](List.mdx#filter) / [Array.filter](Array.mdx#filter) or [List.find](List.mdx#find) / [Array.find](Array.mdx#find). - {2 Examples} + ## Examples - {[ - let isLessThanTwelve = Fun.negate(n => n >= 12) - isLessThanTwelve(12) == false - ]} -") + ```rescript + let isLessThanTwelve = Fun.negate(n => n >= 12) + isLessThanTwelve(12) == false + ``` +*/ let negate: ('a => bool, 'a) => bool -@ocaml.doc(" Calls function [f] with an argument [x]. +/** Calls function `f` with an argument `x`. - [apply(f, x)] is exactly the same as [f(x)]. + `apply(f, x)` is exactly the same as `f(x)`. - Maybe you want to apply a function to a [switch] expression? That sort of thing. -") + Maybe you want to apply a function to a `switch` expression? That sort of thing. +*/ let apply: ('a => 'b, 'a) => 'b -@ocaml.doc(" Function composition, passing result from left to right. +/** Function composition, passing result from left to right. - This is usefull in cases when you want to make multiple transformations - during a [map] operation. + This is usefull in cases when you want to make multiple transformations + during a `map` operation. - {2 Examples} + ## Examples - {[ - let numbers = [1, 2, 3, 4, 5, 6, 7] + ```rescript + let numbers = [1, 2, 3, 4, 5, 6, 7] - let multiplied = Array.map(numbers, ~f=Fun.compose(Int.multiply(5), Int.toString)) + let multiplied = Array.map(numbers, ~f=Fun.compose(Int.multiply(5), Int.toString)) - multiplied == [\"5\", \"10\", \"15\", \"20\", \"25\", \"30\", \"35\"] - ]} -") + multiplied == ["5", "10", "15", "20", "25", "30", "35"] + ``` +*/ let compose: ('a, 'a => 'b, 'b => 'c) => 'c -@ocaml.doc(" Function composition, passing result from right to left. +/** Function composition, passing result from right to left. - Same as [!compose], but function application order is reversed. + Same as `!compose`, but function application order is reversed. - This is usefull in cases when you want to make multiple transformations - during a [map] operation. - - {2 Examples} + This is usefull in cases when you want to make multiple transformations + during a `map` operation. + + ## Examples - {[ - let numbers = [1, 2, 3, 4, 5, 6, 7] + ```rescript + let numbers = [1, 2, 3, 4, 5, 6, 7] - let a = (b) => b -> Fun.compose(Int.toString, Int.multiply(5)) + let a = (b) => b -> Fun.compose(Int.toString, Int.multiply(5)) - multiplied == [\"5\", \"10\", \"15\", \"20\", \"25\", \"30\", \"35\"] - ]} -") + multiplied == ["5", "10", "15", "20", "25", "30", "35"] + ``` +*/ let composeRight: ('a, 'b => 'c, 'a => 'b) => 'c -@ocaml.doc(" Useful for performing some side affect in {!Fun.pipe}-lined code. +/** Useful for performing some side affect in [Fun.pipe](Fun.mdx#pipe)-lined code. - Most commonly used to log a value in the middle of a pipeline of function calls. + Most commonly used to log a value in the middle of a pipeline of function calls. - {2 Examples} + ## Examples - {[ - let sanitize = (input: string): option => - input - ->String.trim - ->Fun.tap(~f=Js.log) - ->Int.fromString + ```rescript + let sanitize = (input: string): option => + input + ->String.trim + ->Fun.tap(~f=Js.log) + ->Int.fromString - Array.filter([1, 3, 2, 5, 4], ~f=Int.isEven) - ->Fun.tap(~f=numbers => numbers[0] = 0) - ->Fun.tap(~f=Array.reverse) == [4, 0] - ]} -") + Array.filter([1, 3, 2, 5, 4], ~f=Int.isEven) + ->Fun.tap(~f=numbers => numbers`0` = 0) + ->Fun.tap(~f=Array.reverse) == [4, 0] + ``` +*/ let tap: ('a, ~f: 'a => unit) => 'a -@ocaml.doc(" Runs the provided function, forever. +/** Runs the provided function, forever. - If an exception is thrown, returns the exception. -") + If an exception is thrown, returns the exception. +*/ let forever: (unit => unit) => exn -@ocaml.doc(" Runs a function repeatedly. +/** Runs a function repeatedly. - {2 Examples} + ## Examples - {[ - let count = ref(0) - Fun.times(10, ~f=() => count.contents = count.contents + 1) - count.contents == 10 - ]} -") + ```rescript + let count = ref(0) + Fun.times(10, ~f=() => count.contents = count.contents + 1) + count.contents == 10 + ``` +*/ let times: (int, ~f: unit => unit) => unit -@ocaml.doc(" Takes a function [f] which takes a single argument of a tuple [('a, 'b)] and returns a function which takes two arguments that can be partially applied. +/** Takes a function `f` which takes a single argument of a tuple `('a, 'b)` and returns a function which takes two arguments that can be partially applied. - {2 Examples} + ## Examples - {[ - let squareArea = ((width, height)) => width * height - let curriedArea: (int, int) => int = Fun.curry(squareArea) - let sizes = [3, 4, 5] - Array.map(sizes, ~f=curriedArea(4)) == [12, 16, 20] - ]} -") + ```rescript + let squareArea = ((width, height)) => width * height + let curriedArea: (int, int) => int = Fun.curry(squareArea) + let sizes = [3, 4, 5] + Array.map(sizes, ~f=curriedArea(4)) == [12, 16, 20] + ``` +*/ let curry: ((('a, 'b)) => 'c, 'a, 'b) => 'c -@ocaml.doc(" Takes a function which takes two arguments and returns a function which takes a single argument of a tuple. +/** Takes a function which takes two arguments and returns a function which takes a single argument of a tuple. - {2 Examples} + ## Examples - {[ - let sum = (a: int, b: int): int => a + b - let uncurriedSum: ((int, int)) => int = Fun.uncurry(sum) - uncurriedSum((3, 4)) == 7 - ]} -") + ```rescript + let sum = (a: int, b: int): int => a + b + let uncurriedSum: ((int, int)) => int = Fun.uncurry(sum) + uncurriedSum((3, 4)) == 7 + ``` +*/ let uncurry: (('a, 'b) => 'c, ('a, 'b)) => 'c -@ocaml.doc(" Like {!curry} but for a {!Tuple3}. ") +/** Like [curry](#curry) but for a [Tuple3](Tuple3.mdx#). */ let curry3: ((('a, 'b, 'c)) => 'd, 'a, 'b, 'c) => 'd -@ocaml.doc(" Like {!uncurry} but for a {!Tuple3}. ") +/** Like [uncurry](#uncurry) but for a [Tuple3](Tuple3.mdx#). */ let uncurry3: (('a, 'b, 'c) => 'd, ('a, 'b, 'c)) => 'd diff --git a/src/TableclothInt.resi b/src/TableclothInt.resi index 621d623..69013bb 100644 --- a/src/TableclothInt.resi +++ b/src/TableclothInt.resi @@ -1,331 +1,316 @@ -@@ocaml.text(" ") +/** An `int` is a whole number. -@@ocaml.text(" An [int] is a whole number. + Rescript's has a 32-bit [ signed ](https://en.wikipedia.org/wiki/Signed_number_representations) [ integer](https://en.wikipedia.org/wiki/Integer). + Largegest `int` value is 2^31 - 1 === [2_147_483_647], and smallest is -2^31 - 1 === [-2_147_483_647] - Rescript's has a 32-bit {{: https://en.wikipedia.org/wiki/Signed_number_representations } signed } {{: https://en.wikipedia.org/wiki/Integer } integer}. - Largegest [int] value is 2^31 - 1 === [2_147_483_647], and smallest is -2^31 - 1 === [-2_147_483_647] + `int`s are subject to [ overflow ](https://en.wikipedia.org/wiki/Integer_overflow), meaning that `Int.maximumValue + 1 == Int.minimumValue`. - [int]s are subject to {{: https://en.wikipedia.org/wiki/Integer_overflow } overflow }, meaning that [Int.maximumValue + 1 == Int.minimumValue]. + If you work with integers larger than [minimumValue](#minimumValue) and smaller than [maximumValue](#maximumValue) you can use the [Int](#Int) module. + If you need to work with larger numbers, concider using [Float](Float.mdx#) since they are signed 64-bit `float`s and limited by + `1.79E+308`, or 1.7976931348623157 * 10^308 at the upper end and `5E-324` at the lower. - If you work with integers larger than {!minimumValue} and smaller than {!maximumValue} you can use the {!Int} module. - If you need to work with larger numbers, concider using {!Float} since they are signed 64-bit [float]s and limited by - [1.79E+308], or 1.7976931348623157 * 10^308 at the upper end and [5E-324] at the lower. + Valid syntax for `int`s includes: + ```rescript + 0 + 42 + 9000 + 1_000_000 + 1_000_000 + 0xFF // 255 in hexadecimal + 0x000A // 10 in hexadecimal + ``` - Valid syntax for [int]s includes: - {[ - 0 - 42 - 9000 - 1_000_000 - 1_000_000 - 0xFF // 255 in hexadecimal - 0x000A // 10 in hexadecimal - ]} - - {e Historical Note: } The name [int] comes from the term {{: https://en.wikipedia.org/wiki/Integer } integer}. It appears - that the [int] abbreviation was introduced in the programming language ALGOL 68. - - Today, almost all programming languages use this abbreviation. -") + ~Historical Note:~ The name `int` comes from the term [ integer](https://en.wikipedia.org/wiki/Integer). It appears + that the `int` abbreviation was introduced in the programming language ALGOL 68. + Today, almost all programming languages use this abbreviation. +*/ type t = int -@@ocaml.text(" {1 Constants } ") - -@ocaml.doc(" The literal [0] as a named value. ") +/** The literal `0` as a named value. */ let zero: t -@ocaml.doc(" The literal [1] as a named value. ") +/** The literal `1` as a named value. */ let one: t -@ocaml.doc(" The maximum representable [int] on the current platform. ") +/** The maximum representable `int` on the current platform. */ let maximumValue: t -@ocaml.doc(" The minimum representable [int] on the current platform. ") +/** The minimum representable `int` on the current platform. */ let minimumValue: t -@@ocaml.text(" {1 Create} ") - -@ocaml.doc(" Attempt to parse a [string] into a [int]. - - {2 Examples} - - {[ - Int.fromString(\"0\") == Some(0) - Int.fromString(\"42\") == Some(42) - Int.fromString(\"-3\") == Some(-3) - Int.fromString(\"123_456\") == Some(123_456) - Int.fromString(\"0xFF\") == Some(255) - Int.fromString(\"0x00A\") == Some(10) - Int.fromString(\"Infinity\") == None - Int.fromString(\"NaN\") == None - ]} -") +/** Attempt to parse a `string` into a `int`. + + ## Examples + + ```rescript + Int.fromString("0") == Some(0) + Int.fromString("42") == Some(42) + Int.fromString("-3") == Some(-3) + Int.fromString("123_456") == Some(123_456) + Int.fromString("0xFF") == Some(255) + Int.fromString("0x00A") == Some(10) + Int.fromString("Infinity") == None + Int.fromString("NaN") == None + ``` +*/ let fromString: string => option -@@ocaml.text(" {1 Operators} ") - -@ocaml.doc(" Add two {!Int} numbers. +/** Add two [Int](Int.mdx#) numbers. - You {e cannot } add an [int] and a [float] directly though. + You *cannot* add an `int` and a `float` directly though. - See {!Float.add} for why, and how to overcome this limitation. + See [Float.add](Float.mdx#add) for why, and how to overcome this limitation. - {2 Examples} + ## Examples - {[ - Int.add(3002, 4004) == 7006 - ]} -") + ```rescript + Int.add(3002, 4004) == 7006 + ``` +*/ let add: (t, t) => t -@ocaml.doc(" Subtract numbers. - - {2 Examples} +/** Subtract numbers. + + ## Examples - {[ - Int.subtract(4, 3) == 1 - ]} -") + ```rescript + Int.subtract(4, 3) == 1 + ``` +*/ let subtract: (t, t) => t -@ocaml.doc(" Multiply [int]s. - - {2 Examples} +/** Multiply `int`s. + + ## Examples - {[ - Int.multiply(2, 7) == 14 - ]} -") + ```rescript + Int.multiply(2, 7) == 14 + ``` +*/ let multiply: (t, t) => t -@ocaml.doc(" Integer division. +/** Integer division. - Notice that the remainder is discarded. + Notice that the remainder is discarded. - {3 Exceptions} + ### Exceptions - Throws [Division_by_zero] when the divisor is [0]. + Throws [Division_by_zero] when the divisor is `0`. - {2 Examples} + ## Examples - {[ - Int.divide(3, ~by=2) == 1 - ]} -") + ```rescript + Int.divide(3, ~by=2) == 1 + ``` +*/ let divide: (t, ~by: t) => t -@ocaml.doc(" Floating point division +/** Floating point division - {2 Examples} + ## Examples - {[ - Int.divideFloat(3, ~by=2) == 1.5 - Int.divideFloat(27, ~by=5) == 5.25 - Int.divideFloat(8, ~by=4) == 2.0 - ]} -") + ```rescript + Int.divideFloat(3, ~by=2) == 1.5 + Int.divideFloat(27, ~by=5) == 5.25 + Int.divideFloat(8, ~by=4) == 2.0 + ``` +*/ let divideFloat: (t, ~by: t) => float -@ocaml.doc(" Exponentiation, takes the base first, then the exponent. +/** Exponentiation, takes the base first, then the exponent. - {2 Examples} + ## Examples - {[ - Int.power(~base=7, ~exponent=3) == 343 - ]} -") + ```rescript + Int.power(~base=7, ~exponent=3) == 343 + ``` +*/ let power: (~base: t, ~exponent: t) => t -@ocaml.doc(" Flips the 'sign' of an integer so that positive integers become negative and negative integers become positive. Zero stays as it is. +/** Flips the 'sign' of an integer so that positive integers become negative and negative integers become positive. Zero stays as it is. - {2 Examples} + ## Examples - {[ - Int.negate(8) == -8 - Int.negate(-7) == 7 - Int.negate(0) == 0 - ]} -") + ```rescript + Int.negate(8) == -8 + Int.negate(-7) == 7 + Int.negate(0) == 0 + ``` +*/ let negate: t => t -@ocaml.doc(" Get the {{: https://en.wikipedia.org/wiki/Absolute_value } absolute value } of a number. +/** Get the [ absolute value ](https://en.wikipedia.org/wiki/Absolute_value) of a number. - {2 Examples} + ## Examples - {[ - Int.absolute(8) == 8 - Int.absolute(-7) == 7 - Int.absolute(0) == 0 - ]} -") + ```rescript + Int.absolute(8) == 8 + Int.absolute(-7) == 7 + Int.absolute(0) == 0 + ``` +*/ let absolute: t => t -@ocaml.doc(" Perform {{: https://en.wikipedia.org/wiki/Modular_arithmetic } modular arithmetic }. +/** Perform [ modular arithmetic ](https://en.wikipedia.org/wiki/Modular_arithmetic). - {b Note:} {!modulo} is not [%] JS operator. If you want [%], use {!remainder} + *Note:* [modulo](#modulo) is not `%` JS operator. If you want `%`, use [remainder](#remainder) - If you intend to use [modulo] to detect even and odd numbers consider using {!Int.isEven} or {!Int.isOdd}. + If you intend to use `modulo` to detect even and odd numbers consider using [Int.isEven](Int.mdx#isEven) or [Int.isOdd](Int.mdx#isOdd). - The [modulo] function works in the typical mathematical way when you run into negative numbers + The `modulo` function works in the typical mathematical way when you run into negative numbers - Use {!Int.remainder} for a different treatment of negative numbers. + Use [Int.remainder](Int.mdx#remainder) for a different treatment of negative numbers. - {2 Examples} + ## Examples - {[ - Int.modulo(-4, ~by=3) == 2 - Int.modulo(-3, ~by=3) == 0 - Int.modulo(-2, ~by=3) = 1 - Int.modulo(-1, ~by=3) == 2 - Int.modulo(0, ~by=3) == 0 - Int.modulo(1, ~by=3) == 1 - Int.modulo(2, ~by=3) == 2 - Int.modulo(3, ~by=3) == 0 - Int.modulo(4, ~by=3) == 1 - ]} -") + ```rescript + Int.modulo(-4, ~by=3) == 2 + Int.modulo(-3, ~by=3) == 0 + Int.modulo(-2, ~by=3) = 1 + Int.modulo(-1, ~by=3) == 2 + Int.modulo(0, ~by=3) == 0 + Int.modulo(1, ~by=3) == 1 + Int.modulo(2, ~by=3) == 2 + Int.modulo(3, ~by=3) == 0 + Int.modulo(4, ~by=3) == 1 + ``` +*/ let modulo: (t, ~by: t) => t -@ocaml.doc(" Get the remainder after division. Works the same as [%] JS operator +/** Get the remainder after division. Works the same as `%` JS operator - Use {!Int.modulo} for a different treatment of negative numbers. + Use [Int.modulo](Int.mdx#modulo) for a different treatment of negative numbers. - The sign of the result is the same as the sign - of the dividend ([~by]) while with a {!modulo} the sign - of the result is the same as the divisor ([t]). + The sign of the result is the same as the sign + of the dividend (`~by`) while with a [modulo](#modulo) the sign + of the result is the same as the divisor (`t`). - {2 Examples} + ## Examples - {[ - Array.map([-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5], ~f=Int.remainder(~by=4)) == - [-1, 0, -3, -2, -1, 0, 1, 2, 3, 0, 1] - ]} -") + ```rescript + Array.map([-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5], ~f=Int.remainder(~by=4)) == + [-1, 0, -3, -2, -1, 0, 1, 2, 3, 0, 1] + ``` +*/ let remainder: (t, ~by: t) => t -@ocaml.doc(" Returns the larger of two [int]s. +/** Returns the larger of two `int`s. - {2 Examples} + ## Examples - {[ - Int.maximum(7, 9) == 9 - Int.maximum(-4, -1) == -1 - ]} -") + ```rescript + Int.maximum(7, 9) == 9 + Int.maximum(-4, -1) == -1 + ``` +*/ let maximum: (t, t) => t -@ocaml.doc(" Returns the smaller of two [int]s. +/** Returns the smaller of two `int`s. - {2 Examples} + ## Examples - {[ - Int.minimum(7, 9) == 7 - Int.minimum(-4, -1) == -4 - ]} -") + ```rescript + Int.minimum(7, 9) == 7 + Int.minimum(-4, -1) == -4 + ``` +*/ let minimum: (t, t) => t -@@ocaml.text(" {1 Query} ") - -@ocaml.doc(" Check if an [int] is even. +/** Check if an `int` is even. - {2 Examples} + ## Examples - {[ - Int.isEven(8) == true - Int.isEven(7) == false - Int.isEven(0) == true - ]} -") + ```rescript + Int.isEven(8) == true + Int.isEven(7) == false + Int.isEven(0) == true + ``` +*/ let isEven: t => bool -@ocaml.doc(" Check if an [int] is odd. +/** Check if an `int` is odd. - {2 Examples} + ## Examples - {[ - Int.isOdd(7) == true - Int.isOdd(8) == false - Int.isOdd(0) == false - ]} -") + ```rescript + Int.isOdd(7) == true + Int.isOdd(8) == false + Int.isOdd(0) == false + ``` +*/ let isOdd: t => bool -@ocaml.doc(" Clamps [n] within the inclusive [lower] and [upper] bounds. +/** Clamps `n` within the inclusive `lower` and `upper` bounds. - {3 Exceptions} + ### Exceptions - Throws an [Invalid_argument] exception if [lower > upper] + Throws an `Invalid_argument` exception if `lower > upper` - {2 Examples} + ## Examples - {[ - Int.clamp(5, ~lower=0, ~upper=8) == 5 - Int.clamp(9, ~lower=0, ~upper=8) == 8 - Int.clamp(5, ~lower=-10, ~upper=-5) == -5 - ]} -") + ```rescript + Int.clamp(5, ~lower=0, ~upper=8) == 5 + Int.clamp(9, ~lower=0, ~upper=8) == 8 + Int.clamp(5, ~lower=-10, ~upper=-5) == -5 + ``` +*/ let clamp: (t, ~lower: t, ~upper: t) => t -@ocaml.doc(" Checks if [n] is between [lower] and up to, but not including, [upper]. +/** Checks if `n` is between `lower` and up to, but not including, `upper`. - {3 Exceptions} + ### Exceptions - Throws an [Invalid_argument] exception if [lower > upper] + Throws an `Invalid_argument` exception if `lower > upper` - {2 Examples} + ## Examples - {[ - Int.inRange(3, ~lower=2, ~upper=4) == true - Int.inRange(4, ~lower=5, ~upper=8) == false - Int.inRange(-3, ~lower=-6, ~upper=-2) == true - ]} + ```rescript + Int.inRange(3, ~lower=2, ~upper=4) == true + Int.inRange(4, ~lower=5, ~upper=8) == false + Int.inRange(-3, ~lower=-6, ~upper=-2) == true + ``` -") +*/ let inRange: (t, ~lower: t, ~upper: t) => bool -@@ocaml.text(" {1 Convert} ") +/** Convert an `int` into a `float`. Useful when mixing [Int](Int.mdx#) and [Float](Float.mdx#) values like this: -@ocaml.doc(" Convert an [int] into a [float]. Useful when mixing {!Int} and {!Float} values like this: + ## Examples - {2 Examples} + ```rescript + let halfOf = (number: int): float => Int.toFloat(number) /. 2. - {[ - let halfOf = (number: int): float => Int.toFloat(number) /. 2. - - halfOf(7) == 3.5 - ]} -") + halfOf(7) == 3.5 + ``` +*/ let toFloat: t => float -@ocaml.doc(" Convert an [int] into a [string] representation. +/** Convert an `int` into a `string` representation. - Guarantees that + Guarantees that - {[ - n->Int.toString->Int.fromString == Some(n) - ]} + ```rescript + n->Int.toString->Int.fromString == Some(n) + ``` - {2 Examples} + ## Examples - {[ - Int.toString(3) == \"3\" - Int.toString(-3) == \"-3\" - Int.toString(0) == \"0\" - ]} -") + ```rescript + Int.toString(3) == "3" + Int.toString(-3) == "-3" + Int.toString(0) == "0" + ``` +*/ let toString: t => string -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two [int]s for equality. ") +/** Test two `int`s for equality. */ let equal: (t, t) => bool -@ocaml.doc(" Compare two [int]s. ") +/** Compare two `int`s. */ let compare: (t, t) => int -@ocaml.doc(" The unique identity for {!Comparator}.") +/** The unique identity for [Comparator](Comparator.mdx#). */ type identity let comparator: TableclothComparator.t diff --git a/src/TableclothList.resi b/src/TableclothList.resi index 325a23c..2de18a6 100644 --- a/src/TableclothList.resi +++ b/src/TableclothList.resi @@ -1,996 +1,970 @@ -@@ocaml.text(" ") - -@@ocaml.text(" Immutable singly-linked list of elements which must have the same type. - - Lists can have any number of elements. - - They are fast (O(1)) when: - - Getting the first element using {!head} - - Getting the {!tail} - - Creating a new list by adding an element to the front using {!cons} - - They also support exhaustive pattern matching: - - {[ - switch aList { - | list{} => \"Empty\" - | list{a} => \"Exactly one element\" - | list{(a, b)} => \"Exactly two elements\" - | list{a, b, ...cs} => \"More than two elements\" - } - ]} - - Lists are slow when: - - You need to access an element that isn't at the front of the list - - Counting how many elements are in the list - - As they have inefficent ([O(n)]) {!getAt} and {!length} operations. - - If those are important to your use-case, perhaps you need an {!Array}. -") - +/** Immutable singly-linked list of elements which must have the same type. + You can create a [list] with the [list{1, 2, 3}] syntax. + Lists can have any number of elements. + + They are fast `O(1)` when: + - Getting the first element using [head](#head) + - Getting the [tail](#tail) + - Creating a new list by adding an element to the front using [cons](#cons) + + They also support exhaustive pattern matching: + + ```rescript + switch aList { + | list{} => "Empty" + | list{a} => "Exactly one element" + | list{(a, b)} => "Exactly two elements" + | list{a, b, ...cs} => "More than two elements" + } + ``` + + Lists are slow when: + - You need to access an element that isn't at the front of the list + - Counting how many elements are in the list + + As they have inefficent (`O(n)`) [getAt](#getAt) and [length](#length) operations. + + If those are important to your use-case, perhaps you need an [Array](Array.mdx#). +*/ type t<'a> = list<'a> -@@ocaml.text(" {1 Create} - - You can create a [list] with the [list{1, 2, 3}] syntax. -") +/** An empty list. -@ocaml.doc(" An empty list. + ## Examples - {2 Examples} - - {[ - List.empty == list{} - List.empty->List.length == 0 - ]} -") + ```rescript + List.empty == list{} + List.empty->List.length == 0 + ``` +*/ let empty: t<'a> -@ocaml.doc(" Create a list with only one element. +/** Create a list with only one element. - {2 Examples} + ## Examples - {[ - List.singleton(1234) == list{1234} - List.singleton(\"hi\") == list{\"hi\"} - ]} -") + ```rescript + List.singleton(1234) == list{1234} + List.singleton("hi") == list{"hi"} + ``` +*/ let singleton: 'a => t<'a> -@ocaml.doc(" Creates a list of length [times] with the value [x] populated at each index. +/** Creates a list of length `times` with the value `x` populated at each index. - {2 Examples} + ## Examples - {[ - List.repeat('a', ~times=5) == list{'a', 'a', 'a', 'a', 'a'} - List.repeat(7, ~times=0) == list{} - List.repeat(\"Why?\", ~times=-1) == list{} - ]} -") + ```rescript + List.repeat('a', ~times=5) == list{'a', 'a', 'a', 'a', 'a'} + List.repeat(7, ~times=0) == list{} + List.repeat("Why?", ~times=-1) == list{} + ``` +*/ let repeat: ('a, ~times: int) => t<'a> -@ocaml.doc(" Creates a list containing all of the integers from [from] if it is provided or [0] if not, up to but not including [to] +/** Creates a list containing all of the integers from `from` if it is provided or `0` if not, up to but not including `to` - {2 Examples} + ## Examples - {[ - List.range(5) == list{0, 1, 2, 3, 4} - List.range(5, ~from=2) == list{2, 3, 4} - List.range(3, ~from=-2) == list{-2, -1, 0, 1, 2} - ]} -") + ```rescript + List.range(5) == list{0, 1, 2, 3, 4} + List.range(5, ~from=2) == list{2, 3, 4} + List.range(3, ~from=-2) == list{-2, -1, 0, 1, 2} + ``` +*/ let range: (~from: int=?, int) => t -@ocaml.doc(" Initialize a list. +/** Initialize a list. - [List.initialize(n, ~f)] creates a list of length [n] by setting the element at position [index] to be [f(index)]. + `List.initialize(n, ~f)` creates a list of length `n` by setting the element at position `index` to be `f(index)`. - {2 Examples} + ## Examples - {[ - List.initialize(4, ~f=identity) == list{0, 1, 2, 3} - List.initialize(4, ~f=index => index * index) == list{0, 1, 4, 9} - ]} -") + ```rescript + List.initialize(4, ~f=identity) == list{0, 1, 2, 3} + List.initialize(4, ~f=index => index * index) == list{0, 1, 4, 9} + ``` +*/ let initialize: (int, ~f: int => 'a) => t<'a> -@ocaml.doc(" Create a list from an {!Array}. +/** Create a list from an [Array](Array.mdx#). - {2 Examples} + ## Examples - {[ - List.fromArray([1, 2, 3]) == list{1, 2, 3} - ]} -") + ```rescript + List.fromArray([1, 2, 3]) == list{1, 2, 3} + ``` +*/ let fromArray: array<'a> => t<'a> -@@ocaml.text(" {1 Basic operations} ") - -@ocaml.doc(" Returns, as an {!Option}, the first element of a list. +/** Returns, as an [Option](Option.mdx#), the first element of a list. - If the list is empty, returns [None]. + If the list is empty, returns `None`. - {2 Examples} + ## Examples - {[ - List.head(list{1, 2, 3}) == Some(1) - List.head(list{}) == None - ]} -") + ```rescript + List.head(list{1, 2, 3}) == Some(1) + List.head(list{}) == None + ``` +*/ let head: t<'a> => option<'a> -@ocaml.doc(" Returns, as an {!Option}, a list without its first element. +/** Returns, as an [Option](Option.mdx#), a list without its first element. - If the list is empty, returns [None] + If the list is empty, returns `None` - {2 Examples} + ## Examples - {[ - List.tail(list{1, 2, 3}) == Some(list{2, 3}) - List.tail(list{1}) == Some(list{}) - List.tail(list{}) == None - ]} -") + ```rescript + List.tail(list{1, 2, 3}) == Some(list{2, 3}) + List.tail(list{1}) == Some(list{}) + List.tail(list{}) == None + ``` +*/ let tail: t<'a> => option> -@ocaml.doc(" Prepend a value to the front of a list. +/** Prepend a value to the front of a list. - The spread syntax [...] operator can also be used. + The spread syntax `...` operator can also be used. - {2 Examples} + ## Examples - {[ - List.cons(list{2, 3, 4}, 1) == list{1, 2, 3, 4} + ```rescript + List.cons(list{2, 3, 4}, 1) == list{1, 2, 3, 4} - let b = list{3, 4} + let b = list{3, 4} - list{1, 2, ...b} == list{1, 2, 3, 4} - ]} -") + list{1, 2, ...b} == list{1, 2, 3, 4} + ``` +*/ let cons: (t<'a>, 'a) => t<'a> -@ocaml.doc(" Attempt to take the first [count] elements of a list. +/** Attempt to take the first `count` elements of a list. - If the list has fewer than [count] elements, returns the entire list. + If the list has fewer than `count` elements, returns the entire list. - If count is zero or negative, returns [list{}]. + If count is zero or negative, returns `list{}`. - {2 Examples} + ## Examples - {[ - List.take(list{1, 2, 3}, ~count=2) == list{1, 2} - List.take(list{}, ~count=2) == list{} - List.take(list{1, 2, 3, 4}, ~count=8) == list{1, 2, 3, 4} - List.take(list{1, 2, 3, 4}, ~count=-1) == list{} - ]} -") + ```rescript + List.take(list{1, 2, 3}, ~count=2) == list{1, 2} + List.take(list{}, ~count=2) == list{} + List.take(list{1, 2, 3, 4}, ~count=8) == list{1, 2, 3, 4} + List.take(list{1, 2, 3, 4}, ~count=-1) == list{} + ``` +*/ let take: (t<'a>, ~count: int) => t<'a> -@ocaml.doc(" Take elements from a list until [f] returns [false]. +/** Take elements from a list until `f` returns `false`. - {2 Examples} + ## Examples - {[ - List.takeWhile(list{2, 4, 6, 7, 8, 9}, ~f=Int.isEven) == list{2, 4, 6} - List.takeWhile(list{2, 4, 6}, ~f=Int.isEven) == list{2, 4, 6} - List.takeWhile(list{1, 2, 3}, ~f=Int.isEven) == list{} - ]} -") + ```rescript + List.takeWhile(list{2, 4, 6, 7, 8, 9}, ~f=Int.isEven) == list{2, 4, 6} + List.takeWhile(list{2, 4, 6}, ~f=Int.isEven) == list{2, 4, 6} + List.takeWhile(list{1, 2, 3}, ~f=Int.isEven) == list{} + ``` +*/ let takeWhile: (t<'a>, ~f: 'a => bool) => t<'a> -@ocaml.doc(" Drop the first [count] elements from the front of a list. +/** Drop the first `count` elements from the front of a list. - If the list has fewer than [count] elements, returns []. + If the list has fewer than `count` elements, returns `list{}`. - If count is zero or negative, returns the entire list. + If count is zero or negative, returns the entire list. - {2 Examples} + ## Examples - {[ - List.drop(list{1, 2, 3, 4}, ~count=2) == list{3, 4} - List.drop(list{1, 2, 3, 4}, ~count=6) == list{} - List.drop(list{1, 2, 3, 4}, ~count=-1) == list{1, 2, 3, 4} - ]} -") + ```rescript + List.drop(list{1, 2, 3, 4}, ~count=2) == list{3, 4} + List.drop(list{1, 2, 3, 4}, ~count=6) == list{} + List.drop(list{1, 2, 3, 4}, ~count=-1) == list{1, 2, 3, 4} + ``` +*/ let drop: (t<'a>, ~count: int) => t<'a> -@ocaml.doc(" Drop elements from a list until [f] returns [false]. +/** Drop elements from a list until `f` returns `false`. - {2 Examples} + ## Examples - {[ - List.dropWhile(list{2, 4, 6, 7, 8, 9}, ~f=Int.isEven) == list{7, 8, 9} - List.dropWhile(list{2, 4, 6, 8}, ~f=Int.isEven) == list{} - List.dropWhile(list{1, 2, 3}, ~f=Int.isEven) == list{1, 2, 3} - ]} -") + ```rescript + List.dropWhile(list{2, 4, 6, 7, 8, 9}, ~f=Int.isEven) == list{7, 8, 9} + List.dropWhile(list{2, 4, 6, 8}, ~f=Int.isEven) == list{} + List.dropWhile(list{1, 2, 3}, ~f=Int.isEven) == list{1, 2, 3} + ``` +*/ let dropWhile: (t<'a>, ~f: 'a => bool) => t<'a> -@ocaml.doc(" As an {!Option} get of all of the elements of a list except the last one. +/** As an [Option](Option.mdx#) get of all of the elements of a list except the last one. - Returns [None] if the list is empty. + Returns `None` if the list is empty. - {2 Examples} + ## Examples - {[ - List.initial(list{1, 2, 3}) == Some(list{1, 2}) - List.initial(list{1}) == Some(list{}) - List.initial(list{}) = None - ]} -") + ```rescript + List.initial(list{1, 2, 3}) == Some(list{1, 2}) + List.initial(list{1}) == Some(list{}) + List.initial(list{}) = None + ``` +*/ let initial: t<'a> => option> -@ocaml.doc(" Get the last element of a list. +/** Get the last element of a list. - Returns [None] if the list is empty. + Returns `None` if the list is empty. - {b Warning} This will iterate through the entire list. + *Warning* This will iterate through the entire list. - {2 Examples} + ## Examples - {[ - List.last(list{1, 2, 3}) == Some(3) - List.last(list{1}) == Some(1) - List.last(list{}) == None - ]} -") + ```rescript + List.last(list{1, 2, 3}) == Some(3) + List.last(list{1}) == Some(1) + List.last(list{}) == None + ``` +*/ let last: t<'a> => option<'a> -@ocaml.doc(" Returns the element at position [index] in the list. +/** Returns the element at position `index` in the list. - Returns [None] if [index] is outside of the bounds of the list. + Returns `None` if `index` is outside of the bounds of the list. - {2 Examples} + ## Examples - {[ - List.getAt(list{1, 2, 3}, ~index=1) == Some(2) - List.getAt(list{}, ~index=2) == None - List.getAt(list{1, 2, 3}, ~index=100) == None - ]} -") + ```rescript + List.getAt(list{1, 2, 3}, ~index=1) == Some(2) + List.getAt(list{}, ~index=2) == None + List.getAt(list{1, 2, 3}, ~index=100) == None + ``` +*/ let getAt: (t<'a>, ~index: int) => option<'a> -@ocaml.doc(" Insert a new element at the specified index. +/** Insert a new element at the specified index. - The element previously occupying [index] will now be at [index + 1] + The element previously occupying `index` will now be at `index + 1` - If [index] is greater than then length of the list, it will be appended: + If `index` is greater than then length of the list, it will be appended: - {3 Exceptions} + ### Exceptions - Raises an [Invalid_argument] exception if [index] is negative. + Raises an `Invalid_argument` exception if `index` is negative. - {2 Examples} + ## Examples - {[ - list{100, 101, 102, 103}->List.insertAt(~index=2, ~value=999) == list{100, 101, 999, 102, 103} - list{100, 101, 102, 103}->List.insertAt(~index=0, ~value=999) == list{999, 100, 101, 102, 103} - list{100, 101, 102, 103}->List.insertAt(~index=4, ~value=999) == list{100, 101, 102, 103, 999} - list{100, 101, 102, 103}->List.insertAt(~index=-1, ~value=999) == list{999, 100, 101, 102, 103} - list{100, 101, 102, 103}->List.insertAt(~index=5, ~value=999) == list{ 100, 101, 102, 103, 999 } - ]} -") + ```rescript + list{100, 101, 102, 103}->List.insertAt(~index=2, ~value=999) == list{100, 101, 999, 102, 103} + list{100, 101, 102, 103}->List.insertAt(~index=0, ~value=999) == list{999, 100, 101, 102, 103} + list{100, 101, 102, 103}->List.insertAt(~index=4, ~value=999) == list{100, 101, 102, 103, 999} + list{100, 101, 102, 103}->List.insertAt(~index=-1, ~value=999) == list{999, 100, 101, 102, 103} + list{100, 101, 102, 103}->List.insertAt(~index=5, ~value=999) == list{ 100, 101, 102, 103, 999 } + ``` +*/ let insertAt: (t<'a>, ~index: int, ~value: 'a) => t<'a> -@ocaml.doc(" Returns a new list with the value at [index] updated to be the result of applying [f]. +/** Returns a new list with the value at `index` updated to be the result of applying `f`. - If [index] is outside of the bounds of the list, returns the list as-is. + If `index` is outside of the bounds of the list, returns the list as-is. - {2 Examples} + ## Examples - {[ - List.updateAt(list{1, 2, 3}, ~index=1, ~f=Int.add(3)) == list{1, 5, 3} + ```rescript + List.updateAt(list{1, 2, 3}, ~index=1, ~f=Int.add(3)) == list{1, 5, 3} - let animals = list{\"Ant\", \"Bat\", \"Cat\"} - animals == List.updateAt(animals, ~index=4, ~f=String.reverse) - ]} -") + let animals = list{"Ant", "Bat", "Cat"} + animals == List.updateAt(animals, ~index=4, ~f=String.reverse) + ``` +*/ let updateAt: (t<'a>, ~index: int, ~f: 'a => 'a) => t<'a> -@ocaml.doc(" Creates a new list without the element at [index]. +/** Creates a new list without the element at `index`. - If [index] is outside of the bounds of the list, returns the list as-is. + If `index` is outside of the bounds of the list, returns the list as-is. - {2 Examples} + ## Examples - {[ - List.removeAt(list{1, 2, 3}, ~index=2) == list{1, 2} + ```rescript + List.removeAt(list{1, 2, 3}, ~index=2) == list{1, 2} - let animals = list{\"Ant\", \"Bat\", \"Cat\"} - List.equal(String.equal, animals, List.removeAt(animals, ~index=4)) == true - ]} -") + let animals = list{"Ant", "Bat", "Cat"} + List.equal(String.equal, animals, List.removeAt(animals, ~index=4)) == true + ``` +*/ let removeAt: (t<'a>, ~index: int) => t<'a> -@ocaml.doc(" Reverse the elements in a list. +/** Reverse the elements in a list. - {2 Examples} + ## Examples - {[ - list{1, 2, 3}->List.reverse == list{3, 2, 1} - ]} - ") + ```rescript + list{1, 2, 3}->List.reverse == list{3, 2, 1} + ``` + */ let reverse: t<'a> => t<'a> -@ocaml.doc(" Sort using the provided [compare] function. +/** Sort using the provided `compare` function. - {2 Examples} + ## Examples - {[ - List.sort(list{5, 6, 8, 3, 6}, ~compare=Int.compare) == list{3, 5, 6, 6, 8} - ]} -") + ```rescript + List.sort(list{5, 6, 8, 3, 6}, ~compare=Int.compare) == list{3, 5, 6, 6, 8} + ``` +*/ let sort: (t<'a>, ~compare: ('a, 'a) => int) => t<'a> -@ocaml.doc(" - [List.sortBy(xs, ~f=fcn)] returns a new list sorted according to the values - returned by [fcn]. This is a stable sort: if two items have the same value, - they will appear in the same order that they appeared in the original list. - {[ - List.sortBy(list{3, 2, 5, -2, 4}, ~f=x => x * x) == list{2, -2, 3, 4, 5} - ]} -") +/** + `List.sortBy(xs, ~f=fcn)` returns a new list sorted according to the values + returned by `fcn`. This is a stable sort: if two items have the same value, + they will appear in the same order that they appeared in the original list. + ```rescript + List.sortBy(list{3, 2, 5, -2, 4}, ~f=x => x * x) == list{2, -2, 3, 4, 5} + ``` +*/ let sortBy: (t<'a>, ~f: 'a => 'b) => t<'a> -@@ocaml.text(" {1 Query} ") - -@ocaml.doc(" Determine if a list is empty. +/** Determine if a list is empty. - {2 Examples} + ## Examples - {[ - List.empty->List.isEmpty == true - list{}->List.isEmpty == true - list{1, 2, 3}->List.isEmpty == false - ]} -") + ```rescript + List.empty->List.isEmpty == true + list{}->List.isEmpty == true + list{1, 2, 3}->List.isEmpty == false + ``` +*/ let isEmpty: t<_> => bool -@ocaml.doc(" Return the number of elements in a list. +/** Return the number of elements in a list. - {b Warning} [List.length] needs to access the {b entire} list in order to calculate its result. + *Warning* `List.length` needs to access the *entire* list in order to calculate its result. - If you need fast access to the length, perhaps you need an {!Array}. + If you need fast access to the length, perhaps you need an [Array](Array.mdx#). - A common mistake is to have something like the following: + A common mistake is to have something like the following: - {[ - if List.length(someList) == 0 { - () // It will take longer than you think to reach here - } else { - () // But it doesn't need to - } - ]} + ```rescript + if List.length(someList) == 0 { + () // It will take longer than you think to reach here + } else { + () // But it doesn't need to + } + ``` - instead you should do + instead you should do - {[ - if List.isEmpty(someList) { - () // This happens instantly - } else { - () // Since List.isEmpty takes the same amount of time for all lists - } - ]} + ```rescript + if List.isEmpty(someList) { + () // This happens instantly + } else { + () // Since List.isEmpty takes the same amount of time for all lists + } + ``` - Or + Or - {[ - switch someList { - | list{} => () // Spoilers - | _ => () // This is how isEmpty is implemented - } - ]} + ```rescript + switch someList { + | list{} => () // Spoilers + | _ => () // This is how isEmpty is implemented + } + ``` - {2 Examples} + ## Examples - {[ - List.length(list{}) == 0 - list{7, 8, 9}->List.length == 3 - ]} -") + ```rescript + List.length(list{}) == 0 + list{7, 8, 9}->List.length == 3 + ``` +*/ let length: t<'a> => int -@ocaml.doc(" Determine if [f] returns true for [any] values in a list. +/** Determine if `f` returns true for `any` values in a list. - Stops iteration as soon as [f] returns true. + Stops iteration as soon as `f` returns true. - {2 Examples} + ## Examples - {[ - List.any(list{2, 3}, ~f=Int.isEven) == true - List.any(list{1, 3}, ~f=Int.isEven) == false - List.any(list{}, ~f=Int.isEven) == false - ]} -") + ```rescript + List.any(list{2, 3}, ~f=Int.isEven) == true + List.any(list{1, 3}, ~f=Int.isEven) == false + List.any(list{}, ~f=Int.isEven) == false + ``` +*/ let any: (t<'a>, ~f: 'a => bool) => bool -@ocaml.doc(" Determine if [f] returns true for [all] values in a list. +/** Determine if `f` returns true for `all` values in a list. - Stops iteration as soon as [f] returns false. + Stops iteration as soon as `f` returns false. - {2 Examples} + ## Examples - {[ - List.all(list{2, 4}, ~f=Int.isEven) == true - List.all(list{2, 3}, ~f=Int.isEven) == false - List.all(list{}, ~f=Int.isEven) == true - ]} -") + ```rescript + List.all(list{2, 4}, ~f=Int.isEven) == true + List.all(list{2, 3}, ~f=Int.isEven) == false + List.all(list{}, ~f=Int.isEven) == true + ``` +*/ let all: (t<'a>, ~f: 'a => bool) => bool -@ocaml.doc(" Count the number of elements where function [f] returns [true]. +/** Count the number of elements where function `f` returns `true`. - {2 Examples} + ## Examples - {[ - List.count(list{7, 5, 8, 6}, ~f=Int.isEven) == 2 - ]} - ") + ```rescript + List.count(list{7, 5, 8, 6}, ~f=Int.isEven) == 2 + ``` + */ let count: (t<'a>, ~f: 'a => bool) => int -@ocaml.doc(" - [List.uniqueBy(xs, ~f=fcn)] returns a new list containing only those elements from [xs] - that have a unique value when [fcn] is applied to them. +/** + `List.uniqueBy(xs, ~f=fcn)` returns a new list containing only those elements from `xs` + that have a unique value when `fcn` is applied to them. - The function [fcn] takes as its single parameter an item from the list - and returns a [string]. If the function generates the same string for two or more + The function `fcn` takes as its single parameter an item from the list + and returns a `string`. If the function generates the same string for two or more list items, only the first of them is retained. - {2 Examples} + ## Examples - {[ - List.uniqueBy(list{1, 3, 4, 3, 7, 7, 6}, ~f=Int.toString) == list{1, 3, 4, 7, 6} - let absStr = x => Int.absolute(x)->Int.toString - List.uniqueBy(list{1, 3, 4, -3, -7, 7, 6}, ~f=absStr) == list{1, 3, 4, -7, 6} - ]} - ") + ```rescript + List.uniqueBy(list{1, 3, 4, 3, 7, 7, 6}, ~f=Int.toString) == list{1, 3, 4, 7, 6} + let absStr = x => Int.absolute(x)->Int.toString + List.uniqueBy(list{1, 3, 4, -3, -7, 7, 6}, ~f=absStr) == list{1, 3, 4, -7, 6} + ``` + */ let uniqueBy: (list<'a>, ~f: 'a => string) => list<'a> -@ocaml.doc(" Returns, as an [option], the first element for which [f] evaluates to true. +/** Returns, as an `option`, the first element for which `f` evaluates to true. - If [f] doesn't return [true] for any of the elements [find] will return [None]. + If `f` doesn't return `true` for any of the elements `find` will return `None`. - {2 Examples} + ## Examples - {[ - List.find(list{1, 3, 4, 8}, ~f=Int.isEven) == Some(4) - List.find(list{0, 2, 4, 8}, ~f=Int.isOdd) == None - List.find(list{}, ~f=Int.isEven) == None - ]} -") + ```rescript + List.find(list{1, 3, 4, 8}, ~f=Int.isEven) == Some(4) + List.find(list{0, 2, 4, 8}, ~f=Int.isOdd) == None + List.find(list{}, ~f=Int.isEven) == None + ``` +*/ let find: (t<'a>, ~f: 'a => bool) => option<'a> -@ocaml.doc(" Returns, as an option, a tuple of the first element and its index for which [f] evaluates to true. +/** Returns, as an option, a tuple of the first element and its index for which `f` evaluates to true. - If [f] doesnt return [true] for any [(index, element)] pair, returns [None]. + If `f` doesnt return `true` for any `(index, element)` pair, returns `None`. - {2 Examples} + ## Examples - {[ - List.findIndex( - list{1, 3, 4, 8}, - ~f=(index, number) => index > 2 && Int.isEven(number) - ) == Some(3, 8) - ]} -") + ```rescript + List.findIndex( + list{1, 3, 4, 8}, + ~f=(index, number) => index > 2 && Int.isEven(number) + ) == Some(3, 8) + ``` +*/ let findIndex: (t<'a>, ~f: (int, 'a) => bool) => option<(int, 'a)> -@ocaml.doc(" Test if a list contains the specified element using the provided [equal] to test for equality. +/** Test if a list contains the specified element using the provided `equal` to test for equality. - This function may iterate the entire list, so if your code needs to - repeatedly perform this check, maybe you want a {!Set} instead. + This function may iterate the entire list, so if your code needs to + repeatedly perform this check, maybe you want a [Set](Set.mdx#) instead. - {2 Examples} + ## Examples - {[ - List.includes(list{1, 3, 5, 7}, 3, ~equal=Int.equal) == true - List.includes(list{1, 3, 5, 7}, 4, ~equal=Int.equal) == false - List.includes(list{}, 5, ~equal=Int.equal) == false - ]} -") + ```rescript + List.includes(list{1, 3, 5, 7}, 3, ~equal=Int.equal) == true + List.includes(list{1, 3, 5, 7}, 4, ~equal=Int.equal) == false + List.includes(list{}, 5, ~equal=Int.equal) == false + ``` +*/ let includes: (t<'a>, 'a, ~equal: ('a, 'a) => bool) => bool -@ocaml.doc(" - [List.minimumBy(xs, ~f=fcn)], when given a non-empty list, returns the item in the list - for which [fcn item] is a minimum. It is returned as [Some(item)]. +/** + `List.minimumBy(xs, ~f=fcn)`, when given a non-empty list, returns the item in the list + for which `fcn item` is a minimum. It is returned as `Some(item)`. - If given an empty list, [List.minimumBy] returns [None]. If more than one value has - a minimum value for [fcn item], the first one is returned. + If given an empty list, `List.minimumBy` returns `None`. If more than one value has + a minimum value for `fcn(item)`, the first one is returned. - The function provided takes a list item as its parameter and must return a value - that can be compared: for example, a [string] or [int]. + The function provided takes a list item as its parameter and must return a value + that can be compared: for example, a `string` or `int`. - {2 Examples} + ## Examples - {[ - let mod12 = x => mod(x, 12) - let hours = list{7, 9, 15, 10, 3, 22} - List.minimumBy(hours, ~f=mod12) == Some(15) - list{}->List.minimumBy(~f=mod12) == None - ]} -") + ```rescript + let mod12 = x => mod(x, 12) + let hours = list{7, 9, 15, 10, 3, 22} + List.minimumBy(hours, ~f=mod12) == Some(15) + list{}->List.minimumBy(~f=mod12) == None + ``` +*/ let minimumBy: (~f: 'a => 'comparable, list<'a>) => option<'a> -@ocaml.doc(" - [List.maximumBy ~f:fcn xs], when given a non-empty list, returns the item in the list - for which [fcn item] is a maximum. It is returned as [Some item]. +/** + `List.maximumBy(~f:fcn, xs)`, when given a non-empty list, returns the item in the list + for which `fcn(item)` is a maximum. It is returned as `Some(item)`. - If given an empty list, [List.maximumBy] returns [None]. If more than one value - has a maximum value for [fcn item], the first one is returned. + If given an empty list, `List.maximumBy` returns `None`. If more than one value + has a maximum value for `fcn(item)`, the first one is returned. - The function provided takes a list item as its parameter and must return a value - that can be compared: for example, a [string] or [int]. + The function provided takes a list item as its parameter and must return a value + that can be compared: for example, a `string` or `int`. - {2 Examples} + ## Examples - {[ - let mod12 = x => mod(x, 12) - let hours = list{7, 9, 15, 10, 3, 22} - List.maximumBy(hours, ~f=mod12) == Some(10) - list{}->List.maximumBy(~f=mod12) == None - ]} -") + ```rescript + let mod12 = x => mod(x, 12) + let hours = list{7, 9, 15, 10, 3, 22} + List.maximumBy(hours, ~f=mod12) == Some(10) + list{}->List.maximumBy(~f=mod12) == None + ``` +*/ let maximumBy: (~f: 'a => 'comparable, list<'a>) => option<'a> -@ocaml.doc(" Find the smallest element using the provided [compare] function. +/** Find the smallest element using the provided `compare` function. - Returns [None] if called on an empty list. + Returns `None` if called on an empty list. - {2 Examples} + ## Examples - {[ - List.minimum(list{7, 5, 8, 6}, ~compare=Int.compare) == Some(5) - ]} -") + ```rescript + List.minimum(list{7, 5, 8, 6}, ~compare=Int.compare) == Some(5) + ``` +*/ let minimum: (t<'a>, ~compare: ('a, 'a) => int) => option<'a> -@ocaml.doc(" Find the largest element using the provided [compare] function. +/** Find the largest element using the provided `compare` function. - Returns [None] if called on an empty list. + Returns `None` if called on an empty list. - {2 Examples} + ## Examples - {[ - List.maximum(list{7, 5, 8, 6}, ~compare) == Some(8) - ]} -") + ```rescript + List.maximum(list{7, 5, 8, 6}, ~compare) == Some(8) + ``` +*/ let maximum: (t<'a>, ~compare: ('a, 'a) => int) => option<'a> -@ocaml.doc(" Find a {!Tuple2} of the [(minimum, maximum)] elements using the provided [compare] function. +/** Find a [Tuple2](Tuple2.mdx#) of the `(minimum, maximum)` elements using the provided `compare` function. - Returns [None] if called on an empty list. + Returns `None` if called on an empty list. - {2 Examples} + ## Examples - {[ - List.extent(list{7, 5, 8, 6}, ~compare) == Some(5, 8) - ]} -") + ```rescript + List.extent(list{7, 5, 8, 6}, ~compare) == Some(5, 8) + ``` +*/ let extent: (t<'a>, ~compare: ('a, 'a) => int) => option<('a, 'a)> -@ocaml.doc(" Calculate the sum of a list using the provided modules [zero] value and [add] function. - - {2 Examples} - - {[ - List.sum(list{1, 2, 3}, module(Int)) == 6 - List.sum(list{4.0, 4.5, 5.0}, module(Float)) == 13.5 - - List.sum( - list{\"a\", \"b\", \"c\"}, - module( - { - type t = string - let zero = \"\" - let add = (a, b) => a ++ b - } - ), - ) == \"abc\" - ]} -") +/** Calculate the sum of a list using the provided modules `zero` value and `add` function. + + ## Examples + + ```rescript + List.sum(list{1, 2, 3}, module(Int)) == 6 + List.sum(list{4.0, 4.5, 5.0}, module(Float)) == 13.5 + + List.sum( + list{"a", "b", "c"}, + module( + { + type t = string + let zero = "" + let add = (a, b) => a ++ b + } + ), + ) == "abc" + ``` +*/ let sum: (t<'a>, module(TableclothContainer.Sum with type t = 'a)) => 'a -@@ocaml.text(" {1 Transform} ") +/** Create a new list which is the result of applying a function `f` to every element. -@ocaml.doc(" Create a new list which is the result of applying a function [f] to every element. + ## Examples - {2 Examples} - - {[ - List.map(list{1.0, 4.0, 9.0}, ~f=Float.squareRoot) == list{1.0, 2.0, 3.0} - ]} -") + ```rescript + List.map(list{1.0, 4.0, 9.0}, ~f=Float.squareRoot) == list{1.0, 2.0, 3.0} + ``` +*/ let map: (t<'a>, ~f: 'a => 'b) => t<'b> -@ocaml.doc(" Apply a function [f] to every element and its index. +/** Apply a function `f` to every element and its index. - {2 Examples} + ## Examples - {[ - List.mapWithIndex(list{\"zero\", \"one\", \"two\"}, ~f=(index, element) => - Int.toString(index) ++ \": \" ++ element - ) == list{\"0: zero\", \"1: one\", \"2: two\"} - ]} -") + ```rescript + List.mapWithIndex(list{"zero", "one", "two"}, ~f=(index, element) => + Int.toString(index) ++ ": " ++ element + ) == list{"0: zero", "1: one", "2: two"} + ``` +*/ let mapWithIndex: (t<'a>, ~f: (int, 'a) => 'b) => t<'b> -@ocaml.doc(" Keep elements that [f] returns [true] for. +/** Keep elements that `f` returns `true` for. - {2 Examples} + ## Examples - {[ - List.filter(list{1, 2, 3, 4, 5, 6}, ~f=Int.isEven) == list{2, 4, 6} - ]} -") + ```rescript + List.filter(list{1, 2, 3, 4, 5, 6}, ~f=Int.isEven) == list{2, 4, 6} + ``` +*/ let filter: (t<'a>, ~f: 'a => bool) => t<'a> -@ocaml.doc(" Like {!filter} but [f] is also called with each elements index. ") +/** Like [filter](#filter) but `f` is also called with each elements index. */ let filterWithIndex: (t<'a>, ~f: (int, 'a) => bool) => t<'a> -@ocaml.doc(" Allows you to combine {!map} and {!filter} into a single pass. +/** Allows you to combine [map](#map) and [filter](#filter) into a single pass. - The output list only contains elements for which [f] returns [Some]. + The output list only contains elements for which `f` returns `Some`. - Why [filterMap] and not just {!filter} then {!map}? + Why `filterMap` and not just [filter](#filter) then [map](#map)? - {!filterMap} removes the {!Option} layer automatically. - If your mapping is already returning an {!Option} and you want to skip over [None]s, then [filterMap] is much nicer to use. + [filterMap](#filterMap) removes the [Option](Option.mdx#) layer automatically. + If your mapping is already returning an [Option](Option.mdx#) and you want to skip over `None`s, then `filterMap` is much nicer to use. - {2 Examples} + ## Examples - {[ - let characters = list{'a', '9', '6', ' ', '2', 'z'} - List.filterMap(characters, ~f=Char.toDigit) == list{9, 6, 2} + ```rescript + let characters = list{'a', '9', '6', ' ', '2', 'z'} + List.filterMap(characters, ~f=Char.toDigit) == list{9, 6, 2} - List.filterMap(list{3, 4, 5, 6}, - ~f=number => Int.isEven(number) ? Some(number * number) : None - ) == list{16, 36} - ]} -") + List.filterMap(list{3, 4, 5, 6}, + ~f=number => Int.isEven(number) ? Some(number * number) : None + ) == list{16, 36} + ``` +*/ let filterMap: (t<'a>, ~f: 'a => option<'b>) => t<'b> -@ocaml.doc(" Apply a function [f] onto a list and {!flatten} the resulting list of lists. +/** Apply a function `f` onto a list and [flatten](#flatten) the resulting list of lists. - {2 Examples} + ## Examples - {[ - List.flatMap(xs, ~f) == List.map(xs, ~f)->List.flatten - list{1, 2, 3}->List.flatMap(~f=n => list{n, n}) == list{1, 1, 2, 2, 3, 3} - ]} -") + ```rescript + List.flatMap(xs, ~f) == List.map(xs, ~f)->List.flatten + list{1, 2, 3}->List.flatMap(~f=n => list{n, n}) == list{1, 1, 2, 2, 3, 3} + ``` +*/ let flatMap: (t<'a>, ~f: 'a => t<'b>) => t<'b> -@ocaml.doc(" Transform a list into a value. +/** Transform a list into a value. - After applying [f] to every element of the list, [fold] returns the accumulator. + After applying `f` to every element of the list, `fold` returns the accumulator. - [fold] iterates over the elements of the list from first to last. + `fold` iterates over the elements of the list from first to last. - For examples if we have: + For examples if we have: - {[ - let numbers = list{1, 2, 3} - let sum = List.fold(numbers, ~initial=0, ~f=(accumulator, element) => accumulator + element) + ```rescript + let numbers = list{1, 2, 3} + let sum = List.fold(numbers, ~initial=0, ~f=(accumulator, element) => accumulator + element) - sum == 6 - ]} + sum == 6 + ``` - Walking though each iteration step by step: + Walking though each iteration step by step: - + [accumulator: 0, element: 1, result: 1] - + [accumulator: 1, element: 2, result: 3] - + [accumulator: 3, element: 3, result: 6] + + [accumulator: 0, element: 1, result: 1] + + [accumulator: 1, element: 2, result: 3] + + [accumulator: 3, element: 3, result: 6] - And so the final result is [6]. (Note that in this case you probably want to use {!List.sum}) + And so the final result is `6`. (Note that in this case you probably want to use [List.sum](List.mdx#sum)) - {b Examples continued} + *Examples continued* - {[ - List.fold(list{1, 2, 3}, ~initial=list{}, ~f=List.cons) == list{3, 2, 1} + ```rescript + List.fold(list{1, 2, 3}, ~initial=list{}, ~f=List.cons) == list{3, 2, 1} - let unique = integers => List.fold(integers, ~initial=Set.Int.empty, ~f=Set.add)->Set.toList + let unique = integers => List.fold(integers, ~initial=Set.Int.empty, ~f=Set.add)->Set.toList - unique(list{1, 1, 2, 3, 2}) == list{1, 2, 3} + unique(list{1, 1, 2, 3, 2}) == list{1, 2, 3} - let lastEven = integers => - List.fold(integers, ~initial=None, ~f=(last, int) => Int.isEven(int) ? Some(int) : last) + let lastEven = integers => + List.fold(integers, ~initial=None, ~f=(last, int) => Int.isEven(int) ? Some(int) : last) - lastEven(list{1, 2, 3, 4, 5}) == Some(4) - ]} -") + lastEven(list{1, 2, 3, 4, 5}) == Some(4) + ``` +*/ let fold: (t<'a>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b -@ocaml.doc( - " This method is like {!fold} except that it iterates over the elements of the list from last to first. " -) +/** This method is like [fold](#fold) except that it iterates over the elements of the list from last to first. */ let foldRight: (t<'a>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b -@@ocaml.text(" {1 Combine} ") - -@ocaml.doc(" Creates a new list which is the result of appending the second list onto the end of the first. +/** Creates a new list which is the result of appending the second list onto the end of the first. - {2 Examples} + ## Examples - {[ - let fourtyTwos = List.repeat(~times=2, 42) - let eightyOnes = List.repeat(~times=3, 81) - List.append(fourtyTwos, eightyOnes) == list{42, 42, 81, 81, 81} - ]} -") + ```rescript + let fourtyTwos = List.repeat(~times=2, 42) + let eightyOnes = List.repeat(~times=3, 81) + List.append(fourtyTwos, eightyOnes) == list{42, 42, 81, 81, 81} + ``` +*/ let append: (t<'a>, t<'a>) => t<'a> -@ocaml.doc(" Concatenate a list of lists into a single list. +/** Concatenate a list of lists into a single list. - {2 Examples} + ## Examples - {[ - List.flatten(list{list{1, 2}, list{3}, list{4, 5}}) == list{1, 2, 3, 4, 5} - ]} -") + ```rescript + List.flatten(list{list{1, 2}, list{3}, list{4, 5}}) == list{1, 2, 3, 4, 5} + ``` +*/ let flatten: t> => t<'a> -@ocaml.doc(" Combine two lists by merging each pair of elements into a {!Tuple2}. +/** Combine two lists by merging each pair of elements into a [Tuple2](Tuple2.mdx#). - If one list is longer, the extra elements are dropped. + If one list is longer, the extra elements are dropped. - The same as [List.map2(~f=Tuple2.make)]. + The same as `List.map2(~f=Tuple2.make)`. - {2 Examples} + ## Examples - {[ - List.zip(list{1, 2, 3, 4, 5}, list{\"Dog\", \"Eagle\", \"Ferret\"}) - == list{(1, \"Dog\"), (2, \"Eagle\"), (3, \"Ferret\")} - ]} -") + ```rescript + List.zip(list{1, 2, 3, 4, 5}, list{"Dog", "Eagle", "Ferret"}) + == list{(1, "Dog"), (2, "Eagle"), (3, "Ferret")} + ``` +*/ let zip: (t<'a>, t<'b>) => t<('a, 'b)> -@ocaml.doc(" Combine two lists, using [f] to combine each pair of elements. +/** Combine two lists, using `f` to combine each pair of elements. - If one list is longer, the extra elements are dropped. + If one list is longer, the extra elements are dropped. - {2 Examples} + ## Examples - {[ - List.map2(list{1, 2, 3}, list{4, 5, 6}, ~f=Int.add) == list{5, 7, 9} + ```rescript + List.map2(list{1, 2, 3}, list{4, 5, 6}, ~f=Int.add) == list{5, 7, 9} - List.map2( - list{\"alice\", \"bob\", \"chuck\"}, list{3, 5, 7, 9, 11, 13, 15, 17, 19}, - ~f=Tuple2.make - ) == list{(\"alice\", 3), (\"bob\", 5), (\"chuck\", 7)} - ]} -") + List.map2( + list{"alice", "bob", "chuck"}, list{3, 5, 7, 9, 11, 13, 15, 17, 19}, + ~f=Tuple2.make + ) == list{("alice", 3), ("bob", 5), ("chuck", 7)} + ``` +*/ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> -@ocaml.doc(" Combine three lists, using [f] to combine each trio of elements. +/** Combine three lists, using `f` to combine each trio of elements. - If one list is longer, the extra elements are dropped. + If one list is longer, the extra elements are dropped. - {2 Examples} + ## Examples - {[ - List.map3( - ~f=Tuple3.make, - list{\"alice\", \"bob\", \"chuck\"}, - list{2, 5, 7, 8}, - list{true, false, true, false}, - ) == list{(\"alice\", 2, true), (\"bob\", 5, false), (\"chuck\", 7, true)} - ]} -") + ```rescript + List.map3( + ~f=Tuple3.make, + list{"alice", "bob", "chuck"}, + list{2, 5, 7, 8}, + list{true, false, true, false}, + ) == list{("alice", 2, true), ("bob", 5, false), ("chuck", 7, true)} + ``` +*/ let map3: (t<'a>, t<'b>, t<'c>, ~f: ('a, 'b, 'c) => 'd) => t<'d> -@@ocaml.text(" {1 Deconstruct} ") +/** Split a list into a [Tuple2](Tuple2.mdx#) of lists. Values which `f` returns true for will end up in [Tuple2.first](Tuple2.mdx#first). -@ocaml.doc(" Split a list into a {!Tuple2} of lists. Values which [f] returns true for will end up in {!Tuple2.first}. + ## Examples - {2 Examples} - - {[ - List.partition(list{1, 2, 3, 4, 5, 6}, ~f=Int.isOdd) == (list{1, 3, 5}, list{2, 4, 6}) - ]} -") + ```rescript + List.partition(list{1, 2, 3, 4, 5, 6}, ~f=Int.isOdd) == (list{1, 3, 5}, list{2, 4, 6}) + ``` +*/ let partition: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) -@ocaml.doc(" Divides a list into a {!Tuple2} of lists. +/** Divides a list into a [Tuple2](Tuple2.mdx#) of lists. - Elements which have index upto (but not including) [index] will be in the first component of the tuple. + Elements which have index upto (but not including) `index` will be in the first component of the tuple. - Elements with an index greater than or equal to [index] will be in the second. + Elements with an index greater than or equal to `index` will be in the second. - If [index] is zero or negative, all elements will be in the second component of the tuple. + If `index` is zero or negative, all elements will be in the second component of the tuple. - If [index] is greater than the length of the list, all elements will be in the second component of the tuple. + If `index` is greater than the length of the list, all elements will be in the second component of the tuple. - {2 Examples} + ## Examples - {[ - List.splitAt(list{1, 2, 3, 4, 5}, ~index=2) == (list{1, 2}, list{3, 4, 5}) - List.splitAt(list{1, 2, 3, 4, 5}, ~index=-1) == (list{}, list{1, 2, 3, 4, 5}) - List.splitAt(list{1, 2, 3, 4, 5}, ~index=10) == (list{1, 2, 3, 4, 5}, 10) - ]} -") + ```rescript + List.splitAt(list{1, 2, 3, 4, 5}, ~index=2) == (list{1, 2}, list{3, 4, 5}) + List.splitAt(list{1, 2, 3, 4, 5}, ~index=-1) == (list{}, list{1, 2, 3, 4, 5}) + List.splitAt(list{1, 2, 3, 4, 5}, ~index=10) == (list{1, 2, 3, 4, 5}, 10) + ``` +*/ let splitAt: (t<'a>, ~index: int) => (t<'a>, t<'a>) -@ocaml.doc(" Divides a list into a {!Tuple2} at the first element where function [f] will return [true]. +/** Divides a list into a [Tuple2](Tuple2.mdx#) at the first element where function `f` will return `true`. - Elements up to (but not including) the first element [f] returns [true] for - will be in the first component of the tuple, the remaining elements will be - in the second. + Elements up to (but not including) the first element `f` returns `true` for + will be in the first component of the tuple, the remaining elements will be + in the second. - {2 Examples} + ## Examples - {[ - List.splitWhen(list{2, 4, 5, 6, 7}, ~f=Int.isEven) == (list{2, 4}, list{5, 6, 7}) - List.splitWhen(list{2, 4, 5, 6, 7}, ~f=Fun.constant(false)) == (list{2, 4, 5, 6, 7}, list{}) - ]} -") + ```rescript + List.splitWhen(list{2, 4, 5, 6, 7}, ~f=Int.isEven) == (list{2, 4}, list{5, 6, 7}) + List.splitWhen(list{2, 4, 5, 6, 7}, ~f=Fun.constant(false)) == (list{2, 4, 5, 6, 7}, list{}) + ``` +*/ let splitWhen: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) -@ocaml.doc(" Decompose a list of {!Tuple2} into a {!Tuple2} of lists. +/** Decompose a list of [Tuple2](Tuple2.mdx#) into a [Tuple2](Tuple2.mdx#) of lists. - {2 Examples} + ## Examples - {[ - List.unzip(list{(0, true), (17, false), (1337, true)}) - == (list{0, 17, 1337}, list{true, false, true}) - ]} -") + ```rescript + List.unzip(list{(0, true), (17, false), (1337, true)}) + == (list{0, 17, 1337}, list{true, false, true}) + ``` +*/ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) -@@ocaml.text(" {1 Iterate} ") - -@ocaml.doc(" Iterates over the elements of invokes [f] for each element. +/** Iterates over the elements of invokes `f` for each element. - The function you provide must return [unit], and the [forEach] call itself also returns [unit]. + The function you provide must return `unit`, and the `forEach` call itself also returns `unit`. - You use [List.forEach] when you want to process a list only for side effects. + You use [List.forEach] when you want to process a list only for side effects. - {2 Examples} + ## Examples - {[ - List.forEach(list{1, 2, 3}, ~f=int => Int.toString(int)->Js.log) - (* - Prints - 1 - 2 - 3 - *) - ]} -") + ```rescript + List.forEach(list{1, 2, 3}, ~f=int => Int.toString(int)->Js.log) + (* + Prints + 1 + 2 + 3 + *) + ``` +*/ let forEach: (t<'a>, ~f: 'a => unit) => unit -@ocaml.doc(" Like {!forEach} but [f] is also called with the elements index. +/** Like [forEach](#forEach) but `f` is also called with the elements index. - {2 Examples} + ## Examples - {[ - List.forEachWithIndex(list{1, 2, 3}, ~f=(index, int) => j`$index: $int`->Js.log) - (* - Prints - 0: 1 - 1: 2 - 2: 3 - *) - ]} -") + ```rescript + List.forEachWithIndex(list{1, 2, 3}, ~f=(index, int) => j`$index: $int`->Js.log) + (* + Prints + 0: 1 + 1: 2 + 2: 3 + *) + ``` +*/ let forEachWithIndex: (t<'a>, ~f: (int, 'a) => unit) => unit -@ocaml.doc(" Places [sep] between all the elements of the given list. +/** Places `sep` between all the elements of the given list. - {2 Examples} + ## Examples - {[ - List.intersperse(~sep=\"on\", list{\"turtles\", \"turtles\", \"turtles\"}) - == list{\"turtles\", \"on\", \"turtles\", \"on\", \"turtles\"} + ```rescript + List.intersperse(~sep="on", list{"turtles", "turtles", "turtles"}) + == list{"turtles", "on", "turtles", "on", "turtles"} - List.intersperse(list{}, ~sep=0) == list{} - ]} -") + List.intersperse(list{}, ~sep=0) == list{} + ``` +*/ let intersperse: (t<'a>, ~sep: 'a) => t<'a> -@ocaml.doc(" Split a list into equally sized chunks. +/** Split a list into equally sized chunks. - If there aren't enough elements to make the last 'chunk', those elements are ignored. + If there aren't enough elements to make the last 'chunk', those elements are ignored. - {2 Examples} + ## Examples - {[ - List.chunksOf(~size=2, list{\"#FFBA49\", \"#9984D4\", \"#20A39E\", \"#EF5B5B\", \"#23001E\"}) - == list{list{\"#FFBA49\", \"#9984D4\"}, list{\"#20A39E\", \"#EF5B5B\"}} - ]} - ") + ```rescript + List.chunksOf(~size=2, list{"#FFBA49", "#9984D4", "#20A39E", "#EF5B5B", "#23001E"}) + == list{list{"#FFBA49", "#9984D4"}, list{"#20A39E", "#EF5B5B"}} + ``` + */ let chunksOf: (t<'a>, ~size: int) => t> -@ocaml.doc(" Provides a sliding 'window' of sub-lists over a list. +/** Provides a sliding 'window' of sub-lists over a list. - The first sub-list starts at the head of the list and takes the first [size] elements. + The first sub-list starts at the head of the list and takes the first `size` elements. - The sub-list then advances [step] (which defaults to 1) positions before taking the next [size] elements. + The sub-list then advances `step` (which defaults to 1) positions before taking the next `size` elements. - The sub-lists are guaranteed to always be of length [size] and iteration stops once a sub-list would extend beyond the end of the list. + The sub-lists are guaranteed to always be of length `size` and iteration stops once a sub-list would extend beyond the end of the list. - {2 Examples} + ## Examples - {[ - List.sliding(list{1, 2, 3, 4, 5}, ~size=1) == list{list{1}, list{2}, list{3}, list{4}, list{5}} - List.sliding(list{1, 2, 3, 4, 5}, ~size=2) == list{list{1, 2}, list{2, 3}, list{3, 4}, list{4, 5}} - List.sliding(list{1, 2, 3, 4, 5}, ~size=3) == list{list{1, 2, 3}, list{2, 3, 4}, list{3, 4, 5}} - List.sliding(list{1, 2, 3, 4, 5}, ~size=2, ~step=2) == list{list{1, 2}, list{3, 4}} - List.sliding(list{1, 2, 3, 4, 5}, ~size=1, ~step=3) == list{list{1}, list{4}} - List.sliding(list{1, 2, 3, 4, 5}, ~size=2, ~step=3) == list{list{1, 2}, list{4, 5}} - List.sliding(list{1, 2, 3, 4, 5}, ~size=7) == list{} - ]} -") + ```rescript + List.sliding(list{1, 2, 3, 4, 5}, ~size=1) == list{list{1}, list{2}, list{3}, list{4}, list{5}} + List.sliding(list{1, 2, 3, 4, 5}, ~size=2) == list{list{1, 2}, list{2, 3}, list{3, 4}, list{4, 5}} + List.sliding(list{1, 2, 3, 4, 5}, ~size=3) == list{list{1, 2, 3}, list{2, 3, 4}, list{3, 4, 5}} + List.sliding(list{1, 2, 3, 4, 5}, ~size=2, ~step=2) == list{list{1, 2}, list{3, 4}} + List.sliding(list{1, 2, 3, 4, 5}, ~size=1, ~step=3) == list{list{1}, list{4}} + List.sliding(list{1, 2, 3, 4, 5}, ~size=2, ~step=3) == list{list{1, 2}, list{4, 5}} + List.sliding(list{1, 2, 3, 4, 5}, ~size=7) == list{} + ``` +*/ let sliding: (~step: int=?, t<'a>, ~size: int) => t> -@ocaml.doc(" Divide a list into groups. +/** Divide a list into groups. - [f] is called with consecutive elements, when [f] returns [false] a new group is started. + `f` is called with consecutive elements, when `f` returns `false` a new group is started. - {2 Examples} + ## Examples - {[ - List.groupWhile(list{1, 2, 3}, ~f=Fun.constant(false)) == list{list{1}, list{2}, list{3}} + ```rescript + List.groupWhile(list{1, 2, 3}, ~f=Fun.constant(false)) == list{list{1}, list{2}, list{3}} - List.groupWhile(list{1, 2, 3}, ~f=Fun.constant(true)) == list{list{1, 2, 3}} + List.groupWhile(list{1, 2, 3}, ~f=Fun.constant(true)) == list{list{1, 2, 3}} - List.groupWhile(list{\"a\", \"b\", \"b\", \"a\", \"a\", \"a\", \"b\", \"a\"}, ~f=String.equal) - == list{list{\"a\"}, list{\"b\", \"b\"}, list{\"a\", \"a\", \"a\"}(list{\"b\"}), list{\"a\"}} + List.groupWhile(list{"a", "b", "b", "a", "a", "a", "b", "a"}, ~f=String.equal) + == list{list{"a"}, list{"b", "b"}, list{"a", "a", "a"}(list{"b"}), list{"a"}} - List.groupWhile(list{\"a\", \"b\", \"b\", \"a\", \"a\", \"a\", \"b\", \"a\"}, ~f=String.equal) - == list{list{\"a\"}, list{\"b\", \"b\"}, list{\"a\", \"a\", \"a\"}, list{\"b\"}, list{\"a\"}} - ]} -") + List.groupWhile(list{"a", "b", "b", "a", "a", "a", "b", "a"}, ~f=String.equal) + == list{list{"a"}, list{"b", "b"}, list{"a", "a", "a"}, list{"b"}, list{"a"}} + ``` +*/ let groupWhile: (t<'a>, ~f: ('a, 'a) => bool) => t> -@@ocaml.text(" {1 Convert} ") +/** Converts a list of strings into a [String](String.mdx#), placing `sep` between each string in the result. -@ocaml.doc(" Converts a list of strings into a {!String}, placing [sep] between each string in the result. + ## Examples - {2 Examples} - - {[ - List.join(list{\"Ant\", \"Bat\", \"Cat\"}, ~sep=\", \") == \"Ant, Bat, Cat\" - ]} - ") + ```rescript + List.join(list{"Ant", "Bat", "Cat"}, ~sep=", ") == "Ant, Bat, Cat" + ``` + */ let join: (t, ~sep: string) => string -@ocaml.doc(" Collect elements which [f] produces the same key for. +/** Collect elements which `f` produces the same key for. - Produces a map from ['key] to a {!List} of all elements which produce the same ['key]. + Produces a map from `'key` to a [List](List.mdx#) of all elements which produce the same `'key`. - {2 Examples} + ## Examples - {[ - let animals = list{\"Ant\", \"Bear\", \"Cat\", \"Dewgong\"} - List.groupBy(animals, module(Int), ~f=String.length)->Map.toList == - list{(3, list{\"Cat\", \"Ant\"}), (4, list{\"Bear\"}), (7, list{\"Dewgong\"})} - ]} -") + ```rescript + let animals = list{"Ant", "Bear", "Cat", "Dewgong"} + List.groupBy(animals, module(Int), ~f=String.length)->Map.toList == + list{(3, list{"Cat", "Ant"}), (4, list{"Bear"}), (7, list{"Dewgong"})} + ``` +*/ let groupBy: ( t<'value>, TableclothComparator.s<'key, 'id>, ~f: 'value => 'key, ) => TableclothMap.t<'key, list<'value>, 'id> -@ocaml.doc(" Converts a list to an {!Array}. ") +/** Converts a list to an [Array](Array.mdx#). */ let toArray: t<'a> => array<'a> -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two lists for equality using the provided function to test elements. ") +/** Test two lists for equality using the provided function to test elements. */ let equal: (t<'a>, t<'a>, ('a, 'a) => bool) => bool -@ocaml.doc(" Compare two lists using the provided [f] function to compare elements. +/** Compare two lists using the provided `f` function to compare elements. - A shorter list is 'less' than a longer one. + A shorter list is 'less' than a longer one. - {2 Examples} + ## Examples - {[ - List.compare(list{1, 2, 3}, list{1, 2, 3, 4}, Int.compare) == -1 - List.compare(list{1, 2, 3}, list{1, 2, 3}, Int.compare) == 0 - List.compare(list{1, 2, 5}, list{1, 2, 3}, Int.compare) == 1 - ]} -") + ```rescript + List.compare(list{1, 2, 3}, list{1, 2, 3, 4}, Int.compare) == -1 + List.compare(list{1, 2, 3}, list{1, 2, 3}, Int.compare) == 0 + List.compare(list{1, 2, 5}, list{1, 2, 3}, Int.compare) == 1 + ``` +*/ let compare: (t<'a>, t<'a>, ('a, 'a) => int) => int diff --git a/src/TableclothMap.resi b/src/TableclothMap.resi index 7f2ed50..2711600 100644 --- a/src/TableclothMap.resi +++ b/src/TableclothMap.resi @@ -1,489 +1,469 @@ -@@ocaml.text(" ") +/** A `Map` represents a unique mapping from keys to values. -@@ocaml.text(" A [Map] represents a unique mapping from keys to values. + `Map` is an immutable data structure which means operations like [Map.add](Map.mdx#add) and [Map.remove](Map.mdx#remove) do not modify the data structure, but return a new map with the desired changes. - [Map] is an immutable data structure which means operations like {!Map.add} and {!Map.remove} do not modify the data structure, but return a new map with the desired changes. + Since maps of `int`s and `string`s are so common the specialized [Map.Int](Map.mdx#Int) and [Map.String](Map.mdx#String) modules are available, which offer a convenient way to construct new maps. - Since maps of [int]s and [string]s are so common the specialized {!Map.Int} and {!Map.String} modules are available, which offer a convenient way to construct new maps. + You can create sets of modules types which conform to the [Comparator.S](Comparator.mdx#S) signature by using [empty](#empty), [singleton](#singleton), [fromList](#fromList) or [fromArray](#fromArray). - Custom data types can be used with maps as long as the module satisfies the {!Comparator.S} interface. + Specialised versions of the [empty](#empty), [singleton](#singleton), [fromList](#fromList) and [fromArray](#fromArray) functions available in the [Set.Int](Set.mdx#Int) and [Set.String](Set.mdx#String) sub-modules. - {[ - module Point = { - type t = (int, int) - let compare = Tuple2.compare(~f=Int.compare, ~g=Int.compare) - include Comparator.Make({ - type t = t - let compare = compare - }) - } + Custom data types can be used with maps as long as the module satisfies the [Comparator.S](Comparator.mdx#S) interface. - type animal = - | Cow - | Pig - | Alpacca + ```rescript + module Point = { + type t = (int, int) + let compare = Tuple2.compare(~f=Int.compare, ~g=Int.compare) + include Comparator.Make({ + type t = t + let compare = compare + }) + } - let pointToAnimal = Map.fromArray( - module(Point), - [((0, 0), Alpacca), ((3, 4), Cow), ((6, 7), Pig)], - ) - ]} + type animal = + | Cow + | Pig + | Alpacca - See the {!Comparator} module for a more details. -") + let pointToAnimal = Map.fromArray( + module(Point), + [((0, 0), Alpacca), ((3, 4), Cow), ((6, 7), Pig)], + ) + ``` + See the [Comparator](Comparator.mdx#) module for a more details. +*/ type t<'key, 'value, 'cmp> = Belt.Map.t<'key, 'value, 'cmp> -@@ocaml.text(" {1 Create} +/** A map with nothing in it. - You can create sets of modules types which conform to the {!Comparator.S} signature by using {!empty}, {!singleton}, {!fromList} or {!fromArray}. + Often used as an intial value for functions like [Array.fold](Array.mdx#fold). - Specialised versions of the {!empty}, {!singleton}, {!fromList} and {!fromArray} functions available in the {!Set.Int} and {!Set.String} sub-modules. -") + ## Examples -@ocaml.doc(" A map with nothing in it. + ```rescript + Array.fold(["Pear", "Orange", "Grapefruit"], ~initial=Map.empty(module(Int)), ~f=( + lengthToFruit, + fruit, + ) => Map.add(lengthToFruit, ~key=String.length(fruit), ~value=fruit))->Map.toArray == + [(4, "Pear"), (6, "Orange"), (10, "Grapefruit")] + ``` - Often used as an intial value for functions like {!Array.fold}. - - {2 Examples} - - {[ - Array.fold([\"Pear\", \"Orange\", \"Grapefruit\"], ~initial=Map.empty(module(Int)), ~f=( - lengthToFruit, - fruit, - ) => Map.add(lengthToFruit, ~key=String.length(fruit), ~value=fruit))->Map.toArray == - [(4, \"Pear\"), (6, \"Orange\"), (10, \"Grapefruit\")] - ]} - - In this particular case you might want to use {!Array.groupBy} -") + In this particular case you might want to use [Array.groupBy](Array.mdx#groupBy) +*/ let empty: TableclothComparator.s<'key, 'identity> => t<'key, 'value, 'identity> -@ocaml.doc(" Create a map from a key and value. +/** Create a map from a key and value. - {2 Examples} + ## Examples - {[ - Map.singleton(module(Int), ~key=1, ~value=\"Ant\")->Map.toArray == [(1, \"Ant\")] - ]} -") + ```rescript + Map.singleton(module(Int), ~key=1, ~value="Ant")->Map.toArray == [(1, "Ant")] + ``` +*/ let singleton: ( TableclothComparator.s<'key, 'identity>, ~key: 'key, ~value: 'value, ) => t<'key, 'value, 'identity> -@ocaml.doc(" Create a map from an {!Array} of key-value tuples. ") +/** Create a map from an [Array](Array.mdx#) of key-value tuples. */ let fromArray: ( TableclothComparator.s<'key, 'identity>, array<('key, 'value)>, ) => t<'key, 'value, 'identity> -@ocaml.doc(" Create a map of a {!List} of key-value tuples. ") +/** Create a map of a [List](List.mdx#) of key-value tuples. */ let fromList: ( TableclothComparator.s<'key, 'identity>, list<('key, 'value)>, ) => t<'key, 'value, 'identity> -@@ocaml.text(" {1 Basic operations} ") +/** Adds a new entry to a map. If `key` is allready present, its previous value is replaced with `value`. -@ocaml.doc(" Adds a new entry to a map. If [key] is allready present, its previous value is replaced with [value]. + ## Examples - {2 Examples} + ```rescript + Map.add( + Map.Int.fromArray([(1, "Ant"), (2, "Bat")]), + ~key=3, + ~value="Cat", + )->Map.toArray == [(1, "Ant"), (2, "Bat"), (3, "Cat")] - {[ - Map.add( - Map.Int.fromArray([(1, \"Ant\"), (2, \"Bat\")]), - ~key=3, - ~value=\"Cat\", - )->Map.toArray == [(1, \"Ant\"), (2, \"Bat\"), (3, \"Cat\")] - - Map.add( - Map.Int.fromArray([(1, \"Ant\"), (2, \"Bat\")]), - ~key=2, - ~value=\"Bug\", - )->Map.toArray == [(1, \"Ant\"), (2, \"Bug\")] - ]} -") + Map.add( + Map.Int.fromArray([(1, "Ant"), (2, "Bat")]), + ~key=2, + ~value="Bug", + )->Map.toArray == [(1, "Ant"), (2, "Bug")] + ``` +*/ let add: (t<'key, 'value, 'id>, ~key: 'key, ~value: 'value) => t<'key, 'value, 'id> -@ocaml.doc(" Removes a key-value pair from a map based on they provided key. - - {2 Examples} - - {[ - let animalPopulations = Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ]) - Map.remove(animalPopulations, \"Mosquito\")->Map.toArray - == [(\"Elephant\", 3_156), (\"Rhino\", 3), (\"Shrew\", 56_423)] - ]} -") +/** Removes a key-value pair from a map based on they provided key. + + ## Examples + + ```rescript + let animalPopulations = Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ]) + Map.remove(animalPopulations, "Mosquito")->Map.toArray + == [("Elephant", 3_156), ("Rhino", 3), ("Shrew", 56_423)] + ``` +*/ let remove: (t<'key, 'value, 'id>, 'key) => t<'key, 'value, 'id> -@ocaml.doc(" Get the value associated with a key. If the key is not present in the map, returns [None]. +/** Get the value associated with a key. If the key is not present in the map, returns `None`. - {2 Examples} + ## Examples - {[ - let animalPopulations = Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ]) - Map.get(animalPopulations, \"Shrew\") == Some(56_423) - ]} -") + ```rescript + let animalPopulations = Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ]) + Map.get(animalPopulations, "Shrew") == Some(56_423) + ``` +*/ let get: (t<'key, 'value, 'id>, 'key) => option<'value> -@ocaml.doc(" Update the value for a specific key using [f]. If [key] is not present in the map [f] will be called with [None]. - - {2 Examples} - - {[ - let animalPopulations = Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ]) - - Map.update(animalPopulations, ~key=\"Hedgehog\", ~f=population => - switch population { - | None => Some(1) - | Some(count) => Some(count + 1) - } - )->Map.toArray == - [ - (\"Elephant\", 3_156), - (\"Hedgehog\", 1), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ] - ]} -") +/** Update the value for a specific key using `f`. If `key` is not present in the map `f` will be called with `None`. + + ## Examples + + ```rescript + let animalPopulations = Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ]) + + Map.update(animalPopulations, ~key="Hedgehog", ~f=population => + switch population { + | None => Some(1) + | Some(count) => Some(count + 1) + } + )->Map.toArray == + [ + ("Elephant", 3_156), + ("Hedgehog", 1), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ] + ``` +*/ let update: ( t<'key, 'value, 'id>, ~key: 'key, ~f: option<'value> => option<'value>, ) => t<'key, 'value, 'id> -@@ocaml.text(" {1 Query} ") - -@ocaml.doc(" Determine if a map is empty. ") +/** Determine if a map is empty. */ let isEmpty: t<_, _, _> => bool -@ocaml.doc(" Returns the number of key-value pairs present in the map. +/** Returns the number of key-value pairs present in the map. - {2 Examples} + ## Examples - {[ - Map.Int.fromArray([(1, \"Hornet\"), (3, \"Marmot\")])->Map.length == 2 - ]} -") + ```rescript + Map.Int.fromArray([(1, "Hornet"), (3, "Marmot")])->Map.length == 2 + ``` +*/ let length: t<_, _, _> => int -@ocaml.doc(" Determine if [f] returns [true] for [any] values in a map. ") +/** Determine if `f` returns `true` for `any` values in a map. */ let any: (t<_, 'value, _>, ~f: 'value => bool) => bool -@ocaml.doc(" Determine if [f] returns [true] for [all] values in a map. ") +/** Determine if `f` returns `true` for `all` values in a map. */ let all: (t<_, 'value, _>, ~f: 'value => bool) => bool -@ocaml.doc(" Returns, as an {!Option} the first key-value pair for which [f] evaluates to [true]. +/** Returns, as an [Option](Option.mdx#) the first key-value pair for which `f` evaluates to `true`. - If [f] doesn't return [true] for any of the elements [find] will return [None]. + If `f` doesn't return `true` for any of the elements `find` will return `None`. - Searches starting from the smallest {b key} + Searches starting from the smallest *key* - {2 Examples} + ## Examples - {[ - Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ])->Map.find(~f=(~key, ~value) => value > 10_000) - == Some(\"Mosquito\", 56_123_156) - ]} -") + ```rescript + Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ])->Map.find(~f=(~key, ~value) => value > 10_000) + == Some("Mosquito", 56_123_156) + ``` +*/ let find: (t<'key, 'value, _>, ~f: (~key: 'key, ~value: 'value) => bool) => option<('key, 'value)> -@ocaml.doc(" Determine if a map includes [key]. ") +/** Determine if a map includes `key`. */ let includes: (t<'key, _, _>, 'key) => bool -@ocaml.doc(" Returns, as an {!Option}, the smallest {b key } in the map. +/** Returns, as an [Option](Option.mdx#), the smallest *key* in the map. - Returns [None] if the map is empty. + Returns `None` if the map is empty. - {2 Examples} + ## Examples - {[ - Map.Int.fromArray([(8, \"Pigeon\"), (1, \"Hornet\"), (3, \"Marmot\")]) - ->Map.minimum == Some(1) - ]} -") + ```rescript + Map.Int.fromArray([(8, "Pigeon"), (1, "Hornet"), (3, "Marmot")]) + ->Map.minimum == Some(1) + ``` +*/ let minimum: t<'key, _, _> => option<'key> -@ocaml.doc(" Returns the largest {b key } in the map. +/** Returns the largest *key* in the map. - Returns [None] if the map is empty. + Returns `None` if the map is empty. - {2 Examples} + ## Examples - {[ - Map.Int.fromArray([(8, \"Pigeon\"), (1, \"Hornet\"), (3, \"Marmot\")]) - ->Map.maximum == Some(8) - ]} -") + ```rescript + Map.Int.fromArray([(8, "Pigeon"), (1, "Hornet"), (3, "Marmot")]) + ->Map.maximum == Some(8) + ``` +*/ let maximum: t<'key, _, _> => option<'key> -@ocaml.doc(" Returns, as an {!Option}, a {!Tuple2} of the [(minimum, maximum)] {b key}s in the map. +/** Returns, as an [Option](Option.mdx#), a [Tuple2](Tuple2.mdx#) of the [(minimum, maximum)] *key*s in the map. - Returns [None] if the map is empty. + Returns `None` if the map is empty. - {2 Examples} + ## Examples - {[ - Map.Int.fromArray([(8, \"Pigeon\"), (1, \"Hornet\"), (3, \"Marmot\")]) - ->Map.extent == Some(1, 8) - ]} -") + ```rescript + Map.Int.fromArray([(8, "Pigeon"), (1, "Hornet"), (3, "Marmot")]) + ->Map.extent == Some(1, 8) + ``` +*/ let extent: t<'key, _, _> => option<('key, 'key)> -@@ocaml.text(" {1 Combine} ") +/** Combine two maps. -@ocaml.doc(" Combine two maps. + You provide a function `f` which is provided the key and the optional + value from each map and needs to account for the three possibilities: - You provide a function [f] which is provided the key and the optional - value from each map and needs to account for the three possibilities: + - Only the 'left' map includes a value for the key. + - Both maps contain a value for the key. + - Only the 'right' map includes a value for the key. - - Only the 'left' map includes a value for the key. - - Both maps contain a value for the key. - - Only the 'right' map includes a value for the key. + You then traverse all the keys, building up whatever you want. - You then traverse all the keys, building up whatever you want. + ## Examples - {2 Examples} + ```rescript + let animalToPopulation = Map.String.fromArray([("Elephant", 3_156), ("Shrew", 56_423)]) - {[ - let animalToPopulation = Map.String.fromArray([(\"Elephant\", 3_156), (\"Shrew\", 56_423)]) + let animalToPopulationGrowthRate = Map.String.fromArray([ + ("Elephant", 0.88), + ("Squirrel", 1.2), + ("Python", 4.0), + ]) - let animalToPopulationGrowthRate = Map.String.fromArray([ - (\"Elephant\", 0.88), - (\"Squirrel\", 1.2), - (\"Python\", 4.0), - ]) - - Map.merge(animalToPopulation, animalToPopulationGrowthRate, ~f=(_animal, population, growth) => - switch Option.both(population, growth) { - | Some(population, growth) => Some(Float.fromInt(population) *. growth) - | None => None - } - )->Map.toArray - == [(\"Elephant\", 2777.28)] - ]} -") + Map.merge(animalToPopulation, animalToPopulationGrowthRate, ~f=(_animal, population, growth) => + switch Option.both(population, growth) { + | Some(population, growth) => Some(Float.fromInt(population) *. growth) + | None => None + } + )->Map.toArray + == [("Elephant", 2777.28)] + ``` +*/ let merge: ( t<'key, 'v1, 'id>, t<'key, 'v2, 'id>, ~f: ('key, option<'v1>, option<'v2>) => option<'v3>, ) => t<'key, 'v3, 'id> -@@ocaml.text(" {1 Transform} ") - -@ocaml.doc(" Apply a function to all values in a dictionary. +/** Apply a function to all values in a dictionary. - {2 Examples} + ## Examples - {[ - Map.String.fromArray([(\"Elephant\", 3_156), (\"Shrew\", 56_423)]) - ->Map.map(~f=Int.toString) - ->Map.toArray == [(\"Elephant\", \"3156\"), (\"Shrew\", \"56423\")] - ]} -") + ```rescript + Map.String.fromArray([("Elephant", 3_156), ("Shrew", 56_423)]) + ->Map.map(~f=Int.toString) + ->Map.toArray == [("Elephant", "3156"), ("Shrew", "56423")] + ``` +*/ let map: (t<'key, 'value, 'id>, ~f: 'value => 'b) => t<'key, 'b, 'id> -@ocaml.doc(" Like {!map} but [f] is also called with each values corresponding key. ") +/** Like [map](#map) but `f` is also called with each values corresponding key. */ let mapWithIndex: (t<'key, 'value, 'id>, ~f: ('key, 'value) => 'b) => t<'key, 'b, 'id> -@ocaml.doc(" Keep elements that [f] returns [true] for. +/** Keep elements that `f` returns `true` for. - {2 Examples} + ## Examples - {[ - Map.String.fromArray([(\"Elephant\", 3_156), (\"Shrew\", 56_423)]) - ->Map.filter(~f=population => population > 10_000) - ->Map.toArray - == [(\"Shrew\", 56423)] - ]} -") + ```rescript + Map.String.fromArray([("Elephant", 3_156), ("Shrew", 56_423)]) + ->Map.filter(~f=population => population > 10_000) + ->Map.toArray + == [("Shrew", 56423)] + ``` +*/ let filter: (t<'key, 'value, 'id>, ~f: 'value => bool) => t<'key, 'value, 'id> -@ocaml.doc(" Mombine {!map} and {!filter} into a single pass. +/** Mombine [map](#map) and [filter](#filter) into a single pass. - The output list only contains elements for which [f] returns [Some]. -") + The output list only contains elements for which `f` returns `Some`. +*/ let filterMap: ( t<'key, 'value, 'id>, ~f: (~key: 'key, ~value: 'value) => option<'b>, ) => t<'key, 'b, 'id> -@ocaml.doc(" Divide a map into two, the first map will contain the key-value pairs that [f] returns [true] for, pairs that [f] returns [false] for will end up in the second. +/** Divide a map into two, the first map will contain the key-value pairs that `f` returns `true` for, pairs that `f` returns `false` for will end up in the second. - {2 Examples} + ## Examples - {[ - let (endangered, notEndangered) = - Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ])->Map.partition(~f=(~key as _, ~value as population) => population < 10_000) + ```rescript + let (endangered, notEndangered) = + Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ])->Map.partition(~f=(~key as _, ~value as population) => population < 10_000) - endangered->Map.toArray == [(\"Elephant\", 3_156), (\"Rhino\", 3)] + endangered->Map.toArray == [("Elephant", 3_156), ("Rhino", 3)] - notEndangered->Map.toArray == [(\"Mosquito\", 56_123_156), (\"Shrew\", 56_423)] - ]} -") + notEndangered->Map.toArray == [("Mosquito", 56_123_156), ("Shrew", 56_423)] + ``` +*/ let partition: ( t<'key, 'value, 'id>, ~f: (~key: 'key, ~value: 'value) => bool, ) => (t<'key, 'value, 'id>, t<'key, 'value, 'id>) -@ocaml.doc(" Like {!Array.fold} but [f] is also called with both the [key] and [value]. ") +/** Like [Array.fold](Array.mdx#fold) but `f` is also called with both the `key` and `value`. */ let fold: (t<'key, 'value, _>, ~initial: 'a, ~f: ('a, ~key: 'key, ~value: 'value) => 'a) => 'a -@@ocaml.text(" {1 Iterate} ") - -@ocaml.doc(" Runs a function [f] against each {b value} in the map. ") +/** Runs a function `f` against each *value* in the map. */ let forEach: (t<_, 'value, _>, ~f: 'value => unit) => unit -@ocaml.doc(" Like {!Map.forEach} except [~f] is also called with the corresponding key. ") +/** Like [Map.forEach](Map.mdx#forEach) except `~f` is also called with the corresponding key. */ let forEachWithIndex: (t<'key, 'value, _>, ~f: (~key: 'key, ~value: 'value) => unit) => unit -@@ocaml.text(" {1 Convert} ") - -@ocaml.doc(" Get a {!List} of all of the keys in a map. +/** Get a [List](List.mdx#) of all of the keys in a map. - {2 Examples} + ## Examples - {[ - Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ])->Map.keys - == list{\"Elephant\", \"Mosquito\", \"Rhino\", \"Shrew\"} - ]} -") + ```rescript + Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ])->Map.keys + == list{"Elephant", "Mosquito", "Rhino", "Shrew"} + ``` +*/ let keys: t<'key, _, _> => list<'key> -@ocaml.doc(" Get a {!List} of all of the values in a map. +/** Get a [List](List.mdx#) of all of the values in a map. - {2 Examples} + ## Examples - {[ - Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ])->Map.values - == list{3_156, 56_123_156, 3, 56_423} - ]} -") + ```rescript + Map.String.fromArray([ + ("Elephant", 3_156), + ("Mosquito", 56_123_156), + ("Rhino", 3), + ("Shrew", 56_423), + ])->Map.values + == list{3_156, 56_123_156, 3, 56_423} + ``` +*/ let values: t<_, 'value, _> => list<'value> -@ocaml.doc(" Get an {!Array} of all of the key-value pairs in a map. ") +/** Get an [Array](Array.mdx#) of all of the key-value pairs in a map. */ let toArray: t<'key, 'value, _> => array<('key, 'value)> -@ocaml.doc(" Get a {!List} of all of the key-value pairs in a map. ") +/** Get a [List](List.mdx#) of all of the key-value pairs in a map. */ let toList: t<'key, 'value, _> => list<('key, 'value)> -@ocaml.doc( - " Construct a Map which can be keyed by any data type using the polymorphic [compare] function. " -) +/** Construct a Map which can be keyed by any data type using the polymorphic `compare` function. */ module Poly: { type identity type t<'key, 'value> = t<'key, 'value, identity> - @ocaml.doc(" A map with nothing in it. ") + /** A map with nothing in it. */ let empty: unit => t<'key, 'value> - @ocaml.doc(" Create a map from a key and value. + /** Create a map from a key and value. - {2 Examples} + ## Examples - {[ - Map.Poly.singleton(~key=false, ~value=1)->Map.toArray == [(false, 1)] - ]} - ") + ```rescript + Map.Poly.singleton(~key=false, ~value=1)->Map.toArray == [(false, 1)] + ``` + */ let singleton: (~key: 'key, ~value: 'value) => t<'key, 'value> - @ocaml.doc(" Create a map from an {!Array} of key-value tuples. ") + /** Create a map from an [Array](Array.mdx#) of key-value tuples. */ let fromArray: array<('key, 'value)> => t<'key, 'value> - @ocaml.doc(" Create a map from a {!List} of key-value tuples. ") + /** Create a map from a [List](List.mdx#) of key-value tuples. */ let fromList: list<('key, 'value)> => t<'key, 'value> } -@ocaml.doc(" Construct a Map with {!Int}s for keys. ") +/** Construct a Map with [Int](Int.mdx#)s for keys. */ module Int: { type identity type t<'value> = t - @ocaml.doc(" A map with nothing in it. ") + /** A map with nothing in it. */ let empty: t<'value> - @ocaml.doc(" Create a map from a key and value. + /** Create a map from a key and value. - {2 Examples} + ## Examples - {[ - Map.Int.singleton(~key=1, ~value=\"Ant\")->Map.toArray == [(1, \"Ant\")] - ]} - ") + ```rescript + Map.Int.singleton(~key=1, ~value="Ant")->Map.toArray == [(1, "Ant")] + ``` + */ let singleton: (~key: int, ~value: 'value) => t<'value> - @ocaml.doc(" Create a map from an {!Array} of key-value tuples. ") + /** Create a map from an [Array](Array.mdx#) of key-value tuples. */ let fromArray: array<(int, 'value)> => t<'value> - @ocaml.doc(" Create a map of a {!List} of key-value tuples. ") + /** Create a map of a [List](List.mdx#) of key-value tuples. */ let fromList: list<(int, 'value)> => t<'value> } -@ocaml.doc(" Construct a Map with {!String}s for keys. ") +/** Construct a Map with [String](String.mdx#)s for keys. */ module String: { type identity type t<'value> = t - @ocaml.doc(" A map with nothing in it. ") + /** A map with nothing in it. */ let empty: t<'value> - @ocaml.doc(" Create a map from a key and value. + /** Create a map from a key and value. - {2 Examples} + ## Examples - {[ - Map.String.singleton(~key=\"Ant\", ~value=1)->Map.toArray == [(\"Ant\", 1)] - ]} - ") + ```rescript + Map.String.singleton(~key="Ant", ~value=1)->Map.toArray == [("Ant", 1)] + ``` + */ let singleton: (~key: string, ~value: 'value) => t<'value> - @ocaml.doc(" Create a map from an {!Array} of key-value tuples. ") + /** Create a map from an [Array](Array.mdx#) of key-value tuples. */ let fromArray: array<(string, 'value)> => t<'value> - @ocaml.doc(" Create a map from a {!List} of key-value tuples. ") + /** Create a map from a [List](List.mdx#) of key-value tuples. */ let fromList: list<(string, 'value)> => t<'value> } diff --git a/src/TableclothOption.resi b/src/TableclothOption.resi index 5bdeab5..3f4db0e 100644 --- a/src/TableclothOption.resi +++ b/src/TableclothOption.resi @@ -1,329 +1,324 @@ -@@ocaml.text(" ") +/** [Option](Option.mdx#) represents a value which may not be present. -@@ocaml.text(" {!Option} represents a value which may not be present. + It is a variant containing the `Some('a)` and `None` constructors - It is a variant containing the [Some('a)] and [None] constructors + ```rescript + type t<'a> = + | Some('a) + | None + ``` - {[ - type t<'a> = - | Some('a) - | None - ]} + Many other languages use `null` or `nil` to represent something similar. - Many other languages use [null] or [nil] to represent something similar. + [Option](Option.mdx#) values are very common and they are used in a number of ways: + - Initial values + - Optional function arguments + - Optional record fields + - Return values for functions that are not defined over their entire input range (partial functions). + - Return value for otherwise reporting simple errors, where `None` is returned on error. - {!Option} values are very common and they are used in a number of ways: - - Initial values - - Optional function arguments - - Optional record fields - - Return values for functions that are not defined over their entire input range (partial functions). - - Return value for otherwise reporting simple errors, where [None] is returned on error. + Lots of functions in `Tablecloth` return options, one you have one you can + work with the value it might contain by: - Lots of functions in [Tablecloth] return options, one you have one you can - work with the value it might contain by: + - Pattern matching + - Using [map](#map) or [andThen](#andThen) + - Unwrapping it using [unwrap](#unwrap) + - Converting a `None` into an exception using[unwrapUnsafe](#unwrapUnsafe) - - Pattern matching - - Using {!map} or {!andThen} - - Unwrapping it using {!unwrap} - - Converting a [None] into an exception using{!unwrapUnsafe} - - If the function you are writing can fail in a variety of ways, use a {!Result} instead to - better communicate with the caller. - - If a function only fails in unexpected, unrecoverable ways, maybe you want raise exception. -") + If the function you are writing can fail in a variety of ways, use a [Result](Result.mdx#) instead to + better communicate with the caller. + If a function only fails in unexpected, unrecoverable ways, maybe you want raise exception. +*/ type t<'a> = option<'a> -@ocaml.doc(" A function version of the [Some] constructor. +/** A function version of the `Some` constructor. - In most situations you just want to use the [Some] constructor directly. + In most situations you just want to use the `Some` constructor directly. - Note that when using the Rescript syntax you {b can} use fast pipe ([->]) with variant constructors, so you don't need this function. + Note that when using the Rescript syntax you *can* use fast pipe (`->`) with variant constructors, so you don't need this function. - See the {{: https://rescript-lang.org/docs/manual/latest/pipe#pipe-into-variants} Reason docs } for more. + See the [Reason docs](https://rescript-lang.org/docs/manual/latest/pipe#pipe-into-variants) for more. - {2 Examples} + ## Examples - {[ - String.reverse(\"desserts\")->Option.some == Some(\"stressed\") - String.reverse(\"desserts\")->Some == Some(\"stressed\") - ]} - ") + ```rescript + String.reverse("desserts")->Option.some == Some("stressed") + String.reverse("desserts")->Some == Some("stressed") + ``` + */ let some: 'a => option<'a> -@ocaml.doc(" Returns [None] if the first argument is [None], otherwise return the second argument. +/** Returns `None` if the first argument is `None`, otherwise return the second argument. - Unlike the built in [&&] operator, the [and_] function does not short-circuit. + Unlike the built in `&&` operator, the `and_` function does not short-circuit. - When you call [and_], both arguments are evaluated before being passed to the function. + When you call `and_`, both arguments are evaluated before being passed to the function. - {2 Examples} + ## Examples - {[ - Option.and_(Some(11), Some(22)) == Some(22) - Option.and_(None, Some(22)) == None - Option.and_(Some(11), None) == None - Option.and_(None, None) == None - ]} -") + ```rescript + Option.and_(Some(11), Some(22)) == Some(22) + Option.and_(None, Some(22)) == None + Option.and_(Some(11), None) == None + Option.and_(None, None) == None + ``` +*/ let and_: (t<'a>, t<'a>) => t<'a> -@ocaml.doc(" Return the first argument if it {!isSome}, otherwise return the second. +/** Return the first argument if it [isSome](#isSome), otherwise return the second. - Unlike the built in [||] operator, the [or_] function does not short-circuit. - When you call [or_], both arguments are evaluated before being passed to the function. + Unlike the built in `||` operator, the `or_` function does not short-circuit. + When you call `or_`, both arguments are evaluated before being passed to the function. - {2 Examples} + ## Examples - {[ - Option.or_(Some(11), Some(22)) == Some(11) - Option.or_(None, Some(22)) == Some(22) - Option.or_(Some(11), None) == Some(11) - Option.or_(None, None) == None - ]} -") + ```rescript + Option.or_(Some(11), Some(22)) == Some(11) + Option.or_(None, Some(22)) == Some(22) + Option.or_(Some(11), None) == Some(11) + Option.or_(None, None) == None + ``` +*/ let or_: (t<'a>, t<'a>) => t<'a> -@ocaml.doc(" Return the second argument if it {!isSome}, otherwise return the first. +/** Return the second argument if it [isSome](#isSome), otherwise return the first. - Like {!or_} but in reverse. Useful when using the [|>] operator + Like [or_](#or_) but in reverse. Useful when using the `|>` operator - {2 Examples} + ## Examples - {[ - Option.orElse(Some(11), Some(22)) == Some(22) - Option.orElse(None, Some(22)) == Some(22) - Option.orElse(Some(11), None) == Some(11) - Option.orElse(None, None) == None - ]} -") + ```rescript + Option.orElse(Some(11), Some(22)) == Some(22) + Option.orElse(None, Some(22)) == Some(22) + Option.orElse(Some(11), None) == Some(11) + Option.orElse(None, None) == None + ``` +*/ let orElse: (t<'a>, t<'a>) => t<'a> -@ocaml.doc(" Transform two options into an option of a {!Tuple2}. +/** Transform two options into an option of a [Tuple2](Tuple2.mdx#). - Returns None if either of the aguments is None. + Returns None if either of the aguments is None. - {2 Examples} + ## Examples - {[ - Option.both(Some(3004), Some(\"Ant\")) == Some(3004, \"Ant\") - Option.both(Some(3004), None) == None - Option.both(None, Some(\"Ant\")) == None - Option.both(None, None) == None - ]} -") + ```rescript + Option.both(Some(3004), Some("Ant")) == Some(3004, "Ant") + Option.both(Some(3004), None) == None + Option.both(None, Some("Ant")) == None + Option.both(None, None) == None + ``` +*/ let both: (t<'a>, t<'b>) => t<('a, 'b)> -@ocaml.doc(" Flatten two optional layers into a single optional layer. +/** Flatten two optional layers into a single optional layer. - {2 Examples} + ## Examples - {[ - Option.flatten(Some(Some(4))) == Some(4) - Option.flatten(Some(None)) == None - Option.flatten(None) == None - ]} -") + ```rescript + Option.flatten(Some(Some(4))) == Some(4) + Option.flatten(Some(None)) == None + Option.flatten(None) == None + ``` +*/ let flatten: t> => t<'a> -@ocaml.doc(" Transform the value inside an option. +/** Transform the value inside an option. - Leaves [None] untouched. + Leaves `None` untouched. - {2 Examples} + ## Examples - {[ - Option.map(~f=x => x * x, Some(9)) == Some(81) - Option.map(~f=Int.toString, Some(9)) == Some(\"9\") - Option.map(~f=x => x * x, None) == None - ]} -") + ```rescript + Option.map(~f=x => x * x, Some(9)) == Some(81) + Option.map(~f=Int.toString, Some(9)) == Some("9") + Option.map(~f=x => x * x, None) == None + ``` +*/ let map: (t<'a>, ~f: 'a => 'b) => t<'b> -@ocaml.doc(" Combine two {!Option}s. +/** Combine two [Option](Option.mdx#)s. - If both options are [Some] returns, as [Some] the result of running [f] on both values. + If both options are `Some` returns, as `Some` the result of running `f` on both values. - If either value is [None], returns [None]. + If either value is `None`, returns `None`. - {2 Examples} + ## Examples - {[ - Option.map2(Some(3), Some(4), ~f=Int.add) == Some(7) - Option.map2(Some(3), Some(4), ~f=Tuple.make) == Some(3, 4) - Option.map2(Some(3), None, ~f=Int.add) == None - Option.map2(None, Some(4), ~f=Int.add) == None - ]} -") + ```rescript + Option.map2(Some(3), Some(4), ~f=Int.add) == Some(7) + Option.map2(Some(3), Some(4), ~f=Tuple.make) == Some(3, 4) + Option.map2(Some(3), None, ~f=Int.add) == None + Option.map2(None, Some(4), ~f=Int.add) == None + ``` +*/ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> -@ocaml.doc(" Chain together many computations that may not return a value. +/** Chain together many computations that may not return a value. - It is helpful to see its definition: + It is helpful to see its definition: - {[ - let andThen = (t, ~f) => - switch t { - | Some(x) => f(x) - | None => None - } - ]} + ```rescript + let andThen = (t, ~f) => + switch t { + | Some(x) => f(x) + | None => None + } + ``` - This means we only continue with the callback if we have a value. + This means we only continue with the callback if we have a value. - For example, say you need to parse some user input as a month: + For example, say you need to parse some user input as a month: - {[ - let toValidMonth = (month) => - if 1 <= month && month <= 12 { - Some(month) - } else { - None - } + ```rescript + let toValidMonth = (month) => + if 1 <= month && month <= 12 { + Some(month) + } else { + None + } - let userInput = \"5\" + let userInput = "5" - Int.fromString(userInput)->Option.andThen(~f=toValidMonth) - ]} + Int.fromString(userInput)->Option.andThen(~f=toValidMonth) + ``` - If [Int.fromString] produces [None] (because the [userInput] was not an - integer) this entire chain of operations will short-circuit and result in - [None]. If [toValidMonth] results in [None], again the chain of - computations will result in [None]. + If `Int.fromString` produces `None` (because the `userInput` was not an + integer) this entire chain of operations will short-circuit and result in + `None`. If `toValidMonth` results in `None`, again the chain of + computations will result in `None`. - {2 Examples} + ## Examples - {[ - Option.andThen(Some([1, 2, 3]), ~f=Array.first) == Some(1) - Option.andThen(Some([]), ~f=Array.first) == None - ]} -") + ```rescript + Option.andThen(Some([1, 2, 3]), ~f=Array.first) == Some(1) + Option.andThen(Some([]), ~f=Array.first) == None + ``` +*/ let andThen: (t<'a>, ~f: 'a => t<'b>) => t<'b> -@ocaml.doc(" Unwrap an [option<'a>] returning [default] if called with [None]. +/** Unwrap an `option<'a>` returning `default` if called with `None`. - This comes in handy when paired with functions like {!Map.get}, - {!Array.first} or {!List.head} which return an {!Option}. + This comes in handy when paired with functions like [Map.get](Map.mdx#get), + [Array.first](Array.mdx#first) or [List.head](List.mdx#head) which return an [Option](Option.mdx#). - {b Note:} This can be overused! Many cases are better handled using pattern matching, {!map} or {!andThen}. + *Note:* This can be overused! Many cases are better handled using pattern matching, [map](#map) or [andThen](#andThen). - {2 Examples} + ## Examples - {[ - Option.unwrap(Some(42), ~default=99) == 42 - Option.unwrap(None, ~default=99) == 99 - Option.unwrap(Map.get(Map.String.empty, \"Tom\"), ~default=\"unknown\") == \"unknown\" - ]} -") + ```rescript + Option.unwrap(Some(42), ~default=99) == 42 + Option.unwrap(None, ~default=99) == 99 + Option.unwrap(Map.get(Map.String.empty, "Tom"), ~default="unknown") == "unknown" + ``` +*/ let unwrap: (t<'a>, ~default: 'a) => 'a -@ocaml.doc(" Unwrap an [option('a)] returning the enclosed ['a]. +/** Unwrap an `option<'a>` returning the enclosed `'a`. - {b Note} in most situations it is better to use pattern matching, {!unwrap}, {!map} or {!andThen}. - Can you structure your code slightly differently to avoid potentially raising an exception? + *Note:* in most situations it is better to use pattern matching, [unwrap](#unwrap), [map](#map) or [andThen](#andThen). + Can you structure your code slightly differently to avoid potentially raising an exception? - {3 Exceptions} + ### Exceptions - Raises an [Invalid_argument] exception if called with [None] + Raises an `Invalid_argument` exception if called with `None` - {2 Examples} + ## Examples - {[ - Array.first([1, 2, 3])->Option.unwrapUnsafe == 1 - Array.first([])->Option.unwrapUnsafe // will raise Invalid_argument - ]} -") + ```rescript + Array.first([1, 2, 3])->Option.unwrapUnsafe == 1 + Array.first([])->Option.unwrapUnsafe // will raise Invalid_argument + ``` +*/ let unwrapUnsafe: t<'a> => 'a -@ocaml.doc(" Check if an {!Option} is a [Some]. +/** Check if an [Option](Option.mdx#) is a `Some`. - In most situtations you should just use pattern matching instead. + In most situtations you should just use pattern matching instead. - {2 Examples} + ## Examples - {[ - Option.isSome(Some(3004)) == true - Option.isSome(None) == false - ]} -") + ```rescript + Option.isSome(Some(3004)) == true + Option.isSome(None) == false + ``` +*/ let isSome: t<'a> => bool -@ocaml.doc(" Check if an {!Option} is a [None]. +/** Check if an [Option](Option.mdx#) is a `None`. - In most situtations you should just use pattern matching instead. + In most situtations you should just use pattern matching instead. - {2 Examples} + ## Examples - {[ - Option.isNone(Some(3004)) == false - Option.isNone(None) == true - ]} -") + ```rescript + Option.isNone(Some(3004)) == false + Option.isNone(None) == true + ``` +*/ let isNone: t<'a> => bool -@ocaml.doc(" Run a function against an [Some(value)], ignores [None]s. +/** Run a function against an `Some(value)`, ignores `None`s. - {2 Examples} + ## Examples - {[ - Option.tap(Some(\"Dog\"), ~f=Js.log) - (* logs \"Dog\" *) - ]} -") + ```rescript + Option.tap(Some("Dog"), ~f=Js.log) + (* logs "Dog" *) + ``` +*/ let tap: (t<'a>, ~f: 'a => unit) => unit -@ocaml.doc(" Convert an option to an {!Array}. +/** Convert an option to an [Array](Array.mdx#). - [None] is represented as an empty array and [Some] is represented as an array of one element. + `None` is represented as an empty array and `Some` is represented as an array of one element. - {2 Examples} + ## Examples - {[ - Option.toArray(Some(3004)) == [3004] - Option.toArray(None) == [ - ]} -") + ```rescript + Option.toArray(Some(3004)) == [3004] + Option.toArray(None) == [ + ``` +*/ let toArray: t<'a> => array<'a> -@ocaml.doc(" Convert an option to a {!List}. +/** Convert an option to a [List](List.mdx#). - [None] is represented as an empty list and [Some] is represented as a list of one element. + `None` is represented as an empty list and `Some` is represented as a list of one element. - {2 Examples} + ## Examples - {[ - Option.toList(Some(3004)) == list{3004} - Option.toList(None) == list{} - ]} -") + ```rescript + Option.toList(Some(3004)) == list{3004} + Option.toList(None) == list{} + ``` +*/ let toList: t<'a> => list<'a> -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two optional values for equality using the provided function. +/** Test two optional values for equality using the provided function. - {2 Examples} + ## Examples - {[ - Option.equal(Some(1), Some(1), Int.equal) == true - Option.equal(Some(1), Some(3), Int.equal) == false - Option.equal(Some(1), None, Int.equal) == false - Option.equal(None, None, Int.equal) == true - ]} -") + ```rescript + Option.equal(Some(1), Some(1), Int.equal) == true + Option.equal(Some(1), Some(3), Int.equal) == false + Option.equal(Some(1), None, Int.equal) == false + Option.equal(None, None, Int.equal) == true + ``` +*/ let equal: (t<'a>, t<'a>, ('a, 'a) => bool) => bool -@ocaml.doc(" Compare two optional values using the provided [f] function. +/** Compare two optional values using the provided `f` function. - A [None] is \"less\" than a [Some]. + A `None` is "less" than a `Some`. - {2 Examples} + ## Examples - {[ - Option.compare(Some(1), Some(3), ~f=Int.compare) == -1 - Option.compare(Some(1), None, ~f=Int.compare) == 1 - Option.compare(None, None, ~f=Int.compare) == 0 - ]} -") + ```rescript + Option.compare(Some(1), Some(3), ~f=Int.compare) == -1 + Option.compare(Some(1), None, ~f=Int.compare) == 1 + Option.compare(None, None, ~f=Int.compare) == 0 + ``` +*/ let compare: (t<'a>, t<'a>, ~f: ('a, 'a) => int) => int diff --git a/src/TableclothResult.resi b/src/TableclothResult.resi index 443ecf2..3f0095a 100644 --- a/src/TableclothResult.resi +++ b/src/TableclothResult.resi @@ -1,457 +1,459 @@ -@@ocaml.text(" ") +/** A [Result](Result.mdx#) is used to represent a computation which may fail. -@@ocaml.text(" A {!Result} is used to represent a computation which may fail. + A [Result](Result.mdx#) is a variant, which has a constructor for successful results + `Ok('ok)`, and one for unsuccessful results `[Error('error)]`. - A [Result] is a variant, which has a constructor for successful results - [Ok('ok)], and one for unsuccessful results ([Error('error)]). + ```rescript + type t<'ok, 'error> = + | Ok('ok) + | Error('error) + ``` - {[ - type t<'ok, 'error> = - | Ok('ok) - | Error('error) - ]} + Here is how you would annotate a [Result](Result.mdx#) variable whose `Ok` + variant is an integer and whose `Error` variant is a string: - Here is how you would annotate a [Result] variable whose [Ok] - variant is an integer and whose [Error] variant is a string: + ```rescript + let ok: Result.t = Ok(3) + let error: Result.t = Error("This computation failed!") + ``` - {[ - let ok: Result.t = Ok(3) - let error: Result.t = Error(\"This computation failed!\") - ]} - - {b Note} The ['error] case can be of {b any} type and while [string] is very common you could also use: - - [Array.t(string)] to allow errors to be accumulated - - [exn], in which case the result type just makes exceptions explicit in the return type - - A variant or polymorphic variant, with one case per possible error. This is means each error can be dealt with explicitly. See {{: https://dev.to/kevanstannard/exploring-rescript-exception-handling-57o3 } this excellent article} for more information on this approach. - - If the function you are writing can only fail in a single obvious way, maybe you want an {!Option} instead. -") + *Note:* The `'error` case can be of *any* type and while `string` is very common you could also use: + - `Array.t(string)` to allow errors to be accumulated + - `exn`, in which case the result type just makes exceptions explicit in the return type + - A variant or polymorphic variant, with one case per possible error. This is means each error can be dealt with explicitly. See [ this excellent article](https://dev.to/kevanstannard/exploring-rescript-exception-handling-57o3) for more information on this approach. + If the function you are writing can only fail in a single obvious way, maybe you want an [Option](Option.mdx#) instead. +*/ type t<'ok, 'error> = result<'ok, 'error> -@@ocaml.text(" {1 Create} ") - -@ocaml.doc(" A function alternative to the [Ok] constructor which can be used in places where - the constructor isn't permitted or functions like {!List.map}. +/** A function alternative to the `Ok` constructor which can be used in places where + the constructor isn't permitted or functions like [List.map](List.mdx#map). - {2 Examples} + ## Examples - {[ - String.reverse(\"desserts\") ->Result.ok == Ok(\"stressed\") - Array.map([1, 2, 3], ~f=Result.ok) == [Ok(1), Ok(2), Ok(3)] - ]} -") + ```rescript + String.reverse("desserts") ->Result.ok == Ok("stressed") + Array.map([1, 2, 3], ~f=Result.ok) == [Ok(1), Ok(2), Ok(3)] + ``` +*/ let ok: 'ok => t<'ok, 'error> -@ocaml.doc(" A function alternative to the [Error] constructor which can be used in places where - the constructor isn't permitted such as at the of a {!Fun.pipe} or functions like {!List.map}. +/** A function alternative to the `Error` constructor which can be used in places where + the constructor isn't permitted such as at the of a [Fun.pipe](Fun.mdx#pipe) or functions like [List.map](List.mdx#map). - {b Note} + *Note* - In Rescript you {b can} use constructors with the fast pipe ([->]). + In Rescript you *can* use constructors with the fast pipe (`->`). - {[ - 5->Ok == Ok(5) - ]} + ```rescript + 5->Ok == Ok(5) + ``` - See the {{: https://reasonml.github.io/docs/en/pipe-first#pipe-into-variants} Rescript docs } for more. + See the [Rescript docs](https://reasonml.github.io/docs/en/pipe-first#pipe-into-variants) for more. - {2 Examples} + ## Examples - {[ - Int.negate(3)->Result.error == Error(-3) - Array.map([1, 2, 3], ~f=Result.error) == [Error(1), Error(2), Error(3)] - ]} -") + ```rescript + Int.negate(3)->Result.error == Error(-3) + Array.map([1, 2, 3], ~f=Result.error) == [Error(1), Error(2), Error(3)] + ``` +*/ let error: 'error => t<'ok, 'error> -@ocaml.doc(" Run the provided function and wrap the returned value in a {!Result}, catching any exceptions raised. +/** Run the provided function and wrap the returned value in a [Result](Result.mdx#), catching any exceptions raised. - {2 Examples} + ## Examples - {[ - Result.attempt(() => 5 / 0) // returns Error(Division_by_zero) + ```rescript + Result.attempt(() => 5 / 0) // returns Error(Division_by_zero) - Array.map([1, 2, 3], ~f=Result.ok) == [Ok(1), Ok(2), Ok(3)] + Array.map([1, 2, 3], ~f=Result.ok) == [Ok(1), Ok(2), Ok(3)] - let numbers = [1, 2, 3] - Result.attempt(() => numbers[3]) // returns Error(Assert_failure) - ]} -") + let numbers = [1, 2, 3] + Result.attempt(() => numbers[3]) // returns Error(Assert_failure) + ``` +*/ let attempt: (unit => 'ok) => t<'ok, exn> -@ocaml.doc(" Convert an {!Option} to a {!Result} where a [Some(value)] becomes [Ok(value)] and a [None] becomes [Error(error)]. +/** Convert an [Option](Option.mdx#) to a [Result](Result.mdx#) where a `Some(value)` becomes `Ok(value)` and a `None` becomes `Error(error)`. - {2 Examples} + ## Examples - {[ - Result.fromOption(Some(84), ~error=\"Greater than 100\") == Ok(84) + ```rescript + Result.fromOption(Some(84), ~error="Greater than 100") == Ok(84) - Result.fromOption(None, ~error=\"Greater than 100\") == Error(\"Greater than 100\") - ]} -") + Result.fromOption(None, ~error="Greater than 100") == Error("Greater than 100") + ``` +*/ let fromOption: (option<'ok>, ~error: 'error) => t<'ok, 'error> -@ocaml.doc(" Check if a {!Result} is an [Ok]. +/** Check if a [Result](Result.mdx#) is an `Ok`. - Useful when you want to perform some side effect based on the presence of - an [Ok] like logging. + Useful when you want to perform some side effect based on the presence of + an `Ok` like logging. - {b Note} if you need access to the contained value rather than doing - [Result.isOk] followed by {!Result.unwrapUnsafe} its safer and just as - convenient to use pattern matching directly or use one of {!Result.andThen} - or {!Result.map} + *Note:* if you need access to the contained value rather than doing + `Result.isOk` followed by [Result.unwrapUnsafe](Result.mdx#unwrapUnsafe) its safer and just as + convenient to use pattern matching directly or use one of [Result.andThen](Result.mdx#andThen) + or [Result.map](Result.mdx#map) - {2 Examples} + ## Examples - {[ - Result.isOk(Ok(3)) == true - Result.isOk(Error(3)) == false - ]} -") + ```rescript + Result.isOk(Ok(3)) == true + Result.isOk(Error(3)) == false + ``` +*/ let isOk: t<_, _> => bool -@ocaml.doc(" Check if a {!Result} is an [Error]. +/** Check if a [Result](Result.mdx#) is an `Error`. - Useful when you want to perform some side effect based on the presence of - an [Error] like logging. + Useful when you want to perform some side effect based on the presence of + an `Error` like logging. - {b Note} if you need access to the contained value rather than doing - {!Result.isOk} followed by {!Result.unwrapUnsafe} its safer and just as - convenient to use pattern matching directly or use one of {!Result.andThen} - or {!Result.map} + *Note:* if you need access to the contained value rather than doing + [Result.isOk](Result.mdx#isOk) followed by [Result.unwrapUnsafe](Result.mdx#unwrapUnsafe) its safer and just as + convenient to use pattern matching directly or use one of [Result.andThen](Result.mdx#andThen) + or [Result.map](Result.mdx#map) - {2 Examples} + ## Examples - {[ - Result.isError(Ok(3)) == false - Result.isError(Error(3)) == true - ]} -") + ```rescript + Result.isError(Ok(3)) == false + Result.isError(Error(3)) == true + ``` +*/ let isError: t<_, _> => bool -@ocaml.doc(" Returns the first argument if it {!isError}, otherwise return the second argument. +/** Returns the first argument if it [isError](#isError), otherwise return the second argument. - Unlike the {!Bool.and_} operator, the [and_] function does not short-circuit. - When you call [and_], both arguments are evaluated before being passed to the function. + Unlike the [Bool.and_](Bool.mdx#and_) operator, the `and_` function does not short-circuit. + When you call `and_`, both arguments are evaluated before being passed to the function. - {2 Examples} + ## Examples - {[ - Result.and_(Ok(\"Antelope\"), Ok(\"Salmon\")) == Ok(\"Salmon\") + ```rescript + Result.and_(Ok("Antelope"), Ok("Salmon")) == Ok("Salmon") - Result.and_(Error(#UnexpectedBird(\"Finch\")), Ok(\"Salmon\")) - == Error(#UnexpectedBird(\"Finch\")) + Result.and_(Error(#UnexpectedBird("Finch")), Ok("Salmon")) + == Error(#UnexpectedBird("Finch")) - Result.and_(Ok(\"Antelope\"), Error(#UnexpectedBird(\"Finch\"))) - == Error(#UnexpectedBird(\"Finch\")) + Result.and_(Ok("Antelope"), Error(#UnexpectedBird("Finch"))) + == Error(#UnexpectedBird("Finch")) - Result.and_(Error(#UnexpectedInvertebrate(\"Honey Bee\")), Error(#UnexpectedBird(\"Finch\"))) - == Error(#UnexpectedInvertebrate(\"Honey Bee\")) - ]} -") + Result.and_(Error(#UnexpectedInvertebrate("Honey Bee")), Error(#UnexpectedBird("Finch"))) + == Error(#UnexpectedInvertebrate("Honey Bee")) + ``` +*/ let and_: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> -@ocaml.doc(" Return the first argument if it {!isOk}, otherwise return the second. +/** Return the first argument if it [isOk](#isOk), otherwise return the second. - Unlike the built in [||] operator, the [or_] function does not short-circuit. - When you call [or_], both arguments are evaluated before being passed to the function. + Unlike the built in `||` operator, the `or_` function does not short-circuit. + When you call `or_`, both arguments are evaluated before being passed to the function. - {2 Examples} + ## Examples - {[ - Result.or_(Ok(\"Boar\"), Ok(\"Gecko\")) == Ok(\"Boar\") - Result.or_(Error(#UnexpectedInvertebrate(\"Periwinkle\")), Ok(\"Gecko\")) == Ok(\"Gecko\") - Result.or_(Ok(\"Boar\"), Error(#UnexpectedInvertebrate(\"Periwinkle\"))) == Ok(\"Boar\") + ```rescript + Result.or_(Ok("Boar"), Ok("Gecko")) == Ok("Boar") + Result.or_(Error(#UnexpectedInvertebrate("Periwinkle")), Ok("Gecko")) == Ok("Gecko") + Result.or_(Ok("Boar"), Error(#UnexpectedInvertebrate("Periwinkle"))) == Ok("Boar") - Result.or_(Error(#UnexpectedInvertebrate(\"Periwinkle\")), Error(#UnexpectedBird(\"Robin\"))) - == Error(#UnexpectedBird(\"Robin\")) - ]} -") + Result.or_(Error(#UnexpectedInvertebrate("Periwinkle")), Error(#UnexpectedBird("Robin"))) + == Error(#UnexpectedBird("Robin")) + ``` +*/ let or_: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> -@ocaml.doc(" Return the second argument if it {!isOk}, otherwise return the first. +/** Return the second argument if it [isOk](#isOk), otherwise return the first. - Like {!or_} but in reverse. Useful when using the [|>] operator + Like [or_](#or_) but in reverse. Useful when using the `|>` operator - {2 Examples} + ## Examples - {[Result.orElse (Ok \"Boar\") (Ok \"Gecko\") = (Ok \"Gecko\")]} + ```rescript + Result.orElse (Ok "Boar") (Ok "Gecko") = (Ok "Gecko") + ``` - {[Result.orElse (Error (`UnexpectedInvertabrate \"Periwinkle\")) (Ok \"Gecko\") = (Ok \"Gecko\")]} + ```rescript + Result.orElse (Error (`UnexpectedInvertabrate "Periwinkle")) (Ok "Gecko") = (Ok "Gecko") + ``` - {[Result.orElse (Ok \"Boar\") (Error (`UnexpectedInvertabrate \"Periwinkle\")) = (Ok \"Boar\") ]} + ```rescript + Result.orElse (Ok "Boar") (Error (`UnexpectedInvertabrate "Periwinkle")) = (Ok "Boar") + ``` - {[Result.orElse (Error (`UnexpectedInvertabrate \"Periwinkle\")) (Error (`UnexpectedBird \"Robin\")) = (Error (`UnexpectedInvertabrate \"Periwinkle\"))]} -") + ```rescript + Result.orElse (Error (`UnexpectedInvertabrate "Periwinkle")) (Error (`UnexpectedBird "Robin")) = (Error (`UnexpectedInvertabrate "Periwinkle")) + ``` +*/ let orElse: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> let or_else: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> -@ocaml.doc(" Combine two results, if both are [Ok] returns an [Ok] containing a {!Tuple2} of the values. +/** Combine two results, if both are `Ok` returns an `Ok` containing a [Tuple2](Tuple2.mdx#) of the values. - If either is an [Error], returns the first [Error]. + If either is an `Error`, returns the first `Error`. - The same as writing [Result.map2(~f=Tuple2.make)]. + The same as writing `Result.map2(~f=Tuple2.make)`. - {2 Examples} + ## Examples - {[ - Result.both(Ok(\"Badger\"), Ok(\"Rhino\")) == Ok(\"Dog\", \"Rhino\") + ```rescript + Result.both(Ok("Badger"), Ok("Rhino")) == Ok("Dog", "Rhino") - Result.both(Error(#UnexpectedBird(\"Flamingo\")), Ok(\"Rhino\")) - == Error(#UnexpectedBird(\"Flamingo\")) + Result.both(Error(#UnexpectedBird("Flamingo")), Ok("Rhino")) + == Error(#UnexpectedBird("Flamingo")) - Result.both(Ok(\"Badger\"), Error(#UnexpectedInvertebrate(\"Blue ringed octopus\"))) - == Error(#UnexpectedInvertebrate(\"Blue ringed octopus\")) + Result.both(Ok("Badger"), Error(#UnexpectedInvertebrate("Blue ringed octopus"))) + == Error(#UnexpectedInvertebrate("Blue ringed octopus")) - Result.both( - Error(#UnexpectedBird(\"Flamingo\")), - Error(#UnexpectedInvertebrate(\"Blue ringed octopus\")), - ) == Error(#UnexpectedBird(\"Flamingo\")) - ]} -") + Result.both( + Error(#UnexpectedBird("Flamingo")), + Error(#UnexpectedInvertebrate("Blue ringed octopus")), + ) == Error(#UnexpectedBird("Flamingo")) + ``` +*/ let both: (t<'a, 'error>, t<'b, 'error>) => t<('a, 'b), 'error> -@ocaml.doc(" Collapse a nested result, removing one layer of nesting. +/** Collapse a nested result, removing one layer of nesting. - {2 Examples} + ## Examples - {[ - Result.flatten(Ok(Ok(2))) == Ok(2) + ```rescript + Result.flatten(Ok(Ok(2))) == Ok(2) - Result.flatten(Ok(Error(#UnexpectedBird(\"Peregrin falcon\")))) - == Error(#UnexpectedBird(\"Peregrin falcon\")) + Result.flatten(Ok(Error(#UnexpectedBird("Peregrin falcon")))) + == Error(#UnexpectedBird("Peregrin falcon")) - Result.flatten(Error(#UnexpectedInvertebrate(\"Woodlouse\"))) - == Error(#UnexpectedInvertebrate(\"Woodlouse\")) - ]} -") + Result.flatten(Error(#UnexpectedInvertebrate("Woodlouse"))) + == Error(#UnexpectedInvertebrate("Woodlouse")) + ``` +*/ let flatten: t, 'error> => t<'ok, 'error> -@ocaml.doc(" Unwrap a Result using the [~default] value in case of an [Error]. +/** Unwrap a Result using the `~default` value in case of an `Error`. - {2 Examples} + ## Examples - {[ - Result.unwrap(Ok(12), ~default=0) == 12 - Result.unwrap(Error(#UnexpectedBird(\"Ostrich\")), ~default=0) == 0 - ]} -") + ```rescript + Result.unwrap(Ok(12), ~default=0) == 12 + Result.unwrap(Error(#UnexpectedBird("Ostrich")), ~default=0) == 0 + ``` +*/ let unwrap: (t<'ok, 'error>, ~default: 'ok) => 'ok -@ocaml.doc(" Unwrap a Result using the [Lazy.force default] value in case of an [Error] +/** Unwrap a Result using the `Lazy.force(default)` value in case of an `Error` - {2 Examples} + ## Examples - {[Result.unwrapLazy ~default:(lazy 0) (Ok 12) = 12]} + ```rescript + Result.unwrapLazy ~default:(lazy 0) (Ok 12) = 12 + ``` - {[Result.unwrapLazy ~default:(lazy 0) ((Error (`UnexpectedBird \"Ostrich\"))) = 0]} -") + ```rescript + Result.unwrapLazy ~default:(lazy 0) ((Error (`UnexpectedBird "Ostrich"))) = 0 + ``` +*/ let unwrapLazy: (t<'ok, 'error>, ~default: Lazy.t<'ok>) => 'ok -@ocaml.doc(" Unwrap a Result, raising an exception in case of an [Error]. +/** Unwrap a Result, raising an exception in case of an `Error`. - {3 Exceptions} + ### Exceptions - Raises an [Not_found] exception. + Raises an `Not_found` exception. - {2 Examples} + ## Examples - {[ - Result.unwrapUnsafe(Ok(12)) == 12 - Result.unwrapUnsafe(Error(\"bad\")) // raises Not_found - ]} -") + ```rescript + Result.unwrapUnsafe(Ok(12)) == 12 + Result.unwrapUnsafe(Error("bad")) // raises Not_found + ``` +*/ let unwrapUnsafe: t<'ok, _> => 'ok -@ocaml.doc(" Like {!Result.unwrap} but unwraps an [Error] value instead. +/** Like [Result.unwrap](Result.mdx#unwrap) but unwraps an `Error` value instead. - {2 Examples} + ## Examples - {[ - Result.unwrapError( - Error(#UnexpectedBird(\"Swallow\")), - ~default=#UnexpectedInvertebrate(\"Ladybird\"), - ) == #UnexpectedBird(\"Swallow\") + ```rescript + Result.unwrapError( + Error(#UnexpectedBird("Swallow")), + ~default=#UnexpectedInvertebrate("Ladybird"), + ) == #UnexpectedBird("Swallow") - Result.unwrapError(Ok(5), ~default=#UnexpectedInvertebrate(\"Ladybird\")) - == #UnexpectedInvertebrate(\"Ladybird\") - ]} -") + Result.unwrapError(Ok(5), ~default=#UnexpectedInvertebrate("Ladybird")) + == #UnexpectedInvertebrate("Ladybird") + ``` +*/ let unwrapError: (t<'ok, 'error>, ~default: 'error) => 'error -@ocaml.doc(" Combine two Results. +/** Combine two Results. - If one of the results is an [Error], that becomes the return result. + If one of the results is an `Error`, that becomes the return result. - If both are [Error] values, returns its first. + If both are `Error` values, returns its first. - {2 Examples} + ## Examples - {[ - Result.map2(Ok(7), Ok(3), ~f=Int.add) == Ok(10) - Result.map2(Error(\"A\"), Ok(3), ~f=Int.add) == Error(\"A\") - Result.map2(Ok(7), Error(\"B\"), ~f=Int.add) == Error(\"B\") - Result.map2(Error(\"A\"), Error(\"B\"), ~f=Int.add) == Error(\"A\") - ]} -") + ```rescript + Result.map2(Ok(7), Ok(3), ~f=Int.add) == Ok(10) + Result.map2(Error("A"), Ok(3), ~f=Int.add) == Error("A") + Result.map2(Ok(7), Error("B"), ~f=Int.add) == Error("B") + Result.map2(Error("A"), Error("B"), ~f=Int.add) == Error("A") + ``` +*/ let map2: (t<'a, 'error>, t<'b, 'error>, ~f: ('a, 'b) => 'c) => t<'c, 'error> -@ocaml.doc(" If all of the elements of a list are [Ok], returns an [Ok] of the the list of unwrapped values. +/** If all of the elements of a list are `Ok`, returns an `Ok` of the the list of unwrapped values. - If {b any} of the elements are an [Error], the first one encountered is returned. + If *any* of the elements are an `Error`, the first one encountered is returned. - {2 Examples} + ## Examples - {[ - Result.values(list{Ok(1), Ok(2), Ok(3), Ok(4)}) == Ok(list{1, 2, 3, 4}) - Result.values(list{Ok(1), Error(\"two\"), Ok(3), Error(\"four\")}) == Error(\"two\") - ]} -") + ```rescript + Result.values(list{Ok(1), Ok(2), Ok(3), Ok(4)}) == Ok(list{1, 2, 3, 4}) + Result.values(list{Ok(1), Error("two"), Ok(3), Error("four")}) == Error("two") + ``` +*/ let values: list> => t, 'error> -@ocaml.doc(" - [Result.combine(results)] takes a list of [Result] values. If all - the elements in [results] are of the form [Ok x], then [Result.combine] - creates a list [xs] of all the values extracted from their [Ok]s, and returns - [Ok xs] +/** + `Result.combine(results)` takes a list of [Result](Result.mdx#) values. If all + the elements in `results` are of the form `Ok x`, then [Result.combine] + creates a list `xs` of all the values extracted from their `Ok`s, and returns + `Ok(xs)` - If any of the elements in [results] are of the form [Error err], - the first of them is returned as the result of [Result.combine]. + If any of the elements in `results` are of the form `Error(err)`, + the first of them is returned as the result of `Result.combine`. - {2 Examples} + ## Examples - {[ - Result.combine(list{Ok(1), Ok(2), Ok(3), Ok(4)}) == Ok(list{1, 2, 3, 4}) - Result.combine(list{Ok(1), Error(\"two\"), Ok(3), Error(\"four\")}) == Error(\"two\") - ]} - ") + ```rescript + Result.combine(list{Ok(1), Ok(2), Ok(3), Ok(4)}) == Ok(list{1, 2, 3, 4}) + Result.combine(list{Ok(1), Error("two"), Ok(3), Error("four")}) == Error("two") + ``` + */ let combine: list> => result, 'error> -@ocaml.doc(" Transforms the ['ok] in a result using [f]. Leaves the ['error] untouched. +/** Transforms the `'ok` in a result using `f`. Leaves the `'error` untouched. - {2 Examples} + ## Examples - {[ - Result.map(Ok(3), ~f=Int.add(1)) == Ok(9) - Result.map(Error(\"three\"), ~f=Int.add(1)) == Error(\"three\") - ]} -") + ```rescript + Result.map(Ok(3), ~f=Int.add(1)) == Ok(9) + Result.map(Error("three"), ~f=Int.add(1)) == Error("three") + ``` +*/ let map: (t<'a, 'error>, ~f: 'a => 'b) => t<'b, 'error> -@ocaml.doc(" Transforms the value in an [Error] using [f]. Leaves an [Ok] untouched. +/** Transforms the value in an `Error` using `f`. Leaves an `Ok` untouched. - {2 Examples} + ## Examples - {[ - Result.mapError(Ok(3), ~f=String.reverse) == Ok(3) - Result.mapError(Error(\"bad\"), ~f=String.reverse) == Error(\"dab\") - ]} -") + ```rescript + Result.mapError(Ok(3), ~f=String.reverse) == Ok(3) + Result.mapError(Error("bad"), ~f=String.reverse) == Error("dab") + ``` +*/ let mapError: (t<'ok, 'a>, ~f: 'a => 'b) => t<'ok, 'b> -@ocaml.doc(" Run a function which may fail on a result. - - Short-circuits of called with an [Error]. - - {2 Examples} - - {[ - let reciprical = (x: float): Result.t => - if x == 0.0 { - Error(\"Divide by zero\") - } else { - Ok(1.0 /. x) - } - - let root = (x: float): Result.t => - if x < 0.0 { - Error(\"Cannot be negative\") - } else { - Ok(Float.squareRoot(x)) - } - - Result.andThen(Ok(4.0), ~f=reciprical) == Ok(0.25) - Result.andThen(Error(\"Missing number!\"), ~f=reciprical) == Error(\"Missing number!\") - Result.andThen(Ok(0.0), ~f=reciprical) == Error(\"Divide by zero\") - Result.andThen(Ok(4.0), ~f=root)->Result.andThen(~f=reciprical) == Ok(0.5) - Result.andThen(Ok(-2.0), ~f=root)->Result.andThen(~f=reciprical) == Error(\"Cannot be negative\") - Result.andThen(Ok(0.0), ~f=root)->Result.andThen(~f=reciprical) == Error(\"Divide by zero\") - ]} -") +/** Run a function which may fail on a result. + + Short-circuits of called with an `Error`. + + ## Examples + + ```rescript + let reciprical = (x: float): Result.t => + if x == 0.0 { + Error("Divide by zero") + } else { + Ok(1.0 /. x) + } + + let root = (x: float): Result.t => + if x < 0.0 { + Error("Cannot be negative") + } else { + Ok(Float.squareRoot(x)) + } + + Result.andThen(Ok(4.0), ~f=reciprical) == Ok(0.25) + Result.andThen(Error("Missing number!"), ~f=reciprical) == Error("Missing number!") + Result.andThen(Ok(0.0), ~f=reciprical) == Error("Divide by zero") + Result.andThen(Ok(4.0), ~f=root)->Result.andThen(~f=reciprical) == Ok(0.5) + Result.andThen(Ok(-2.0), ~f=root)->Result.andThen(~f=reciprical) == Error("Cannot be negative") + Result.andThen(Ok(0.0), ~f=root)->Result.andThen(~f=reciprical) == Error("Divide by zero") + ``` +*/ let andThen: (t<'a, 'error>, ~f: 'a => t<'b, 'error>) => t<'b, 'error> -@ocaml.doc(" Run a function against an [Ok(value)], ignores [Error]s. +/** Run a function against an `Ok(value)`, ignores `Error`s. - {2 Examples} + ## Examples - {[ - Result.tap(Ok(\"Dog\"), ~f=Js.log) - (* logs \"Dog\" *) - ]} - ") + ```rescript + Result.tap(Ok("Dog"), ~f=Js.log) + (* logs "Dog" *) + ``` + */ let tap: (t<'ok, _>, ~f: 'ok => unit) => unit -@@ocaml.text(" {1 Convert} ") +/** Convert a [Result](Result.mdx#) to an [Option](Option.mdx#). -@ocaml.doc(" Convert a {!Result} to an {!Option}. + An `Ok(x)` becomes `Some(x)` - An [Ok x] becomes [Some x] + An `Error(_)` becomes `None` - An [Error _] becomes [None] + ## Examples - {2 Examples} - - {[ - Result.toOption(Ok(42)) == Some(42) - Result.toOption(Error(\"Missing number!\")) == None - ]} -") + ```rescript + Result.toOption(Ok(42)) == Some(42) + Result.toOption(Error("Missing number!")) == None + ``` +*/ let toOption: t<'ok, _> => option<'ok> -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two results for equality using the provided functions. +/** Test two results for equality using the provided functions. - {2 Examples} + ## Examples - {[ - Result.equal(Ok(3), Ok(3), Int.equal, String.equal) == true - Result.equal(Ok(3), Ok(4), Int.equal, String.equal) == false - Result.equal(Error(\"Fail\"), Error(\"Fail\"), Int.equal, String.equal) == true - Result.equal(Error(\"Expected error\"), Error(\"Unexpected error\"), Int.equal, String.equal) == false - Result.equal(Error(\"Fail\"), Ok(4), Int.equal, String.equal) == false - ]} -") + ```rescript + Result.equal(Ok(3), Ok(3), Int.equal, String.equal) == true + Result.equal(Ok(3), Ok(4), Int.equal, String.equal) == false + Result.equal(Error("Fail"), Error("Fail"), Int.equal, String.equal) == true + Result.equal(Error("Expected error"), Error("Unexpected error"), Int.equal, String.equal) == false + Result.equal(Error("Fail"), Ok(4), Int.equal, String.equal) == false + ``` +*/ let equal: (t<'ok, 'error>, t<'ok, 'error>, ('ok, 'ok) => bool, ('error, 'error) => bool) => bool -@ocaml.doc(" Compare results for using the provided functions. - [f] will be used to compare [Ok]'s and [g] will be used on [Error]s. +/** Compare results for using the provided functions. + `f` will be used to compare `Ok`'s and `g` will be used on `Error`s. - In the case when one of the results is an [Error] and one is [Ok], [Error]s are considered 'less' then [Ok]s. + In the case when one of the results is an `Error` and one is `Ok`, `Error`s are considered 'less' then `Ok`s. - {2 Examples} + ## Examples - {[ - Result.compare(Ok(3), Ok(3), ~f=Int.compare, ~g=String.compare) == 0 - Result.compare(Ok(3), Ok(4), ~f=Int.compare, ~g=String.compare) == -1 - Result.compare(Error(\"Fail\"), Error(\"Fail\"), ~f=Int.compare, ~g=String.compare) == 0 - Result.compare(Error(\"Fail\"), Ok(4), ~f=Int.compare, ~g=String.compare) == -1 - Result.compare(Ok(4), Error(\"Fail\"), ~f=Int.compare, ~g=String.compare) == 1 + ```rescript + Result.compare(Ok(3), Ok(3), ~f=Int.compare, ~g=String.compare) == 0 + Result.compare(Ok(3), Ok(4), ~f=Int.compare, ~g=String.compare) == -1 + Result.compare(Error("Fail"), Error("Fail"), ~f=Int.compare, ~g=String.compare) == 0 + Result.compare(Error("Fail"), Ok(4), ~f=Int.compare, ~g=String.compare) == -1 + Result.compare(Ok(4), Error("Fail"), ~f=Int.compare, ~g=String.compare) == 1 - Result.compare( - Error(\"Expected error\"), - Error(\"Unexpected error\"), - ~f=Int.compare, - ~g=String.compare - ) == -1 - ]} -") + Result.compare( + Error("Expected error"), + Error("Unexpected error"), + ~f=Int.compare, + ~g=String.compare + ) == -1 + ``` +*/ let compare: ( t<'ok, 'error>, t<'ok, 'error>, ~f: ('ok, 'ok) => int, ~g: ('error, 'error) => int, ) => int - diff --git a/src/TableclothSet.resi b/src/TableclothSet.resi index 8b44f13..ce44c6f 100644 --- a/src/TableclothSet.resi +++ b/src/TableclothSet.resi @@ -1,403 +1,384 @@ -@@ocaml.text(" ") +/** A [Set](Set.mdx#) represents a collection of unique values. -@@ocaml.text(" A {!Set} represents a collection of unique values. + `Set` is an immutable data structure which means operations like [Set.add](Set.mdx#add) and [Set.remove](Set.mdx#remove) do not modify the data structure, but return a new set with the desired changes. - [Set] is an immutable data structure which means operations like {!Set.add} and {!Set.remove} do not modify the data structure, but return a new set with the desired changes. + Since sets of `int`s and `string`s are so common the specialised [Set.Int](Set.mdx#Int) and [Set.String](Set.mdx#String) modules are available which offer a convenient way to construct new sets. - Since sets of [int]s and [string]s are so common the specialised {!Set.Int} and {!Set.String} modules are available which offer a convenient way to construct new sets. + You can create a Set by providing a module conform to the [Comparator.S](Comparator.mdx#S) signature by using [empty](#empty), [singleton](#singleton), [fromList](#fromList) or [fromArray](#fromArray). - Custom data types can be used with sets as long as the module satisfies the {!Comparator.S} interface. + Specialised versions of the [empty](#empty), [singleton](#singleton), [fromList](#fromList) and [fromArray](#fromArray) functions available in the [Set.Int](Set.mdx#Int) and [Set.String](Set.mdx#String) sub-modules. - {[ - module Point = { - type rec t = (int, int) - let compare = Tuple2.compare(~f=Int.compare, ~g=Int.compare) - include Comparator.Make({ - type t = t - let compare = compare - }) - } + Custom data types can be used with sets as long as the module satisfies the [Comparator.S](Comparator.mdx#S) interface. - let points = Set.fromArray(module(Point), [(0, 0), (3, 4), (6, 7)]) - ]} + ```rescript + module Point = { + type rec t = (int, int) + let compare = Tuple2.compare(~f=Int.compare, ~g=Int.compare) + include Comparator.Make({ + type t = t + let compare = compare + }) + } - See the {!Comparator} module for a more details. -") + let points = Set.fromArray(module(Point), [(0, 0), (3, 4), (6, 7)]) + ``` + See the [Comparator](Comparator.mdx#) module for a more details. +*/ type t<'a, 'id> = Belt.Set.t<'a, 'id> -@@ocaml.text(" {1 Create} - - You can create a Set by providing a module conform to the {!Comparator.S} signature by using {!empty}, {!singleton}, {!fromList} or {!fromArray}. - - Specialised versions of the {!empty}, {!singleton}, {!fromList} and {!fromArray} functions available in the {!Set.Int} and {!Set.String} sub-modules. -") - -@ocaml.doc(" A set with nothing in it. +/** A set with nothing in it. - Often used as an initial value for functions like {!Array.fold} + Often used as an initial value for functions like [Array.fold](Array.mdx#fold) - {2 Examples} + ## Examples - {[ - Array.fold( - ['m', 'i', 's', 's', 'i', 's', 's', 'i', 'p', 'p', 'i'], - ~initial=Set.empty(module(Char)), - ~f=Set.add, - )->Set.toArray - == ['i', 'm', 'p', 's'] - ]} -") + ```rescript + Array.fold( + ['m', 'i', 's', 's', 'i', 's', 's', 'i', 'p', 'p', 'i'], + ~initial=Set.empty(module(Char)), + ~f=Set.add, + )->Set.toArray + == ['i', 'm', 'p', 's'] + ``` +*/ let empty: TableclothComparator.s<'a, 'identity> => t<'a, 'identity> -@ocaml.doc(" Create a set from a single {!Int}. +/** Create a set from a single [Int](#Int). - {2 Examples} + ## Examples - {[ - Set.singleton(7, module(Int)) |> Set.toArray == [7] - ]} -") + ```rescript + Set.singleton(7, module(Int)) |> Set.toArray == [7] + ``` +*/ let singleton: ('a, TableclothComparator.s<'a, 'identity>) => t<'a, 'identity> -@ocaml.doc(" Create a set from an {!Array}. +/** Create a set from an [Array](#Array). - {2 Examples} + ## Examples - {[ - Set.fromArray([\"Ant\", \"Bat\", \"Bat\", \"Goldfish\"], module(String))->Set.toArray - == [\"Ant\", \"Bat\", \"Goldfish\"] - ]} -") + ```rescript + Set.fromArray(["Ant", "Bat", "Bat", "Goldfish"], module(String))->Set.toArray + == ["Ant", "Bat", "Goldfish"] + ``` +*/ let fromArray: (array<'a>, TableclothComparator.s<'a, 'identity>) => t<'a, 'identity> -@ocaml.doc(" Create a set from a {!List}. +/** Create a set from a [List](List.mdx#). - {2 Examples} + ## Examples - {[ - Set.fromList(list{'A', 'B', 'B', 'G'}, module(Char))->Set.toArray == ['A', 'B', 'G'] - ]} -") + ```rescript + Set.fromList(list{'A', 'B', 'B', 'G'}, module(Char))->Set.toArray == ['A', 'B', 'G'] + ``` +*/ let fromList: (list<'a>, TableclothComparator.s<'a, 'identity>) => t<'a, 'identity> -@@ocaml.text(" {1 Basic operations} ") +/** Insert a value into a set. -@ocaml.doc(" Insert a value into a set. + ## Examples - {2 Examples} - - {[ - Set.add(Set.Int.fromArray([1, 2]), 3) -> Set.toArray == [1, 2, 3] - Set.add(Set.Int.fromArray([1, 2]), 2) -> Set.toArray == [1, 2] - ]} -") + ```rescript + Set.add(Set.Int.fromArray([1, 2]), 3) -> Set.toArray == [1, 2, 3] + Set.add(Set.Int.fromArray([1, 2]), 2) -> Set.toArray == [1, 2] + ``` +*/ let add: (t<'a, 'id>, 'a) => t<'a, 'id> -@ocaml.doc(" Remove a value from a set, if the set doesn't contain the value anyway, returns the original set. +/** Remove a value from a set, if the set doesn't contain the value anyway, returns the original set. - {2 Examples} + ## Examples - {[ - Set.remove(Set.Int.fromArray([1, 2]), 2)->Set.toArray == [1] - - let originalSet = Set.Int.fromArray([1, 2]) - let newSet = Set.remove(originalSet, 3) - originalSet == newSet - ]} -") + ```rescript + Set.remove(Set.Int.fromArray([1, 2]), 2)->Set.toArray == [1] + + let originalSet = Set.Int.fromArray([1, 2]) + let newSet = Set.remove(originalSet, 3) + originalSet == newSet + ``` +*/ let remove: (t<'a, 'id>, 'a) => t<'a, 'id> -@ocaml.doc(" Determine if a value is in a set. +/** Determine if a value is in a set. - {2 Examples} + ## Examples - {[ - Set.includes(Set.String.fromArray([\"Ant\", \"Bat\", \"Cat\"]), \"Bat\") == true - ]} -") + ```rescript + Set.includes(Set.String.fromArray(["Ant", "Bat", "Cat"]), "Bat") == true + ``` +*/ let includes: (t<'a, _>, 'a) => bool -@ocaml.doc(" Determine the number of elements in a set. +/** Determine the number of elements in a set. - {2 Examples} + ## Examples - {[ - Set.length(Set.Int.fromArray([1, 2, 3])) == 3 - ]} -") + ```rescript + Set.length(Set.Int.fromArray([1, 2, 3])) == 3 + ``` +*/ let length: t<_, _> => int -@ocaml.doc(" Returns, as an {!Option}, the first element for which [f] evaluates to [true]. - If [f] doesn't return [true] for any of the elements [find] will return [None]. +/** Returns, as an [Option](Option.mdx#), the first element for which `f` evaluates to `true`. + If `f` doesn't return `true` for any of the elements `find` will return `None`. - {2 Examples} + ## Examples - {[ - Set.find(Set.Int.fromArray([1, 3, 4, 8]), ~f=Int.isEven) == Some(4) - Set.find(Set.Int.fromArray([0, 2, 4, 8]), ~f=Int.isOdd) == None - Set.find(Set.Int.empty, ~f=Int.isEven) == None - ]} -") + ```rescript + Set.find(Set.Int.fromArray([1, 3, 4, 8]), ~f=Int.isEven) == Some(4) + Set.find(Set.Int.fromArray([0, 2, 4, 8]), ~f=Int.isOdd) == None + Set.find(Set.Int.empty, ~f=Int.isEven) == None + ``` +*/ let find: (t<'value, _>, ~f: 'value => bool) => option<'value> -@@ocaml.text(" {1 Query} ") +/** Check if a set is empty. -@ocaml.doc(" Check if a set is empty. + ## Examples - {2 Examples} - - {[ - Set.isEmpty(Set.Int.empty) == true - Set.isEmpty(Set.Int.singleton(4)) == false - ]} -") + ```rescript + Set.isEmpty(Set.Int.empty) == true + Set.isEmpty(Set.Int.singleton(4)) == false + ``` +*/ let isEmpty: t<_, _> => bool -@ocaml.doc(" Determine if [f] returns true for [any] values in a set. +/** Determine if `f` returns true for `any` values in a set. - {2 Examples} + ## Examples - {[ - Set.any(Set.Int.fromArray([2, 3]), ~f=Int.isEven) == true - Set.any(Set.Int.fromArray([1, 3]), ~f=Int.isEven) == false - Set.any(Set.Int.fromArray([]), ~f=Int.isEven) == false - ]} -") + ```rescript + Set.any(Set.Int.fromArray([2, 3]), ~f=Int.isEven) == true + Set.any(Set.Int.fromArray([1, 3]), ~f=Int.isEven) == false + Set.any(Set.Int.fromArray([]), ~f=Int.isEven) == false + ``` +*/ let any: (t<'value, _>, ~f: 'value => bool) => bool -@ocaml.doc(" Determine if [f] returns true for [all] values in a set. +/** Determine if `f` returns true for `all` values in a set. - {2 Examples} + ## Examples - {[ - Set.all(Set.Int.fromArray([2, 4]), ~f=Int.isEven) == true - Set.all(Set.Int.fromArray([2, 3]), ~f=Int.isEven) == false - Set.all(Set.Int.empty, ~f=Int.isEven) == true - ]} -") + ```rescript + Set.all(Set.Int.fromArray([2, 4]), ~f=Int.isEven) == true + Set.all(Set.Int.fromArray([2, 3]), ~f=Int.isEven) == false + Set.all(Set.Int.empty, ~f=Int.isEven) == true + ``` +*/ let all: (t<'value, _>, ~f: 'value => bool) => bool -@@ocaml.text(" {1 Combine} ") - -@ocaml.doc(" Returns a new set with the values from the first set which are not in the second set. +/** Returns a new set with the values from the first set which are not in the second set. - {2 Examples} + ## Examples - {[ - Set.difference( - Set.Int.fromArray([1, 2, 5]), - Set.Int.fromArray([2, 3, 4]) - )->Set.toArray == [1, 5] + ```rescript + Set.difference( + Set.Int.fromArray([1, 2, 5]), + Set.Int.fromArray([2, 3, 4]) + )->Set.toArray == [1, 5] - Set.difference( - Set.Int.fromArray([2, 3, 4]), - Set.Int.fromArray([1, 2, 5]) - )->Set.toArray == [3, 4] - ]} -") + Set.difference( + Set.Int.fromArray([2, 3, 4]), + Set.Int.fromArray([1, 2, 5]) + )->Set.toArray == [3, 4] + ``` +*/ let difference: (t<'a, 'id>, t<'a, 'id>) => t<'a, 'id> -@ocaml.doc(" Get the intersection of two sets. Keeps values that appear in both sets. +/** Get the intersection of two sets. Keeps values that appear in both sets. - {2 Examples} + ## Examples - {[ - Set.intersection( - Set.Int.fromArray([1, 2, 5]), - Set.Int.fromArray([2, 3, 4]) - )->Set.toArray == [2] - ]} -") + ```rescript + Set.intersection( + Set.Int.fromArray([1, 2, 5]), + Set.Int.fromArray([2, 3, 4]) + )->Set.toArray == [2] + ``` +*/ let intersection: (t<'a, 'id>, t<'a, 'id>) => t<'a, 'id> -@ocaml.doc(" Get the union of two sets. Keep all values. +/** Get the union of two sets. Keep all values. - {2 Examples} + ## Examples - {[ - Set.union( - Set.Int.fromArray([1, 2, 5]), - Set.Int.fromArray([2, 3, 4]) - )->Set.toArray == [1, 2, 3, 4, 5] - ]} -") + ```rescript + Set.union( + Set.Int.fromArray([1, 2, 5]), + Set.Int.fromArray([2, 3, 4]) + )->Set.toArray == [1, 2, 3, 4, 5] + ``` +*/ let union: (t<'a, 'id>, t<'a, 'id>) => t<'a, 'id> -@@ocaml.text(" {1 Transform} ") - -@ocaml.doc(" Keep elements that [f] returns [true] for. +/** Keep elements that `f` returns `true` for. - {2 Examples} + ## Examples - {[ - Set.filter(Set.Int.fromArray([1, 2, 3]), ~f=Int.isEven)->Set.toArray == [2] - ]} -") + ```rescript + Set.filter(Set.Int.fromArray([1, 2, 3]), ~f=Int.isEven)->Set.toArray == [2] + ``` +*/ let filter: (t<'a, 'id>, ~f: 'a => bool) => t<'a, 'id> -@ocaml.doc(" Divide a set into two according to [f]. The first set will contain the values - that [f] returns [true] for, values that [f] returns [false] for will end up in the second. +/** Divide a set into two according to `f`. The first set will contain the values + that `f` returns `true` for, values that `f` returns `false` for will end up in the second. - {2 Examples} + ## Examples - {[ - let numbers = Set.Int.fromArray([1, 1, 5, 6, 5, 7, 9, 8]) - let (evens, odds) = Set.partition(numbers, ~f=Int.isEven) - Set.toArray(evens) == [6, 8] - Set.toArray(odds) == [1, 5, 7, 9] - ]} -") + ```rescript + let numbers = Set.Int.fromArray([1, 1, 5, 6, 5, 7, 9, 8]) + let (evens, odds) = Set.partition(numbers, ~f=Int.isEven) + Set.toArray(evens) == [6, 8] + Set.toArray(odds) == [1, 5, 7, 9] + ``` +*/ let partition: (t<'a, 'id>, ~f: 'a => bool) => (t<'a, 'id>, t<'a, 'id>) -@ocaml.doc(" Transform a set into a value which is result of running each element in the set through [f], - where each successive invocation is supplied the return value of the previous. +/** Transform a set into a value which is result of running each element in the set through `f`, + where each successive invocation is supplied the return value of the previous. - See {!Array.fold} for a more in-depth explanation. + See [Array.fold](Array.mdx#fold) for a more in-depth explanation. - {2 Examples} + ## Examples - {[ - Set.fold(Set.Int.fromArray([1, 2, 3, 4], ~initial=1, ~f=Int.multiply)) == 24 - ]} -") + ```rescript + Set.fold(Set.Int.fromArray([1, 2, 3, 4], ~initial=1, ~f=Int.multiply)) == 24 + ``` +*/ let fold: (t<'a, _>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b -@ocaml.doc(" Runs a function [f] against each element of the set. ") +/** Runs a function `f` against each element of the set. */ let forEach: (t<'a, _>, ~f: 'a => unit) => unit -@@ocaml.text(" {1 Convert} ") - -@ocaml.doc(" Converts a set into an {!Array} ") +/** Converts a set into an [Array](#Array) */ let toArray: t<'a, _> => array<'a> -@ocaml.doc(" Converts a set into a {!List}. ") +/** Converts a set into a [List](List.mdx#). */ let toList: t<'a, _> => list<'a> -@ocaml.doc( - " Construct sets which can hold any data type using the polymorphic [compare] function. " -) +/** Construct sets which can hold any data type using the polymorphic `compare` function. */ module Poly: { type identity type t<'a> = t<'a, identity> - @ocaml.doc(" The empty set. + /** The empty set. - A great starting point. - ") + A great starting point. + */ let empty: unit => t<'a> - @ocaml.doc(" Create a set of a single value + /** Create a set of a single value - {2 Examples} + ## Examples - {[ - Set.Poly.singleton((5, \"Emu\"))->Set.toArray == [(5, \"Emu\")] - ]} - ") + ```rescript + Set.Poly.singleton((5, "Emu"))->Set.toArray == [(5, "Emu")] + ``` + */ let singleton: 'a => t<'a> - @ocaml.doc(" Create a set from an {!Array} + /** Create a set from an [Array](#Array) - {2 Examples} + ## Examples - {[ - Set.Poly.fromArray([(1, \"Ant\"), (2, \"Bat\"), (2, \"Bat\")])->Set.toArray - == [(1, \"Ant\"), (2, \"Bat\")] - ]} - ") + ```rescript + Set.Poly.fromArray([(1, "Ant"), (2, "Bat"), (2, "Bat")])->Set.toArray + == [(1, "Ant"), (2, "Bat")] + ``` + */ let fromArray: array<'a> => t<'a> - @ocaml.doc(" Create a set from a {!List} + /** Create a set from a [List](List.mdx#) - {2 Examples} + ## Examples - {[ - Set.Poly.fromList(list{(1, \"Ant\"), (2, \"Bat\"), (2, \"Bat\")})->Set.toArray - == [(1, \"Ant\"), (2, \"Bat\")] - ]} - ") + ```rescript + Set.Poly.fromList(list{(1, "Ant"), (2, "Bat"), (2, "Bat")})->Set.toArray + == [(1, "Ant"), (2, "Bat")] + ``` + */ let fromList: list<'a> => t<'a> } -@ocaml.doc(" Construct sets of {!Int}s ") +/** Construct sets of [Int](#Int)s */ module Int: { type identity type t = t - @ocaml.doc(" A set with nothing in it. ") + /** A set with nothing in it. */ let empty: t - @ocaml.doc(" Create a set from a single {!Int} + /** Create a set from a single [Int](#Int) - {2 Examples} + ## Examples - {[ - Set.Int.singleton(5)->Set.toArray == [5] - ]} - ") + ```rescript + Set.Int.singleton(5)->Set.toArray == [5] + ``` + */ let singleton: int => t - @ocaml.doc(" Create a set from an {!Array} + /** Create a set from an [Array](Array.mdx#) - {2 Examples} + ## Examples - {[ - Set.Int.fromArray([1, 2, 3, 3, 2, 1, 7])->Set.toArray == [1, 2, 3, 7] - ]} - ") + ```rescript + Set.Int.fromArray([1, 2, 3, 3, 2, 1, 7])->Set.toArray == [1, 2, 3, 7] + ``` + */ let fromArray: array => t - @ocaml.doc(" Create a set from a {!List} + /** Create a set from a [List](List.mdx#) - {2 Examples} + ## Examples - {[ - Set.Int.fromList(list{1, 2, 3, 3, 2, 1, 7})->Set.toArray == [1, 2, 3, 7] - ]} - ") + ```rescript + Set.Int.fromList(list{1, 2, 3, 3, 2, 1, 7})->Set.toArray == [1, 2, 3, 7] + ``` + */ let fromList: list => t } -@ocaml.doc(" Construct sets of {!String}s ") +/** Construct sets of [String](String.mdx#)s */ module String: { type identity type t = t - @ocaml.doc(" A set with nothing in it. ") + /** A set with nothing in it. */ let empty: t - @ocaml.doc(" Create a set of a single {!String}. + /** Create a set of a single [String](String.mdx#). - {2 Examples} + ## Examples - {[ - Set.String.singleton(\"Bat\")->Set.toArray == [\"Bat\"] - ]} - ") + ```rescript + Set.String.singleton("Bat")->Set.toArray == ["Bat"] + ``` + */ let singleton: string => t - @ocaml.doc(" Create a set from an {!Array}. + /** Create a set from an [Array](Array.mdx#). - {2 Examples} + ## Examples - {[ - Set.String.fromArray([\"a\", \"b\", \"g\", \"b\", \"g\", \"a\", \"a\"])->Set.toArray == [\"a\", \"b\", \"g\"] - ]} - ") + ```rescript + Set.String.fromArray(["a", "b", "g", "b", "g", "a", "a"])->Set.toArray == ["a", "b", "g"] + ``` + */ let fromArray: array => t - @ocaml.doc(" Create a set from a {!List}. + /** Create a set from a [List](List.mdx#). - {2 Examples} + ## Examples - {[ - Set.String.fromList([\"a\", \"b\", \"g\", \"b\", \"g\", \"a\", \"a\"])->Set.toArray == [\"a\", \"b\", \"g\"] - ]} - ") + ```rescript + Set.String.fromList(["a", "b", "g", "b", "g", "a", "a"])->Set.toArray == ["a", "b", "g"] + ``` + */ let fromList: list => t } - diff --git a/src/TableclothString.resi b/src/TableclothString.resi index 60854a5..4a07dea 100644 --- a/src/TableclothString.resi +++ b/src/TableclothString.resi @@ -1,403 +1,385 @@ -@@ocaml.text(" ") - -@@ocaml.text(" Functions for working with [\"strings\"] ") - +/** Functions for working with `"strings"` + Strings literals are created with the `"double quotes"`, `` `backticks` `` syntax. + ~Warning~ If string contains non-ASCII characters, use `` `backticks` `` + */ type t = string -@@ocaml.text(" {1 Create} - - Strings literals are created with the [\"double quotes\"], [`backticks`] syntax. - {b Warning} If string contains non-ASCII characters, use [`backticks`] - -") - -@ocaml.doc(" Converts the given character to an equivalent string of length one. ") +/** Converts the given character to an equivalent string of length one. */ let fromChar: char => string -@ocaml.doc(" Create a string from an {!Array} of characters. +/** Create a string from an [Array](Array.mdx#) of characters. - Note that these must be individual characters in single quotes, not strings of length one. + Note that these must be individual characters in single quotes, not strings of length one. - {2 Examples} + ## Examples - {[ - String.fromArray([]) == \"\" - String.fromArray(['a', 'b', 'c']) == \"abc\" - ]} -") + ```rescript + String.fromArray([]) == "" + String.fromArray(['a', 'b', 'c']) == "abc" + ``` +*/ let fromArray: array => string -@ocaml.doc(" Create a string from a {!List} of characters. +/** Create a string from a [List](List.mdx#) of characters. - Note that these must be individual characters in single quotes, not strings of length one. + Note that these must be individual characters in single quotes, not strings of length one. - {2 Examples} + ## Examples - {[ - String.fromList(list{}) == \"\" - String.fromList(list{'a', 'b', 'c'}) == \"abc\" - ]} -") + ```rescript + String.fromList(list{}) == "" + String.fromList(list{'a', 'b', 'c'}) == "abc" + ``` +*/ let fromList: list => string -@ocaml.doc(" Create a string by repeating a string [count] time. +/** Create a string by repeating a string `count` time. - {3 Exceptions} + ### Exceptions - If [count] is negative, [String.repeat] throws a [RangeError] exception. + If `count` is negative, [String.repeat] throws a [RangeError] exception. - {2 Examples} + ## Examples - {[ - String.repeat(\"ok\", ~count=3) == \"okokok\" - String.repeat(\"\", ~count=3) == \"\" - String.repeat(\"ok\", ~count=0) == \"\" - ]} -") + ```rescript + String.repeat("ok", ~count=3) == "okokok" + String.repeat("", ~count=3) == "" + String.repeat("ok", ~count=0) == "" + ``` +*/ let repeat: (string, ~count: int) => string -@ocaml.doc(" Create a string by providing a length and a function to choose characters. +/** Create a string by providing a length and a function to choose characters. - Returns an empty string if the length is negative. + Returns an empty string if the length is negative. - {2 Examples} + ## Examples - {[ - String.initialize(8, ~f=Fun.constant('9')) == \"99999999\" - ]} -") + ```rescript + String.initialize(8, ~f=Fun.constant('9')) == "99999999" + ``` +*/ let initialize: (int, ~f: int => char) => string -@@ocaml.text(" {1 Basic operations} ") - -@ocaml.doc(" Get the character at the specified index +/** Get the character at the specified index - {3 Exceptions} + ### Exceptions - If index out of range, throws a [Invalid_argument] exception. - Concider using {!getAt}, it returns an [option] + If index out of range, throws a `Invalid_argument` exception. + Concider using [getAt](#getAt), it returns an `option` - {2 Examples} + ## Examples - {[ - String.get(\"stressed\", 1) == 't' - ]} + ```rescript + String.get("stressed", 1) == 't' + ``` -") +*/ let get: (string, int) => char -@ocaml.doc(" Get the character at [~index] ") +/** Get the character at `~index` */ let getAt: (string, ~index: int) => option -@ocaml.doc(" Reverse a string +/** Reverse a string - {2 Examples} + ## Examples - {[ - String.reverse(\"stressed\") == \"desserts\" - ]} -") + ```rescript + String.reverse("stressed") == "desserts" + ``` +*/ let reverse: string => string -@ocaml.doc(" Extract a substring from the specified indicies. +/** Extract a substring from the specified indicies. - See {!Array.slice}. -") + See [Array.slice](Array.mdx#slice). +*/ let slice: (~to_: int=?, string, ~from: int) => string -@@ocaml.text(" {1 Query} ") - -@ocaml.doc(" Check if a string is empty ") +/** Check if a string is empty */ let isEmpty: string => bool -@ocaml.doc(" Returns the length of the given string. +/** Returns the length of the given string. - {2 Examples} + ## Examples - {[ - String.length(\"abc\") == 3 - ]} -") + ```rescript + String.length("abc") == 3 + ``` +*/ let length: string => int -@ocaml.doc(" See if the string starts with [prefix]. +/** See if the string starts with `~prefix`. - {2 Examples} + ## Examples - {[ - String.startsWith(\"theory\", ~prefix=\"the\") == true - String.startsWith(\"theory\", ~prefix=\"ory\") == false - ]} -") + ```rescript + String.startsWith("theory", ~prefix="the") == true + String.startsWith("theory", ~prefix="ory") == false + ``` +*/ let startsWith: (string, ~prefix: string) => bool -@ocaml.doc(" See if the string ends with [suffix]. +/** See if the string ends with `~suffix`. - {2 Examples} + ## Examples - {[ - String.endsWith(\"theory\", ~suffix=\"the\") == false - String.endsWith(\"theory\", ~suffix=\"ory\") == true - ]} -") + ```rescript + String.endsWith("theory", ~suffix="the") == false + String.endsWith("theory", ~suffix="ory") == true + ``` +*/ let endsWith: (string, ~suffix: string) => bool -@ocaml.doc(" Check if one string appears within another +/** Check if one string appears within another - {2 Examples} + ## Examples - {[ - String.includes(\"team\", ~substring=\"tea\") == true - String.includes(\"team\", ~substring=\"i\") == false - String.includes(\"ABC\", ~substring=\"\") == true - ]} -") + ```rescript + String.includes("team", ~substring="tea") == true + String.includes("team", ~substring="i") == false + String.includes("ABC", ~substring="") == true + ``` +*/ let includes: (string, ~substring: string) => bool -@ocaml.doc(" Test if the first letter of a string is upper case. +/** Test if the first letter of a string is upper case. - {2 Examples} + ## Examples - {[ - String.isCapitalized(\"Anastasia\") == true - String.isCapitalized(\"\") == false - ]} -") + ```rescript + String.isCapitalized("Anastasia") == true + String.isCapitalized("") == false + ``` +*/ let isCapitalized: string => bool -@ocaml.doc(" Drop [count] characters from the left side of a string. +/** Drop `count` characters from the left side of a string. - {2 Examples} + ## Examples - {[ - String.dropLeft(\"abcdefg\", ~count=3) == \"defg\" - String.dropLeft(\"abcdefg\", ~count=0) == \"abcdefg\" - String.dropLeft(\"abcdefg\", ~count=7) == \"\" - String.dropLeft(\"abcdefg\", ~count=-2) == \"fg\" - String.dropLeft(\"abcdefg\", ~count=8) == \"\" - ]} -") + ```rescript + String.dropLeft("abcdefg", ~count=3) == "defg" + String.dropLeft("abcdefg", ~count=0) == "abcdefg" + String.dropLeft("abcdefg", ~count=7) == "" + String.dropLeft("abcdefg", ~count=-2) == "fg" + String.dropLeft("abcdefg", ~count=8) == "" + ``` +*/ let dropLeft: (string, ~count: int) => string -@ocaml.doc(" Drop [count] characters from the right side of a string. +/** Drop `count` characters from the right side of a string. - {2 Examples} + ## Examples - {[ - String.dropRight(\"abcdefg\", ~count=3) == \"abcd\" - String.dropRight(\"abcdefg\", ~count=0) == \"abcdefg\" - String.dropRight(\"abcdefg\", ~count=7) == \"\" - String.dropRight(\"abcdefg\", ~count=-2) == \"abcdefg\" - String.dropRight(\"abcdefg\", ~count=8) == \"\" - ]} -") + ```rescript + String.dropRight("abcdefg", ~count=3) == "abcd" + String.dropRight("abcdefg", ~count=0) == "abcdefg" + String.dropRight("abcdefg", ~count=7) == "" + String.dropRight("abcdefg", ~count=-2) == "abcdefg" + String.dropRight("abcdefg", ~count=8) == "" + ``` +*/ let dropRight: (string, ~count: int) => string -@ocaml.doc(" Returns the index of the first occurrence of [string] or None if string has no occurences of [string] +/** Returns the index of the first occurrence of `string` or None if string has no occurences of `string` - {2 Examples} + ## Examples - {[ - String.indexOf(\"Hello World World\", \"World\") == Some(6) - String.indexOf(\"Hello World World\", \"Bye\") == None - ]} -") + ```rescript + String.indexOf("Hello World World", "World") == Some(6) + String.indexOf("Hello World World", "Bye") == None + ``` +*/ let indexOf: (string, string) => option -@ocaml.doc(" Returns the index of the last occurrence of [string] or None if string has no occurences of [string] +/** Returns the index of the last occurrence of `string` or None if string has no occurences of `string` - {2 Examples} + ## Examples - {[ - String.indexOfRight(\"Hello World World\", \"World\") == Some(12) - String.indexOfRight(\"Hello World World\", \"Bye\") == None - ]} -") + ```rescript + String.indexOfRight("Hello World World", "World") == Some(12) + String.indexOfRight("Hello World World", "Bye") == None + ``` +*/ let indexOfRight: (string, string) => option -@ocaml.doc(" Insert a string at [index]. +/** Insert a string at `index`. - The character previously at index will now follow the inserted string. + The character previously at index will now follow the inserted string. - {2 Examples} + ## Examples - {[ - String.insertAt(\"abcde\", ~value=\"**\", ~index=2) == \"ab**cde\" - String.insertAt(\"abcde\", ~value=\"**\", ~index=0) == \"**abcde\" - String.insertAt(\"abcde\", ~value=\"**\", ~index=5) == \"abcde**\" - String.insertAt(\"abcde\", ~value=\"**\", ~index=-2) == \"abc**de\" - String.insertAt(\"abcde\", ~value=\"**\", ~index=-9) == \"**abcde\" - String.insertAt(\"abcde\", ~value=\"**\", ~index=9) == \"abcde**\" - ]} -") + ```rescript + String.insertAt("abcde", ~value="**", ~index=2) == "ab**cde" + String.insertAt("abcde", ~value="**", ~index=0) == "**abcde" + String.insertAt("abcde", ~value="**", ~index=5) == "abcde**" + String.insertAt("abcde", ~value="**", ~index=-2) == "abc**de" + String.insertAt("abcde", ~value="**", ~index=-9) == "**abcde" + String.insertAt("abcde", ~value="**", ~index=9) == "abcde**" + ``` +*/ let insertAt: (string, ~index: int, ~value: t) => string -@ocaml.doc(" Converts all upper case letters to lower case. +/** Converts all upper case letters to lower case. - {2 Examples} + ## Examples - {[ - String.toLowercase(\"AaBbCc123\") == \"aabbcc123\" - ]} -") + ```rescript + String.toLowercase("AaBbCc123") == "aabbcc123" + ``` +*/ let toLowercase: string => string -@ocaml.doc(" Converts all lower case letters to upper case. +/** Converts all lower case letters to upper case. - {2 Examples} + ## Examples - {[ - String.toUppercase(\"AaBbCc123\") == \"AABBCC123\" - ]} -") + ```rescript + String.toUppercase("AaBbCc123") == "AABBCC123" + ``` +*/ let toUppercase: string => string -@ocaml.doc(" Converts the first letter to lower case if it is upper case. +/** Converts the first letter to lower case if it is upper case. - {2 Examples} + ## Examples - {[ - String.uncapitalize(\"Anastasia\") == \"anastasia\" - ]} -") + ```rescript + String.uncapitalize("Anastasia") == "anastasia" + ``` +*/ let uncapitalize: string => string -@ocaml.doc(" Converts the first letter of [s] to lowercase if it is upper case. +/** Converts the first letter of `s` to lowercase if it is upper case. - {2 Examples} + ## Examples - {[ - String.capitalize(\"den\") == \"Den\" - ]} -") + ```rescript + String.capitalize("den") == "Den" + ``` +*/ let capitalize: string => string -@ocaml.doc(" Removes leading and trailing {{!Char.isWhitespace} whitespace} from a string +/** Removes leading and trailing [whitespace](Char.mdx#isWhitespace) from a string - {2 Examples} + ## Examples - {[ - String.trim(\" abc \") == \"abc\" - String.trim(\" abc def \") == \"abc def\" - String.trim(\"\r\n\t abc \n\n\") == \"abc\" - ]} -") + ```rescript + String.trim(" abc ") == "abc" + String.trim(" abc def ") == "abc def" + String.trim("\r\n\t abc \n\n") == "abc" + ``` +*/ let trim: string => string -@ocaml.doc(" Like {!trim} but only drops characters from the beginning of the string. ") +/** Like [trim](#trim) but only drops characters from the beginning of the string. */ let trimLeft: string => string -@ocaml.doc(" Like {!trim} but only drops characters from the end of the string. ") +/** Like [trim](#trim) but only drops characters from the end of the string. */ let trimRight: string => string -@ocaml.doc(" Pad a string up to a minimum length. +/** Pad a string up to a minimum length. - If the string is shorted than the proivded length, adds [with_] - to the left of the string until the minimum length is met. + If the string is shorted than the proivded length, adds `with_` + to the left of the string until the minimum length is met. - {2 Examples} + ## Examples - {[ - String.padLeft(\"5\", 3, ~with_=\"0\") == \"005\" - ]} -") + ```rescript + String.padLeft("5", 3, ~with_="0") == "005" + ``` +*/ let padLeft: (string, int, ~with_: string) => string -@ocaml.doc(" Pad a string up to a minimum length. +/** Pad a string up to a minimum length. - If the string is shorted than the proivded length, adds [with_] - to the left of the string until the minimum length is met. + If the string is shorted than the proivded length, adds `with_` + to the left of the string until the minimum length is met. - {2 Examples} + ## Examples - {[ - String.padRight(\"Ahh\", 7, ~with_=\"h\") == \"Ahhhhhh\" - ]} -") + ```rescript + String.padRight("Ahh", 7, ~with_="h") == "Ahhhhhh" + ``` +*/ let padRight: (string, int, ~with_: string) => string -@ocaml.doc(" Returns, as an {!Option}, a tuple containing the first {!Char} and the remaining String. +/** Returns, as an [Option](Option.mdx#), a tuple containing the first [Char](Char.mdx#) and the remaining String. - If given an empty string, returns [None]. + If given an empty string, returns `None`. - {2 Examples} + ## Examples - {[ - String.uncons(\"abcde\") == Some('a', \"bcde\") - String.uncons(\"a\") == Some('a', \"\") - String.uncons(\"\") == None - ]} -") + ```rescript + String.uncons("abcde") == Some('a', "bcde") + String.uncons("a") == Some('a', "") + String.uncons("") == None + ``` +*/ let uncons: string => option<(char, string)> -@ocaml.doc(" Divide a string into a list of strings, splitting whenever [on] is encountered. +/** Divide a string into a list of strings, splitting whenever `on` is encountered. - {2 Examples} + ## Examples - {[ - String.split(\"a/b/c\", ~on=\"/\") == list{\"a\", \"b\", \"c\"} - String.split(\"a--b--c\", ~on=\"--\") == list{\"a\", \"b\", \"c\"} - String.split(\"abc\", ~on=\"/\") == list{\"abc\"} - String.split(\"\", ~on=\"/\") == list{\"\"} - String.split(\"abc\", ~on=\"\") == list{\"a\", \"b\", \"c\"} - ]} -") + ```rescript + String.split("a/b/c", ~on="/") == list{"a", "b", "c"} + String.split("a--b--c", ~on="--") == list{"a", "b", "c"} + String.split("abc", ~on="/") == list{"abc"} + String.split("", ~on="/") == list{""} + String.split("abc", ~on="") == list{"a", "b", "c"} + ``` +*/ let split: (string, ~on: string) => list -@@ocaml.text(" {1 Iterate} ") - -@ocaml.doc(" Run [f] on each character in a string. ") +/** Run `f` on each character in a string. */ let forEach: (string, ~f: char => unit) => unit -@ocaml.doc(" Like {!Array.fold} but the elements are {!Char}s ") +/** Like [Array.fold](Array.mdx#fold) but the elements are [Char](Char.mdx#)s */ let fold: (string, ~initial: 'a, ~f: ('a, char) => 'a) => 'a -@@ocaml.text(" {1 Convert} ") - -@ocaml.doc(" Returns an {!Array} of the individual characters in the given string. +/** Returns an [Array](Array.mdx#) of the individual characters in the given string. - {2 Examples} + ## Examples - {[ - String.toArray(\"\") == [] - String.toArray(\"abc\") == ['a', 'b', 'c'] - ]} -") + ```rescript + String.toArray("") == [] + String.toArray("abc") == ['a', 'b', 'c'] + ``` +*/ let toArray: string => array -@ocaml.doc(" Returns a {!List} of the individual characters in the given string. +/** Returns a [List](List.mdx#) of the individual characters in the given string. - {2 Examples} + ## Examples - {[ - String.toList(\"\") == list{} - String.toList(\"abc\") == list{'a', 'b', 'c'} - ]} -") + ```rescript + String.toList("") == list{} + String.toList("abc") == list{'a', 'b', 'c'} + ``` +*/ let toList: string => list -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two string for equality. ") +/** Test two string for equality. */ let equal: (string, string) => bool -@ocaml.doc(" Compare two strings. Strings use 'dictionary' ordering. -1 - Also known as {{: https://en.wikipedia.org/wiki/Lexicographical_order } lexicographical ordering }. +/** Compare two strings. Strings use 'dictionary' ordering. + + Also known as [ lexicographical ordering ](https://en.wikipedia.org/wiki/Lexicographical_order). - {2 Examples} + ## Examples - {[ - String.compare(\"Z\", \"A\") == 1 - String.compare(\"Be\", \"Bee\") == -1 - String.compare(\"Pear\", \"pear\") == 1 - String.compare(\"Peach\", \"Peach\") == 0 - ]} -") + ```rescript + String.compare("Z", "A") == 1 + String.compare("Be", "Bee") == -1 + String.compare("Pear", "pear") == 1 + String.compare("Peach", "Peach") == 0 + ``` +*/ let compare: (string, string) => int -@ocaml.doc(" The unique identity for {!Comparator} ") +/** The unique identity for [Comparator](Comparator.mdx#) */ type identity let comparator: TableclothComparator.t - diff --git a/src/TableclothTuple2.resi b/src/TableclothTuple2.resi index 81b8e0a..d35d338 100644 --- a/src/TableclothTuple2.resi +++ b/src/TableclothTuple2.resi @@ -1,183 +1,174 @@ -@@ocaml.text(" ") - -@@ocaml.text(" Functions for manipulating pairs of values ") - +/** Functions for manipulating pairs of values */ type t<'a, 'b> = ('a, 'b) -@@ocaml.text(" {1 Create} ") - -@ocaml.doc(" Create a two-tuple with the given values. +/** Create a two-tuple with the given values. - The values do not have to be of the same type. + The values do not have to be of the same type. - {2 Examples} + ## Examples - {[ - Tuple2.make(3, \"Clementine\") == (3, \"Clementine\") - ]} -") + ```rescript + Tuple2.make(3, "Clementine") == (3, "Clementine") + ``` +*/ let make: ('a, 'b) => ('a, 'b) -@ocaml.doc(" Create a tuple from the first two elements of an {!Array}. +/** Create a tuple from the first two elements of an [Array](Array.mdx#). - If the array is longer than two elements, the extra elements are ignored. + If the array is longer than two elements, the extra elements are ignored. - If the array is less than two elements, returns [None]. + If the array is less than two elements, returns `None`. - {2 Examples} + ## Examples - {[ - Tuple2.fromArray([1, 2]) == Some(1, 2) - Tuple2.fromArray([1]) == None - Tuple2.fromArray([4, 5, 6]) == Some(4, 5) - ]} -") + ```rescript + Tuple2.fromArray([1, 2]) == Some(1, 2) + Tuple2.fromArray([1]) == None + Tuple2.fromArray([4, 5, 6]) == Some(4, 5) + ``` +*/ let fromArray: array<'a> => option<('a, 'a)> -@ocaml.doc(" Create a tuple from the first two elements of a {!List}. +/** Create a tuple from the first two elements of a [List](List.mdx#). - If the list is longer than two elements, the extra elements are ignored. + If the list is longer than two elements, the extra elements are ignored. - If the list is less than two elements, returns [None]. + If the list is less than two elements, returns `None`. - {2 Examples} + ## Examples - {[ - Tuple2.fromList(list{1, 2}) == Some(1, 2) - Tuple2.fromList(list{1}) == None - Tuple2.fromList(list{4, 5, 6}) == Some(4, 5) - ]} -") + ```rescript + Tuple2.fromList(list{1, 2}) == Some(1, 2) + Tuple2.fromList(list{1}) == None + Tuple2.fromList(list{4, 5, 6}) == Some(4, 5) + ``` +*/ let fromList: list<'a> => option<('a, 'a)> -@ocaml.doc(" Extract the first value from a tuple. +/** Extract the first value from a tuple. - {2 Examples} + ## Examples - {[ - Tuple2.first((3, 4)) == 3 - Tuple2.first((\"john\", \"doe\")) == \"john\" - ]} -") + ```rescript + Tuple2.first((3, 4)) == 3 + Tuple2.first(("john", "doe")) == "john" + ``` +*/ let first: (('a, 'b)) => 'a -@ocaml.doc(" Extract the second value from a tuple. +/** Extract the second value from a tuple. - {2 Examples} + ## Examples - {[ - Tuple2.second((3, 4)) == 4 - Tuple2.second((\"john\", \"doe\")) == \"doe\" - ]} -") + ```rescript + Tuple2.second((3, 4)) == 4 + Tuple2.second(("john", "doe")) == "doe" + ``` +*/ let second: (('a, 'b)) => 'b -@@ocaml.text(" {1 Transform} ") +/** Transform the [first](#first) value in a tuple. -@ocaml.doc(" Transform the {!first} value in a tuple. + ## Examples - {2 Examples} - - {[ - Tuple2.mapFirst((\"stressed\", 16), ~f=String.reverse) == (\"desserts\", 16) - Tuple2.mapFirst((\"stressed\", 16), ~f=String.length) == (8, 16) - ]} -") + ```rescript + Tuple2.mapFirst(("stressed", 16), ~f=String.reverse) == ("desserts", 16) + Tuple2.mapFirst(("stressed", 16), ~f=String.length) == (8, 16) + ``` +*/ let mapFirst: (('a, 'b), ~f: 'a => 'x) => ('x, 'b) -@ocaml.doc(" Transform the second value in a tuple. +/** Transform the second value in a tuple. - {2 Examples} + ## Examples - {[ - Tuple2.mapSecond((\"stressed\", 16.), ~f=Float.squareRoot) == (\"stressed\", 4.) - Tuple2.mapSecond(~f=Int.negate, (\"stressed\", 16)) == (\"stressed\", -16) - ]} -") + ```rescript + Tuple2.mapSecond(("stressed", 16.), ~f=Float.squareRoot) == ("stressed", 4.) + Tuple2.mapSecond(~f=Int.negate, ("stressed", 16)) == ("stressed", -16) + ``` +*/ let mapSecond: (('a, 'b), ~f: 'b => 'c) => ('a, 'c) -@ocaml.doc(" Transform both values of a tuple, using [f] for the first value and [g] for the second. +/** Transform both values of a tuple, using `f` for the first value and `g` for the second. - {2 Examples} + ## Examples - {[ - Tuple2.mapEach((\"stressed\", 16.), ~f=String.reverse, ~g=Float.squareRoot) == (\"desserts\", 4.) - Tuple2.mapEach(~f=String.length, ~g=Int.negate, (\"stressed\", 16)) == (8, -16) - ]} -") + ```rescript + Tuple2.mapEach(("stressed", 16.), ~f=String.reverse, ~g=Float.squareRoot) == ("desserts", 4.) + Tuple2.mapEach(~f=String.length, ~g=Int.negate, ("stressed", 16)) == (8, -16) + ``` +*/ let mapEach: (('a, 'b), ~f: 'a => 'x, ~g: 'b => 'y) => ('x, 'y) -@ocaml.doc(" Transform both of the values of a tuple using the same function. +/** Transform both of the values of a tuple using the same function. - [mapAll] can only be used on tuples which have the same type for each value. + [mapAll] can only be used on tuples which have the same type for each value. - {2 Examples} + ## Examples - {[ - Tuple2.mapAll(~f=Int.add(1), (3, 4)) == (4, 5) - Tuple2.mapAll((\"was\", \"stressed\"), ~f=String.length) == (3, 8) - ]} -") + ```rescript + Tuple2.mapAll(~f=Int.add(1), (3, 4)) == (4, 5) + Tuple2.mapAll(("was", "stressed"), ~f=String.length) == (3, 8) + ``` +*/ let mapAll: (('a, 'a), ~f: 'a => 'b) => ('b, 'b) -@ocaml.doc(" Switches the first and second values of a tuple. +/** Switches the first and second values of a tuple. - {2 Examples} + ## Examples - {[ - Tuple2.swap((3, 4)) == (4, 3) - Tuple2.swap((\"stressed\", 16)) == (16, \"stressed\") - ]} -") + ```rescript + Tuple2.swap((3, 4)) == (4, 3) + Tuple2.swap(("stressed", 16)) == (16, "stressed") + ``` +*/ let swap: (('a, 'b)) => ('b, 'a) -@@ocaml.text(" {1 Convert} ") - -@ocaml.doc(" Turns a tuple into an {!Array} of length two. +/** Turns a tuple into an [Array](Array.mdx#) of length two. - This function can only be used on tuples which have the same type for each value. + This function can only be used on tuples which have the same type for each value. - {2 Examples} + ## Examples - {[ - Tuple2.toArray((3, 4)) == [3, 4] - Tuple2.toArray((\"was\", \"stressed\")) == [\"was\", \"stressed\"] - ]} -") + ```rescript + Tuple2.toArray((3, 4)) == [3, 4] + Tuple2.toArray(("was", "stressed")) == ["was", "stressed"] + ``` +*/ let toArray: (('a, 'a)) => array<'a> -@ocaml.doc(" Turns a tuple into a list of length two. This function can only be used on tuples which have the same type for each value. +/** Turns a tuple into a list of length two. This function can only be used on tuples which have the same type for each value. - {2 Examples} + ## Examples - {[ - Tuple2.toList((3, 4)) == list{3, 4} - Tuple2.toList((\"was\", \"stressed\")) == list{\"was\", \"stressed\"} - ]} -") + ```rescript + Tuple2.toList((3, 4)) == list{3, 4} + Tuple2.toList(("was", "stressed")) == list{"was", "stressed"} + ``` +*/ let toList: (('a, 'a)) => list<'a> -@ocaml.doc(" Test two {!Tuple2}s for equality, using the provided functions to test the - first and second components. +/** Test two [Tuple2](Tuple2.mdx#)s for equality, using the provided functions to test the + first and second components. - {2 Examples} + ## Examples - {[ - Tuple2.equal((1, \"Fox\"), (1, \"Fox\"), Int.equal, String.equal) == true - Tuple2.equal((1, \"Fox\"), (2, \"Hen\"), Int.equal, String.equal) == false - ]} -") + ```rescript + Tuple2.equal((1, "Fox"), (1, "Fox"), Int.equal, String.equal) == true + Tuple2.equal((1, "Fox"), (2, "Hen"), Int.equal, String.equal) == false + ``` +*/ let equal: (t<'a, 'b>, t<'a, 'b>, ('a, 'a) => bool, ('b, 'b) => bool) => bool -@ocaml.doc(" Compare two {!Tuple2}s, using the provided [f] function to compare the first components. - Then, if the first components are equal, the second components are compared with [g]. +/** Compare two [Tuple2](Tuple2.mdx#)s, using the provided `f` function to compare the first components. + Then, if the first components are equal, the second components are compared with `g`. - {2 Examples} + ## Examples - {[ - Tuple2.compare((1, \"Fox\"), (1, \"Fox\"), ~f=Int.compare, ~g=String.compare) == 0 - Tuple2.compare((1, \"Fox\"), (1, \"Eel\"), ~f=Int.compare, ~g=String.compare) == 1 - Tuple2.compare((1, \"Fox\"), (2, \"Hen\"), ~f=Int.compare, ~g=String.compare) == -1 - ]} -") + ```rescript + Tuple2.compare((1, "Fox"), (1, "Fox"), ~f=Int.compare, ~g=String.compare) == 0 + Tuple2.compare((1, "Fox"), (1, "Eel"), ~f=Int.compare, ~g=String.compare) == 1 + Tuple2.compare((1, "Fox"), (2, "Hen"), ~f=Int.compare, ~g=String.compare) == -1 + ``` +*/ let compare: (t<'a, 'b>, t<'a, 'b>, ~f: ('a, 'a) => int, ~g: ('b, 'b) => int) => int diff --git a/src/TableclothTuple3.resi b/src/TableclothTuple3.resi index 4236415..53542c2 100644 --- a/src/TableclothTuple3.resi +++ b/src/TableclothTuple3.resi @@ -1,235 +1,228 @@ -@@ocaml.text(" ") - -@@ocaml.text(" Functions for manipulating trios of values ") - +/** Functions for manipulating trios of values */ type t<'a, 'b, 'c> = ('a, 'b, 'c) -@@ocaml.text(" {1 Create} ") - -@ocaml.doc(" Create a {!Tuple3}. - - {2 Examples} - - {[ - Tuple3.make(3, \"cat\", false) == (3, \"cat\", false) - - Array.map3(~f=Tuple3.make, [1, 2, 3], ['a', 'b', 'c'], [4., 5., 6.]) - == [ - (1, 'a', 4.), - (2, 'b', 5.), - (3, 'c', 6.), - ] - ]} -") +/** Create a [Tuple3](Tuple3.mdx#). + + ## Examples + + ```rescript + Tuple3.make(3, "cat", false) == (3, "cat", false) + + Array.map3(~f=Tuple3.make, [1, 2, 3], ['a', 'b', 'c'], [4., 5., 6.]) + == [ + (1, 'a', 4.), + (2, 'b', 5.), + (3, 'c', 6.), + ] + ``` +*/ let make: ('a, 'b, 'c) => ('a, 'b, 'c) -@ocaml.doc(" Create a tuple from the first two elements of an {!Array}. +/** Create a tuple from the first two elements of an [Array](Array.mdx#). - If the array is longer than three elements, the extra elements are ignored. + If the array is longer than three elements, the extra elements are ignored. - If the array is less than three elements, returns [None] + If the array is less than three elements, returns `None` - {2 Examples} + ## Examples - {[ - Tuple3.fromArray([1, 2, 3]) == Some(1, 2, 3) - Tuple3.fromArray([1, 2]) == None - Tuple3.fromArray([4, 5, 6, 7]) == Some(4, 5, 6) - ]} -") + ```rescript + Tuple3.fromArray([1, 2, 3]) == Some(1, 2, 3) + Tuple3.fromArray([1, 2]) == None + Tuple3.fromArray([4, 5, 6, 7]) == Some(4, 5, 6) + ``` +*/ let fromArray: array<'a> => option<('a, 'a, 'a)> -@ocaml.doc(" Create a tuple from the first two elements of a {!List}. +/** Create a tuple from the first two elements of a [List](List.mdx#). - If the list is longer than two elements, the extra elements are ignored. + If the list is longer than two elements, the extra elements are ignored. - If the list is less than two elements, returns [None] + If the list is less than two elements, returns `None` - {2 Examples} + ## Examples - {[ - Tuple3.fromList(list{1, 2, 3}) == Some(1, 2, 3) - Tuple3.fromList(list{1, 2}) == None - Tuple3.fromList(list{4, 5, 6, 7}) == Some(4, 5, 6) - ]} -") + ```rescript + Tuple3.fromList(list{1, 2, 3}) == Some(1, 2, 3) + Tuple3.fromList(list{1, 2}) == None + Tuple3.fromList(list{4, 5, 6, 7}) == Some(4, 5, 6) + ``` +*/ let fromList: list<'a> => option<('a, 'a, 'a)> -@ocaml.doc(" Extract the first value from a tuple. +/** Extract the first value from a tuple. - {2 Examples} + ## Examples - {[ - Tuple3.first((3, 4, 5)) == 3 - Tuple3.first((\"john\", \"danger\", \"doe\")) == \"john\" - ]} -") + ```rescript + Tuple3.first((3, 4, 5)) == 3 + Tuple3.first(("john", "danger", "doe")) == "john" + ``` +*/ let first: (('a, 'b, 'c)) => 'a -@ocaml.doc(" Extract the second value from a tuple. +/** Extract the second value from a tuple. - {2 Examples} + ## Examples - {[ - Tuple3.second((3, 4, 5)) == 4 - Tuple3.second((\"john\", \"danger\", \"doe\")) == \"danger\" - ]} -") + ```rescript + Tuple3.second((3, 4, 5)) == 4 + Tuple3.second(("john", "danger", "doe")) == "danger" + ``` +*/ let second: (('a, 'b, 'c)) => 'b -@ocaml.doc(" Extract the third value from a tuple. +/** Extract the third value from a tuple. - {2 Examples} + ## Examples - {[ - Tuple3.third((3, 4, 5)) == 5 - Tuple3.third((\"john\", \"danger\", \"doe\")) == \"doe\" - ]} -") + ```rescript + Tuple3.third((3, 4, 5)) == 5 + Tuple3.third(("john", "danger", "doe")) == "doe" + ``` +*/ let third: (('a, 'b, 'c)) => 'c -@ocaml.doc(" Extract the first and second values of a {!Tuple3} as a {!Tuple2}. +/** Extract the first and second values of a [Tuple3](Tuple3.mdx#) as a [Tuple2](Tuple2.mdx#). - {2 Examples} + ## Examples - {[ - Tuple3.initial((3, \"stressed\", false)) == (3, \"stressed\") - Tuple3.initial((\"john\", 16, true)) == (\"john\", 16) - ]} -") + ```rescript + Tuple3.initial((3, "stressed", false)) == (3, "stressed") + Tuple3.initial(("john", 16, true)) == ("john", 16) + ``` +*/ let initial: (('a, 'b, 'c)) => ('a, 'b) -@ocaml.doc(" Extract the second and third values of a {!Tuple3} as a {!Tuple2}. +/** Extract the second and third values of a [Tuple3](Tuple3.mdx#) as a [Tuple2](Tuple2.mdx#). - {2 Examples} + ## Examples - {[ - Tuple3.tail((3, \"stressed\", false)) == (\"stressed\", false) - Tuple3.tail((\"john\", 16, true)) == (16, true) - ]} -") + ```rescript + Tuple3.tail((3, "stressed", false)) == ("stressed", false) + Tuple3.tail(("john", 16, true)) == (16, true) + ``` +*/ let tail: (('a, 'b, 'c)) => ('b, 'c) -@@ocaml.text(" {1 Modify} ") - -@ocaml.doc(" Move each value in the tuple one position to the left, moving the value in the first position into the last position. +/** Move each value in the tuple one position to the left, moving the value in the first position into the last position. - {2 Examples} + ## Examples - {[ - Tuple3.rotateLeft((3, 4, 5)) == (4, 5, 3) - Tuple3.rotateLeft((\"was\", \"stressed\", \"then\")) == (\"stressed\", \"then\", \"was\") - ]} -") + ```rescript + Tuple3.rotateLeft((3, 4, 5)) == (4, 5, 3) + Tuple3.rotateLeft(("was", "stressed", "then")) == ("stressed", "then", "was") + ``` +*/ let rotateLeft: (('a, 'b, 'c)) => ('b, 'c, 'a) -@ocaml.doc(" Move each value in the tuple one position to the right, moving the value in the last position into the first position. +/** Move each value in the tuple one position to the right, moving the value in the last position into the first position. - {2 Examples} + ## Examples - {[ - Tuple3.rotateRight((3, 4, 5)) == (5, 3, 4) - Tuple3.rotateRight((\"was\", \"stressed\", \"then\")) == (\"then\", \"was\", \"stressed\") - ]} -") + ```rescript + Tuple3.rotateRight((3, 4, 5)) == (5, 3, 4) + Tuple3.rotateRight(("was", "stressed", "then")) == ("then", "was", "stressed") + ``` +*/ let rotateRight: (('a, 'b, 'c)) => ('c, 'a, 'b) -@ocaml.doc(" Transform the first value in a tuple. +/** Transform the first value in a tuple. - {2 Examples} + ## Examples - {[ - Tuple3.mapFirst((\"stressed\", 16, false), ~f=String.reverse) == (\"desserts\", 16, false) - Tuple3.mapFirst((\"stressed\", 16, false), ~f=String.length) == (8, 16, false) - ]} -") + ```rescript + Tuple3.mapFirst(("stressed", 16, false), ~f=String.reverse) == ("desserts", 16, false) + Tuple3.mapFirst(("stressed", 16, false), ~f=String.length) == (8, 16, false) + ``` +*/ let mapFirst: (('a, 'b, 'c), ~f: 'a => 'x) => ('x, 'b, 'c) -@ocaml.doc(" Transform the second value in a tuple. +/** Transform the second value in a tuple. - {2 Examples} + ## Examples - {[ - Tuple3.mapSecond((\"stressed\", 16., false), ~f=Float.squareRoot) == (\"stressed\", 4., false) - Tuple3.mapSecond(~f=Int.negate, (\"stressed\", 16, false)) == (\"stressed\", -16, false) - ]} -") + ```rescript + Tuple3.mapSecond(("stressed", 16., false), ~f=Float.squareRoot) == ("stressed", 4., false) + Tuple3.mapSecond(~f=Int.negate, ("stressed", 16, false)) == ("stressed", -16, false) + ``` +*/ let mapSecond: (('a, 'b, 'c), ~f: 'b => 'y) => ('a, 'y, 'c) -@ocaml.doc(" Transform the third value in a tuple. +/** Transform the third value in a tuple. - {2 Examples} + ## Examples - {[ - Tuple3.mapThird((\"stressed\", 16, false), ~f=Bool.not) == (\"stressed\", 16, true) - ]} -") + ```rescript + Tuple3.mapThird(("stressed", 16, false), ~f=Bool.not) == ("stressed", 16, true) + ``` +*/ let mapThird: (('a, 'b, 'c), ~f: 'c => 'z) => ('a, 'b, 'z) -@ocaml.doc(" Transform each value in a tuple by applying [f] to the {!first} value, [g] to the {!second} value and [h] to the {!third} value. +/** Transform each value in a tuple by applying `f` to the [first](#first) value, `g` to the [second](#second) value and `h` to the [third](#third) value. - {2 Examples} + ## Examples - {[ - Tuple3.mapEach( - (\"stressed\", 16., false) - ~f=String.reverse, - ~g=Float.squareRoot, - ~h=Bool.not) - == (\"desserts\", 4., true) - ]} -") + ```rescript + Tuple3.mapEach( + ("stressed", 16., false) + ~f=String.reverse, + ~g=Float.squareRoot, + ~h=Bool.not) + == ("desserts", 4., true) + ``` +*/ let mapEach: (('a, 'b, 'c), ~f: 'a => 'x, ~g: 'b => 'y, ~h: 'c => 'z) => ('x, 'y, 'z) -@ocaml.doc(" Transform all the values of a tuple using the same function. +/** Transform all the values of a tuple using the same function. - [mapAll] can only be used on tuples which have the same type for each value. + `mapAll` can only be used on tuples which have the same type for each value. - {2 Examples} + ## Examples - {[ - Tuple3.mapAll((9., 16., 25.), ~f=Float.squareRoot) == (3., 4., 5.) - Tuple3.mapAll((\"was\", \"stressed\", \"then\"), ~f=String.length) == (3, 8, 4) - ]} -") + ```rescript + Tuple3.mapAll((9., 16., 25.), ~f=Float.squareRoot) == (3., 4., 5.) + Tuple3.mapAll(("was", "stressed", "then"), ~f=String.length) == (3, 8, 4) + ``` +*/ let mapAll: (('a, 'a, 'a), ~f: 'a => 'b) => ('b, 'b, 'b) -@ocaml.doc(" Turns a tuple into a {!List} of length three. +/** Turns a tuple into a [List](List.mdx#) of length three. - This function can only be used on tuples which have the same type for each value. + This function can only be used on tuples which have the same type for each value. - {2 Examples} + ## Examples - {[ - Tuple3.toArray((3, 4, 5)) == [3, 4, 5] - Tuple3.toArray((\"was\", \"stressed\", \"then\")) == [\"was\", \"stressed\", \"then\"] - ]} -") + ```rescript + Tuple3.toArray((3, 4, 5)) == [3, 4, 5] + Tuple3.toArray(("was", "stressed", "then")) == ["was", "stressed", "then"] + ``` +*/ let toArray: (('a, 'a, 'a)) => array<'a> -@ocaml.doc(" Turns a tuple into a {!List} of length three. +/** Turns a tuple into a [List](List.mdx#) of length three. - This function can only be used on tuples which have the same type for each value. + This function can only be used on tuples which have the same type for each value. - {2 Examples} + ## Examples - {[ - Tuple3.toList((3, 4, 5)) == list{3, 4, 5} - Tuple3.toList((\"was\", \"stressed\", \"then\")) == list{\"was\", \"stressed\", \"then\"} - ]} -") + ```rescript + Tuple3.toList((3, 4, 5)) == list{3, 4, 5} + Tuple3.toList(("was", "stressed", "then")) == list{"was", "stressed", "then"} + ``` +*/ let toList: (('a, 'a, 'a)) => list<'a> -@ocaml.doc(" Test two {!Tuple3}s for equality, using the provided functions to test the - first, second and third components. +/** Test two [Tuple3](Tuple3.mdx#)s for equality, using the provided functions to test the + first, second and third components. - {2 Examples} + ## Examples - {[ - Tuple3.equal((1, \"Fox\", 'j'), (1, \"Fox\", 'k'), Int.equal, String.equal, Char.equal) == false - Tuple3.equal((1, \"Fox\", 'j'), (2, \"Hen\", 'j'), Int.equal, String.equal, Char.equal) == false - ]} - ") + ```rescript + Tuple3.equal((1, "Fox", 'j'), (1, "Fox", 'k'), Int.equal, String.equal, Char.equal) == false + Tuple3.equal((1, "Fox", 'j'), (2, "Hen", 'j'), Int.equal, String.equal, Char.equal) == false + ``` + */ let equal: ( t<'a, 'b, 'c>, t<'a, 'b, 'c>, @@ -238,18 +231,18 @@ let equal: ( ('c, 'c) => bool, ) => bool -@ocaml.doc(" Compare two {!Tuple3}s, using [f] to compare the first - components then, if the first components are equal, the second components are compared with [g], - then the third components are compared with [h]. +/** Compare two [Tuple3](Tuple3.mdx#)s, using `f` to compare the first + components then, if the first components are equal, the second components are compared with `g`, + then the third components are compared with `h`. - {2 Examples} + ## Examples - {[ - Tuple3.compare((1, \"Fox\", 'j'), (1, \"Fox\", 'j'), ~f=Int.compare, ~g=String.compare, ~h=Char.compare) == 0 - Tuple3.compare((1, \"Fox\", 'j'), (1, \"Eel\", 'j'), ~f=Int.compare, ~g=String.compare, ~h=Char.compare) == 1 - Tuple3.compare((1, \"Fox\", 'j'), (2, \"Fox\", 'm'), ~f=Int.compare, ~g=String.compare, ~h=Char.compare) == -1 - ]} - ") + ```rescript + Tuple3.compare((1, "Fox", 'j'), (1, "Fox", 'j'), ~f=Int.compare, ~g=String.compare, ~h=Char.compare) == 0 + Tuple3.compare((1, "Fox", 'j'), (1, "Eel", 'j'), ~f=Int.compare, ~g=String.compare, ~h=Char.compare) == 1 + Tuple3.compare((1, "Fox", 'j'), (2, "Fox", 'm'), ~f=Int.compare, ~g=String.compare, ~h=Char.compare) == -1 + ``` + */ let compare: ( t<'a, 'b, 'c>, t<'a, 'b, 'c>, @@ -257,4 +250,3 @@ let compare: ( ~g: ('b, 'b) => int, ~h: ('c, 'c) => int, ) => int - diff --git a/test/ArrayTest.res b/test/ArrayTest.res index 03c81e6..efa31b5 100644 --- a/test/ArrayTest.res +++ b/test/ArrayTest.res @@ -3,6 +3,8 @@ open Jest open Expect open Array + + describe("singleton", () => { test("equals an array literal of the same value", () => expect(singleton(1234))->toEqual([1234])) test("has length one", () => expect(length(singleton(1)))->toEqual(1)) @@ -160,7 +162,7 @@ describe("filterMap", () => ) describe("flatMap", () => - test("{!map} [f] onto an array and {!flatten} the resulting arrays", () => + test("[map](#map) [f] onto an array and [flatten](#flatten) the resulting arrays", () => expect(flatMap(~f=n => [n, n], [1, 2, 3]))->toEqual([1, 1, 2, 2, 3, 3]) ) ) @@ -179,12 +181,12 @@ describe("map", () => ) describe("mapWithIndex", () => test("equals an array literal of the same value", () => - expect(mapWithIndex(~f=\"*", [5, 5, 5]))->toEqual([0, 5, 10]) + expect(mapWithIndex(~f=(a,b)=> a*b, [5, 5, 5]))->toEqual([0, 5, 10]) ) ) describe("map2", () => { test("works the order of arguments to `f` is not important", () => - expect(map2(~f=\"+", [1, 2, 3], [4, 5, 6]))->toEqual([5, 7, 9]) + expect(map2(~f=(a,b)=> a+b, [1, 2, 3], [4, 5, 6]))->toEqual([5, 7, 9]) ) test("works the order of `f` is important", () => expect(map2(~f=Tuple2.make, ["alice", "bob", "chuck"], [2, 5, 7, 8]))->toEqual([ @@ -315,11 +317,11 @@ describe("findIndex", () => { }) describe("includes", () => { - test("returns true if equal", () => expect(includes([1, 2, 3], 2, ~equal=\"="))->toEqual(true)) + test("returns true if equal", () => expect(includes([1, 2, 3], 2, ~equal=(a,b)=> a===b))->toEqual(true)) test("returns false if not equal", () => - expect(includes([1, 5, 3], 2, ~equal=\"="))->toEqual(false) + expect(includes([1, 5, 3], 2, ~equal=(a,b)=> a===b))->toEqual(false) ) - test("returns false if empty", () => expect(includes([], 2, ~equal=\"="))->toEqual(false)) + test("returns false if empty", () => expect(includes([], 2, ~equal=(a,b)=> a===b))->toEqual(false)) }) describe("minimum", () => { @@ -481,12 +483,12 @@ describe("slice", () => { test("works `from` >= `to_`", () => expect(slice(~from=4, ~to_=3, numbers))->toEqual([])) }) describe("fold", () => { - test("works for an empty array", () => expect(fold([], ~f=\"^", ~initial=""))->toEqual("")) + test("works for an empty array", () => expect(fold([], ~f=(a,b)=> a++b, ~initial=""))->toEqual("")) test("works for an ascociative operator", () => - expect(fold(~f=\"*", ~initial=1, repeat(~length=4, 7)))->toEqual(2401) + expect(fold(~f=(a,b)=> a*b, ~initial=1, repeat(~length=4, 7)))->toEqual(2401) ) test("works the order of arguments to `f` is important", () => - expect(fold(["a", "b", "c"], ~f=\"^", ~initial=""))->toEqual("abc") + expect(fold(["a", "b", "c"], ~f=(a,b)=> a++b, ~initial=""))->toEqual("abc") ) test("works the order of arguments to `f` is important", () => expect( @@ -495,10 +497,10 @@ describe("fold", () => { ) }) describe("foldRight", () => { - test("works for empty arrays", () => expect(foldRight([], ~f=\"^", ~initial=""))->toEqual("")) - test("foldRight", () => expect(foldRight(~f=\"+", ~initial=0, repeat(~length=3, 5)))->toEqual(15)) + test("works for empty arrays", () => expect(foldRight([], ~f=(a,b)=> a++b, ~initial=""))->toEqual("")) + test("foldRight", () => expect(foldRight(~f=(a,b)=> a+b, ~initial=0, repeat(~length=3, 5)))->toEqual(15)) test("works the order of arguments to `f` is important", () => - expect(foldRight(["a", "b", "c"], ~f=\"^", ~initial=""))->toEqual("cba") + expect(foldRight(["a", "b", "c"], ~f=(a,b)=> a++b, ~initial=""))->toEqual("cba") ) test("works the order of arguments to `f` is important", () => expect( diff --git a/test/BoolTest.res b/test/BoolTest.res index 2c01023..5b5a930 100644 --- a/test/BoolTest.res +++ b/test/BoolTest.res @@ -3,6 +3,7 @@ open Jest open Expect open Bool + describe("fromInt", () => { test("converts zero to Some(false)", () => expect(fromInt(0))->toEqual(Some(false))) test("converts one to Some(true)", () => expect(fromInt(1))->toEqual(Some(true))) diff --git a/test/ListTest.res b/test/ListTest.res index 5511833..b82b55f 100644 --- a/test/ListTest.res +++ b/test/ListTest.res @@ -167,13 +167,13 @@ describe("reverse", () => { test("two elements", () => expect(reverse(list{0, 1}))->toEqual(list{1, 0})) }) describe("map2", () => { - test("map2 empty lists", () => expect(map2(~f=\"+", list{}, list{}))->toEqual(list{})) - test("map2 one element", () => expect(map2(~f=\"+", list{1}, list{1}))->toEqual(list{2})) + test("map2 empty lists", () => expect(map2(~f=(a,b) =>(a+b), list{}, list{}))->toEqual(list{})) + test("map2 one element", () => expect(map2(~f=(a,b) =>(a+b), list{1}, list{1}))->toEqual(list{2})) test("map2 two elements", () => - expect(map2(~f=\"+", list{1, 2}, list{1, 2}))->toEqual(list{2, 4}) + expect(map2(~f=(a,b) =>(a+b), list{1, 2}, list{1, 2}))->toEqual(list{2, 4}) ) test("map2 with lists of different lengths", () => - expect(map2(~f=\"+", list{1, 2, 3}, list{1, 2}))->toEqual(list{2, 4}) + expect(map2(~f=(a,b) =>(a+b), list{1, 2, 3}, list{1, 2}))->toEqual(list{2, 4}) ) }) @@ -265,7 +265,7 @@ describe("groupWhile", () => { test("empty list", () => expect(groupWhile(~f=String.equal, list{}))->toEqual(list{})) test("normal char", () => - expect(groupWhile(~f=\"<>", list{"a", "b", "b", "a", "a", "a", "b", "a"}))->toEqual(list{ + expect(groupWhile(~f=(a,b) => a !==b, list{"a", "b", "b", "a", "a", "a", "b", "a"}))->toEqual(list{ list{"a"}, list{"b", "b"}, list{"a", "a", "a"}, @@ -402,7 +402,7 @@ describe("sum", () => { let zero = "" - let add = \"^" + let add = (a,b) => a ++ b } ), ), @@ -543,8 +543,8 @@ describe("fold", () => { test("foldr three elements", () => expect(foldRight(~f=cons, ~initial=list{}, list{1, 2, 3}))->toEqual(list{1, 2, 3}) ) - test("-", () => expect(fold(~f=\"-", ~initial=0, list{1, 2, 3}))->toEqual(-6)) - test("- foldRight", () => expect(foldRight(~f=\"-", ~initial=0, list{1, 2, 3}))->toEqual(-6)) + test("-", () => expect(fold(~f=(a,b)=> a-b, ~initial=0, list{1, 2, 3}))->toEqual(-6)) + test("- foldRight", () => expect(foldRight(~f=(a,b)=> a-b, ~initial=0, list{1, 2, 3}))->toEqual(-6)) }) describe("insertAt", () => { test("empty list", () => expect(insertAt(~index=0, ~value=1, list{}))->toEqual(list{1}))