From 27c626f74322792bc19b263316910f6e6cd9c457 Mon Sep 17 00:00:00 2001 From: Sergey Zhukaev Date: Sat, 11 Nov 2023 11:18:23 +0100 Subject: [PATCH 1/2] docstrings WIP --- src/Tablecloth.res | 30 +- src/TableclothArray.resi | 1054 ++++++++++++++------------- src/TableclothBool.resi | 216 +++--- src/TableclothChar.resi | 339 +++++---- src/TableclothComparator.resi | 113 ++- src/TableclothContainer.res | 10 +- src/TableclothFloat.resi | 1021 +++++++++++++------------- src/TableclothFun.resi | 261 ++++--- src/TableclothInt.resi | 425 ++++++----- src/TableclothList.resi | 1274 ++++++++++++++++----------------- src/TableclothMap.resi | 598 ++++++++-------- src/TableclothOption.resi | 430 ++++++----- src/TableclothResult.resi | 597 ++++++++------- src/TableclothSet.resi | 490 +++++++------ src/TableclothString.resi | 494 +++++++------ src/TableclothTuple2.resi | 232 +++--- src/TableclothTuple3.resi | 326 +++++---- test/ArrayTest.res | 24 +- test/BoolTest.res | 1 + test/ListTest.res | 16 +- 20 files changed, 3917 insertions(+), 4034 deletions(-) diff --git a/src/Tablecloth.res b/src/Tablecloth.res index d92ccab..4e3a9b1 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} or {!List} */ 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..a0a717f 100644 --- a/src/TableclothArray.resi +++ b/src/TableclothArray.resi @@ -1,831 +1,821 @@ -@@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#)}. +*/ type t<'a> = array<'a> -@@ocaml.text(" {1 Create} - - You can create an [array] in Rescript with the [[1, 2, 3]] syntax. -") +/** # Create -@ocaml.doc(" Create an array with only one element. + You can create an `array` in Rescript with the `[1, 2, 3]` syntax. +*/ +/** Create an array with only one element. - {2 Examples} + ## 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} ") +/** # Basic operations */ +/** Get the element at the specified index. -@ocaml.doc(" 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: + ```rescript + array[n] + ``` - {[ - array[n] - ]} + Or using the safer [Array.getAt](#get-at) function. - Or using the safer {!Array.getAt} function. + ### Exceptions - {3 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)]. + ## Examples - {2 Examples} + ```rescript + [1, 2, 3, 2, 1][3] == 2 - {[ - [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. +/** # Query */ +/** 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} ") +/** # 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}. +/** # Deconstruct */ +/** 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} ") +/** # Iterate */ +/** Iterates over the elements of invokes `f` for each element. -@ocaml.doc(" Iterates over the elements of invokes [f] for each element. + ## Examples - {2 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} ") - -@ocaml.doc(" Converts an array of strings into a {!String}, placing [sep] between each string in the result. +/** # Convert */ +/** Converts an array of strings into a [String](String.mdx#), placing `sep` between each string in the result. - {2 Examples} + ## 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. */ 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..5fff6b5 100644 --- a/src/TableclothBool.resi +++ b/src/TableclothBool.resi @@ -1,151 +1,143 @@ -@@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} ") +/** # Create */ +/** Convert an {!Int} into a {!Bool}. -@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}. - {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. +/** # Basic operations */ +/** 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 */ +/** 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}. - {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} ") +/** {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..7dbcdce 100644 --- a/src/TableclothChar.resi +++ b/src/TableclothChar.resi @@ -1,245 +1,240 @@ -@@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 {{: https://www.w3schools.com/charsets/ref_html_ascii.asp } here}. + Characters from 128-255 range can still be handled, but only as codes. +*/ type t = char -@@ocaml.text(" {1 Create} +/** # Create - You can also create a {!Char} using single quotes: + You can also create a {!Char} using single quotes: - {[ - let char = 'c' - ]} -") + ```rescript + let char = 'c' + ``` +*/ +/** Convert an ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point } to a character. -@ocaml.doc(" Convert an ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point } to a character. + The full range of extended ASCII is from `0` to [255]. + For numbers outside that range, you get `None`. - The full range of extended ASCII is from [0] to [255]. - For numbers outside that range, you get [None]. + ## Examples - {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 {{: https://en.wikipedia.org/wiki/ASCII#Printable_characters } printable } character - A Printable character has a {!Char.toCode} in the range 32 to 127, inclusive ([' '] to ['~']). + A Printable character has a {!Char.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 {{: https://en.wikipedia.org/wiki/Code_point } 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}. - 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}s for equality */ let equal: (t, t) => bool -@ocaml.doc(" Compare two {!Char}s ") +/** Compare two {!Char}s */ let compare: (t, t) => int -@ocaml.doc(" The unique identity for {!Comparator} ") +/** The unique identity for {!Comparator} */ type identity let comparator: TableclothComparator.t - diff --git a/src/TableclothComparator.resi b/src/TableclothComparator.resi index 09aa75f..9282dd5 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}s and {!Set}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} 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} signature. - First we need to make our module conform to the {!S} signature. + This can be done by using the {!Make} 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} 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}. */ type comparator<'a, 'identity> = t<'a, 'identity> module type S = { - @@ocaml.text(" The output type of {!Make}. ") - + /** The output type of {!Make}. */ type t type identity @@ -74,25 +69,25 @@ module type S = { ) 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}. - {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..afebf47 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 + /** Modules which conform to this signature can be used with functions like {!Array.sum} or {!List.sum}. - ") - + */ type t let zero: t diff --git a/src/TableclothFloat.resi b/src/TableclothFloat.resi index 01bc80e..73c1fa3 100644 --- a/src/TableclothFloat.resi +++ b/src/TableclothFloat.resi @@ -1,61 +1,57 @@ -@@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 {{: https://en.wikipedia.org/wiki/Floating-point_arithmetic } floating-point numbers}. + + 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 {{: https://en.wikipedia.org/wiki/IEEE_754 } 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. ") +/** {1 Constants} */ +/** 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 {{: https://en.wikipedia.org/wiki/NaN } not a number}. - {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} 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} - {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 {{: https://en.wikipedia.org/wiki/IEEE_754-1985#Positive_and_negative_infinity } 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}. */ let negativeInfinity: t @ocaml.doc( @@ -63,515 +59,508 @@ let negativeInfinity: t ) let e: t -@ocaml.doc(" An approximation of {{: https://en.wikipedia.org/wiki/Pi } pi}. ") +/** An approximation of {{: https://en.wikipedia.org/wiki/Pi } 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 + {{: 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. - 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} +*/ 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 + {{: 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. - 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} +*/ let minimumSafeInteger: t -@@ocaml.text(" {1 Create} ") - -@ocaml.doc(" Convert an {!Int} to a [float]. +/** # Create */ +/** Convert an {!Int} to a [float]. - {2 Examples} + ## 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) - ]} -") +/** Convert a [String](String.mdx#) to a [float]. + The behaviour of this function is platform specific. + Parses [Infinity] case-sensitive, [NaN] is case-insensitive. + + ## Examples + + ```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 -@@ocaml.text(" {1 Basic arithmetic and operators} ") +/** {1 Basic arithmetic and operators} */ +/** Addition for floating point numbers. -@ocaml.doc(" Addition for floating point numbers. + 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} 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 {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. + 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} to a [float] for some reason, you - could: + ```rescript + [1, 2, 3]->Array.length->Int.toFloat->Float.add(3.5) == 6.5 + ``` - {[ - [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. + ## Examples - {2 Examples} + ```rescript + Float.add(3.14, 3.14) == 6.28 - {[ - 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 {{: https://en.wikipedia.org/wiki/Absolute_value } 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. +/** {1 Fancier math} */ +/** 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} 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} ") - -@ocaml.doc(" Determine whether a [float] is an [undefined] or unrepresentable number. +/** # Query */ +/** Determine whether a [float] is an [undefined] or unrepresentable number. - {b Note: } this function is more useful than it might seem since [NaN] {b does not } equal [NaN]: + *Note: * this function is more useful than it might seem since [NaN] *does not * equal [NaN]: - {[ - (Float.nan == Float.nan) == false - ]} + ```rescript + (Float.nan == Float.nan) == false + ``` - {2 Examples} + ## 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} ") +/** {1 Angles} */ +/** This type is just an alias for [float]. -@ocaml.doc(" 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 {{: https://en.wikipedia.org/wiki/Degree_(angle) } degrees} to {!Float.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} to {{: https://en.wikipedia.org/wiki/Radian } radians}. - {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 {{: https://en.wikipedia.org/wiki/Turn_(geometry) } turns} into {!Float.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). +/** {1 Polar coordinates} */ +/** 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). - {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 {{: 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)]. - {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 {{: https://en.wikipedia.org/wiki/Radian } radians}. - {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 {{: https://en.wikipedia.org/wiki/Radian } radians}: - {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 {{: https://en.wikipedia.org/wiki/Radian } radians}. - {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 {{: https://en.wikipedia.org/wiki/Radian } radians}: - {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} 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} 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} ") - -@ocaml.doc(" The possible [direction]s availible when doing {!Float.round}. +/** {1 Rounding} */ +/** The possible [direction]s availible when doing {!Float.round}. - See {!Float.round} for what each variant represents. - ") + See {!Float.round} for what each variant represents. + */ type direction = [ | #Zero | #AwayFromZero @@ -580,193 +569,191 @@ 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} + {3 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} + {3 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} + {3 Towards infinity} - This is also known as {!Float.ceiling}. + This is also known as {!Float.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} + {3 Towards negative infinity} - This is also known as {!Float.floor}. + This is also known as {!Float.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} + {3 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} + {3 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} + {3 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} + {3 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} + {3 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} + {3 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} ") +/** # Convert */ +/** Converts a [float] to an {!Int} by *ignoring the decimal portion*. See {!Float.truncate} for examples. -@ocaml.doc(" Converts a [float] to an {!Int} by {b ignoring the decimal portion}. See {!Float.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} or {!Float.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} prior to using this function. + ## Examples - {2 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. ") +/** {1 Compare} */ +/** 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..7f02d74 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.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} or {!Array.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} / {!Array.filter} or {!List.find} / {!Array.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}-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} but for a {!Tuple3}. */ let curry3: ((('a, 'b, 'c)) => 'd, 'a, 'b, 'c) => 'd -@ocaml.doc(" Like {!uncurry} but for a {!Tuple3}. ") +/** Like {!uncurry} but for a {!Tuple3}. */ let uncurry3: (('a, 'b, 'c) => 'd, ('a, 'b, 'c)) => 'd diff --git a/src/TableclothInt.resi b/src/TableclothInt.resi index 621d623..9e32894 100644 --- a/src/TableclothInt.resi +++ b/src/TableclothInt.resi @@ -1,331 +1,322 @@ -@@ocaml.text(" ") +/** An [int] is a whole number. -@@ocaml.text(" An [int] is a whole number. + 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] - 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 {{: https://en.wikipedia.org/wiki/Integer_overflow } 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} 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. - 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. -") + {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. +*/ type t = int -@@ocaml.text(" {1 Constants } ") - -@ocaml.doc(" The literal [0] as a named value. ") +/** {1 Constants } */ +/** 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 - ]} -") +/** # Create */ +/** 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. +/** {1 Operators} */ +/** Add two {!Int} numbers. - You {e cannot } add an [int] and a [float] directly though. + You {e cannot } add an [int] and a [float] directly though. - See {!Float.add} for why, and how to overcome this limitation. + See {!Float.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 {{: https://en.wikipedia.org/wiki/Absolute_value } 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 {{: https://en.wikipedia.org/wiki/Modular_arithmetic } modular arithmetic }. - {b Note:} {!modulo} is not [%] JS operator. If you want [%], use {!remainder} + *Note:* {!modulo} is not [%] JS operator. If you want [%], use {!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} or {!Int.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} 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} 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} 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. +/** # Query */ +/** 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 */ +/** Convert an [int] into a [float]. Useful when mixing {!Int} and {!Float} 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. ") +/** {1 Compare} */ +/** 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}. */ type identity let comparator: TableclothComparator.t diff --git a/src/TableclothList.resi b/src/TableclothList.resi index 325a23c..3aa5e61 100644 --- a/src/TableclothList.resi +++ b/src/TableclothList.resi @@ -1,435 +1,429 @@ -@@ocaml.text(" ") +/** Immutable singly-linked list of elements which must have the same type. -@@ocaml.text(" Immutable singly-linked list of elements which must have the same type. + Lists can have any number of elements. - 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 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: - 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" + } + ``` - {[ - 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 - 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}. -") + As they have inefficent ([O(n)]) {!getAt} and {!length} operations. + If those are important to your use-case, perhaps you need an {!Array}. +*/ type t<'a> = list<'a> -@@ocaml.text(" {1 Create} - - You can create a [list] with the [list{1, 2, 3}] syntax. -") +/** # Create -@ocaml.doc(" An empty list. + You can create a [list] with the [list{1, 2, 3}] syntax. +*/ +/** An empty list. - {2 Examples} + ## 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}. - {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} ") +/** # Basic operations */ +/** Returns, as an [Option](Option.mdx#), the first element of a list. -@ocaml.doc(" Returns, as an {!Option}, the first element of a list. + If the list is empty, returns `None`. - If the list is empty, returns [None]. + ## Examples - {2 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 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 []. - 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. +/** # Query */ +/** 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}. - 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. @@ -437,268 +431,267 @@ let count: (t<'a>, ~f: 'a => bool) => int 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} 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} 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} ") - -@ocaml.doc(" Create a new list which is the result of applying a function [f] to every element. +/** # Transform */ +/** Create a new list which is the result of applying a function `f` to every element. - {2 Examples} + ## 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} 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} and {!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} then {!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} 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} 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}) - {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( @@ -706,291 +699,286 @@ let fold: (t<'a>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b ) let foldRight: (t<'a>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b -@@ocaml.text(" {1 Combine} ") +/** {1 Combine} */ +/** Creates a new list which is the result of appending the second list onto the end of the first. -@ocaml.doc(" Creates a new list which is the result of appending the second list onto the end of the first. + ## Examples - {2 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}. - 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} ") - -@ocaml.doc(" Split a list into a {!Tuple2} of lists. Values which [f] returns true for will end up in {!Tuple2.first}. +/** # Deconstruct */ +/** Split a list into a {!Tuple2} of lists. Values which `f` returns true for will end up in {!Tuple2.first}. - {2 Examples} + ## 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} 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} 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} into a {!Tuple2} 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. +/** # Iterate */ +/** 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} 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} ") +/** # 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}. */ let toArray: t<'a> => array<'a> -@@ocaml.text(" {1 Compare} ") - -@ocaml.doc(" Test two lists for equality using the provided function to test elements. ") +/** {1 Compare} */ +/** 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..7187245 100644 --- a/src/TableclothMap.resi +++ b/src/TableclothMap.resi @@ -1,489 +1,479 @@ -@@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} and {!Map.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} and {!Map.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. + Custom data types can be used with maps as long as the module satisfies the {!Comparator.S} interface. - Custom data types can be used with maps as long as the module satisfies the {!Comparator.S} interface. + ```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 + }) + } - {[ - 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 - }) - } + type animal = + | Cow + | Pig + | Alpacca - type animal = - | Cow - | Pig - | Alpacca - - let pointToAnimal = Map.fromArray( - module(Point), - [((0, 0), Alpacca), ((3, 4), Cow), ((6, 7), Pig)], - ) - ]} - - 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} module for a more details. +*/ type t<'key, 'value, 'cmp> = Belt.Map.t<'key, 'value, 'cmp> -@@ocaml.text(" {1 Create} +/** # Create - You can create sets of modules types which conform to the {!Comparator.S} signature by using {!empty}, {!singleton}, {!fromList} or {!fromArray}. + You can create sets of modules types which 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. -") + Specialised versions of the {!empty}, {!singleton}, {!fromList} and {!fromArray} functions available in the {!Set.Int} and {!Set.String} sub-modules. +*/ +/** A map with nothing in it. -@ocaml.doc(" A map with nothing in it. + Often used as an intial value for functions like {!Array.fold}. - Often used as an intial value for functions like {!Array.fold}. + ## Examples - {2 Examples} + ```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")] + ``` - {[ - 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} +*/ 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} 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} ") - -@ocaml.doc(" Adds a new entry to a map. If [key] is allready present, its previous value is replaced with [value]. - - {2 Examples} - - {[ - 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\")] - ]} -") +/** # Basic operations */ +/** Adds a new entry to a map. If [key] is allready present, its previous value is replaced with `value`. + + ## 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=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. ") +/** # Query */ +/** 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} 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} ") - -@ocaml.doc(" Combine two maps. +/** {1 Combine} */ +/** 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. - {2 Examples} + ## Examples - {[ - let animalToPopulation = Map.String.fromArray([(\"Elephant\", 3_156), (\"Shrew\", 56_423)]) + ```rescript + 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} ") +/** # Transform */ +/** Apply a function to all values in a dictionary. -@ocaml.doc(" Apply a function to all values in a dictionary. + ## Examples - {2 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} 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} and {!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} 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. ") +/** # Iterate */ +/** 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} 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. - - {2 Examples} - - {[ - Map.String.fromArray([ - (\"Elephant\", 3_156), - (\"Mosquito\", 56_123_156), - (\"Rhino\", 3), - (\"Shrew\", 56_423), - ])->Map.keys - == list{\"Elephant\", \"Mosquito\", \"Rhino\", \"Shrew\"} - ]} -") +/** # Convert */ +/** Get a [List](List.mdx#) of all of the keys in a map. + + ## Examples + + ```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} 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} 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}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} 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} 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..e3a8756 100644 --- a/src/TableclothOption.resi +++ b/src/TableclothOption.resi @@ -1,329 +1,325 @@ -@@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} or {!andThen} + - Unwrapping it using {!unwrap} + - Converting a `None` into an exception using{!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} 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 {{: https://rescript-lang.org/docs/manual/latest/pipe#pipe-into-variants} Reason docs } 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. 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}, 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}, otherwise return the first. - Like {!or_} but in reverse. Useful when using the [|>] operator + Like {!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}. - 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}, + {!Array.first} or {!List.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} or {!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}, {!map} or {!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}. - [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. +/** {1 Compare} */ +/** 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..0dddd67 100644 --- a/src/TableclothResult.resi +++ b/src/TableclothResult.resi @@ -1,457 +1,450 @@ -@@ocaml.text(" ") +/** A {!Result} is used to represent a computation which may fail. -@@ocaml.text(" A {!Result} is used to represent a computation which may fail. + A [Result] 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] 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 {{: 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](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}. +/** # Create */ +/** A function alternative to the [Ok] constructor which can be used in places where + the constructor isn't permitted or functions like {!List.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} or functions like {!List.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 {{: https://reasonml.github.io/docs/en/pipe-first#pipe-into-variants} Rescript docs } 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}, 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} 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} 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} its safer and just as + convenient to use pattern matching directly or use one of {!Result.andThen} + or {!Result.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} 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} followed by {!Result.unwrapUnsafe} its safer and just as + convenient to use pattern matching directly or use one of {!Result.andThen} + or {!Result.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}, 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_} 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}, 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. - {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}, otherwise return the first. Like {!or_} but in reverse. Useful when using the [|>] operator - {2 Examples} + ## Examples - {[Result.orElse (Ok \"Boar\") (Ok \"Gecko\") = (Ok \"Gecko\")]} + ```rescriptResult.orElse (Ok "Boar") (Ok "Gecko") = (Ok "Gecko")``` - {[Result.orElse (Error (`UnexpectedInvertabrate \"Periwinkle\")) (Ok \"Gecko\") = (Ok \"Gecko\")]} + ```rescriptResult.orElse (Error (`UnexpectedInvertabrate "Periwinkle")) (Ok "Gecko") = (Ok "Gecko")``` - {[Result.orElse (Ok \"Boar\") (Error (`UnexpectedInvertabrate \"Periwinkle\")) = (Ok \"Boar\") ]} + ```rescriptResult.orElse (Ok "Boar") (Error (`UnexpectedInvertabrate "Periwinkle")) = (Ok "Boar") ``` - {[Result.orElse (Error (`UnexpectedInvertabrate \"Periwinkle\")) (Error (`UnexpectedBird \"Robin\")) = (Error (`UnexpectedInvertabrate \"Periwinkle\"))]} -") + ```rescriptResult.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} 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]} + ```rescriptResult.unwrapLazy ~default:(lazy 0) (Ok 12) = 12``` - {[Result.unwrapLazy ~default:(lazy 0) ((Error (`UnexpectedBird \"Ostrich\"))) = 0]} -") + ```rescriptResult.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} 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] 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 */ +/** Convert a {!Result} 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. +/** {1 Compare} */ +/** 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..bd10fc3 100644 --- a/src/TableclothSet.resi +++ b/src/TableclothSet.resi @@ -1,403 +1,393 @@ -@@ocaml.text(" ") +/** A {!Set} 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} and {!Set.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} and {!Set.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. + Custom data types can be used with sets as long as the module satisfies the {!Comparator.S} interface. - Custom data types can be used with sets as long as the module satisfies the {!Comparator.S} interface. + ```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 + }) + } - {[ - 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 - }) - } - - let points = Set.fromArray(module(Point), [(0, 0), (3, 4), (6, 7)]) - ]} - - See the {!Comparator} module for a more details. -") + let points = Set.fromArray(module(Point), [(0, 0), (3, 4), (6, 7)]) + ``` + See the {!Comparator} module for a more details. +*/ type t<'a, 'id> = Belt.Set.t<'a, 'id> -@@ocaml.text(" {1 Create} +/** # 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. - - Often used as an initial value for functions like {!Array.fold} - - {2 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'] - ]} -") +*/ +/** A set with nothing in it. + + Often used as an initial value for functions like {!Array.fold} + + ## Examples + + ```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}. - {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}. - {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} ") - -@ocaml.doc(" Insert a value into a set. +/** # Basic operations */ +/** Insert a value into a set. - {2 Examples} + ## 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} ") - -@ocaml.doc(" Check if a set is empty. +/** # Query */ +/** Check if a set is empty. - {2 Examples} + ## 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. +/** {1 Combine} */ +/** 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} ") +/** # Transform */ +/** Keep elements that `f` returns `true` for. -@ocaml.doc(" Keep elements that [f] returns [true] for. + ## Examples - {2 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. - {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} ") +/** # Convert */ +/** Converts a set into an {!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} - {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}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} - {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} - {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}. - {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..b270843 100644 --- a/src/TableclothString.resi +++ b/src/TableclothString.resi @@ -1,403 +1,393 @@ -@@ocaml.text(" ") - -@@ocaml.text(" Functions for working with [\"strings\"] ") - +/** Functions for working with ["strings"] */ 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`] +/** # Create -") + Strings literals are created with the ["double quotes"], [`backticks`] syntax. + *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} 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} ") +/** # Basic operations */ +/** Get the character at the specified index -@ocaml.doc(" Get the character at the specified index + ### Exceptions - {3 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}, it returns an [option] + ## Examples - {2 Examples} + ```rescript + String.get("stressed", 1) == 't' + ``` - {[ - 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}. +*/ let slice: (~to_: int=?, string, ~from: int) => string -@@ocaml.text(" {1 Query} ") - -@ocaml.doc(" Check if a string is empty ") +/** # Query */ +/** 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 {{!Char.isWhitespace} whitespace} 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} 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} 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} 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. ") +/** # Iterate */ +/** 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} but the elements are {!Char}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. +/** # Convert */ +/** Returns an {!Array} 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. ") +/** {1 Compare} */ +/** Test two string for equality. */ let equal: (string, string) => bool -@ocaml.doc(" Compare two strings. Strings use 'dictionary' ordering. +/** Compare two strings. Strings use 'dictionary' ordering. 1 - Also known as {{: https://en.wikipedia.org/wiki/Lexicographical_order } lexicographical ordering }. + Also known as {{: https://en.wikipedia.org/wiki/Lexicographical_order } lexicographical ordering }. - {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} */ type identity let comparator: TableclothComparator.t - diff --git a/src/TableclothTuple2.resi b/src/TableclothTuple2.resi index 81b8e0a..e59cfcc 100644 --- a/src/TableclothTuple2.resi +++ b/src/TableclothTuple2.resi @@ -1,183 +1,177 @@ -@@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 */ +/** 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}. - 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 */ +/** Transform the {!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. +/** # Convert */ +/** Turns a tuple into an {!Array} 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}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}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..6d44e0e 100644 --- a/src/TableclothTuple3.resi +++ b/src/TableclothTuple3.resi @@ -1,235 +1,230 @@ -@@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 */ +/** Create a {!Tuple3}. + + ## 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}. - 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} as a {!Tuple2}. - {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} as a {!Tuple2}. - {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. +/** {1 Modify} */ +/** 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} value, [g] to the {!second} value and [h] to the {!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}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 +233,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}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 +252,3 @@ let compare: ( ~g: ('b, 'b) => int, ~h: ('c, 'c) => int, ) => int - diff --git a/test/ArrayTest.res b/test/ArrayTest.res index 03c81e6..99f1647 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)) @@ -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})) From 3ae96e290091176b9a1c996671cbd5af2324232c Mon Sep 17 00:00:00 2001 From: Sergey Zhukaev Date: Wed, 3 Jan 2024 21:07:06 +0100 Subject: [PATCH 2/2] Markdown docstrings (Rescript 11) --- src/Tablecloth.res | 2 +- src/TableclothArray.resi | 27 +++-- src/TableclothBool.resi | 20 ++-- src/TableclothChar.resi | 52 ++++----- src/TableclothComparator.resi | 18 +-- src/TableclothContainer.res | 2 +- src/TableclothFloat.resi | 205 ++++++++++++++++------------------ src/TableclothFun.resi | 30 ++--- src/TableclothInt.resi | 88 +++++++-------- src/TableclothList.resi | 128 ++++++++++----------- src/TableclothMap.resi | 66 +++++------ src/TableclothOption.resi | 55 +++++---- src/TableclothResult.resi | 137 ++++++++++++----------- src/TableclothSet.resi | 49 ++++---- src/TableclothString.resi | 66 +++++------ src/TableclothTuple2.resi | 17 ++- src/TableclothTuple3.resi | 22 ++-- test/ArrayTest.res | 2 +- 18 files changed, 458 insertions(+), 528 deletions(-) diff --git a/src/Tablecloth.res b/src/Tablecloth.res index 4e3a9b1..64868d3 100644 --- a/src/Tablecloth.res +++ b/src/Tablecloth.res @@ -13,7 +13,7 @@ module Int = TableclothInt /** Functions for working with floating point numbers. */ module Float = TableclothFloat -/** 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 /** A fixed lenfth collection of values */ diff --git a/src/TableclothArray.resi b/src/TableclothArray.resi index a0a717f..135f0e4 100644 --- a/src/TableclothArray.resi +++ b/src/TableclothArray.resi @@ -3,13 +3,10 @@ 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> -/** # Create - - You can create an `array` in Rescript with the `[1, 2, 3]` syntax. -*/ /** Create an array with only one element. ## Examples @@ -92,7 +89,6 @@ let fromList: list<'a> => t<'a> */ let clone: t<'a> => t<'a> -/** # Basic operations */ /** Get the element at the specified index. The first element has index number 0. @@ -124,7 +120,7 @@ let get: (t<'a>, int) => '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`. ## Examples @@ -251,7 +247,6 @@ let reverse: t<'a> => unit */ let sort: (t<'a>, ~compare: ('a, 'a) => int) => unit -/** # Query */ /** Check if an array is empty. ## Examples @@ -336,7 +331,7 @@ let find: (t<'a>, ~f: 'a => bool) => option<'a> */ let findIndex: (t<'a>, ~f: (int, 'a) => bool) => option<(int, 'a)> -/** 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. ## Examples @@ -408,7 +403,6 @@ let extent: (t<'a>, ~compare: ('a, 'a) => int) => option<('a, 'a)> */ let sum: (t<'a>, module(TableclothContainer.Sum with type t = 'a)) => 'a -/** # Transform */ /** Create a new array which is the result of applying a function `f` to every element. ## Examples @@ -560,7 +554,7 @@ let flatten: t> => t<'a> 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)` ## Examples @@ -605,7 +599,6 @@ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> */ let map3: (t<'a>, t<'b>, t<'c>, ~f: ('a, 'b, 'c) => 'd) => t<'d> -/** # Deconstruct */ /** 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). ## Examples @@ -664,7 +657,6 @@ let splitWhen: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) */ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) -/** # Iterate */ /** Iterates over the elements of invokes `f` for each element. ## Examples @@ -749,7 +741,6 @@ let chunksOf: (t<'a>, ~size: int) => t> */ let sliding: (~step: int=?, t<'a>, ~size: int) => t> -/** # Convert */ /** Converts an array of strings into a [String](String.mdx#), placing `sep` between each string in the result. ## Examples @@ -803,7 +794,15 @@ let toList: t<'a> => list<'a> */ let toIndexedList: t<'a> => list<(int, 'a)> -/** 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 /** Compare two arrays using the provided `f` function to compare pairs of elements. diff --git a/src/TableclothBool.resi b/src/TableclothBool.resi index 5fff6b5..5846c31 100644 --- a/src/TableclothBool.resi +++ b/src/TableclothBool.resi @@ -20,8 +20,7 @@ */ type t = bool -/** # Create */ -/** Convert an {!Int} into a {!Bool}. +/** Convert an [Int](Int.mdx#) into a [Bool](Bool.mdx#). ## Examples @@ -34,7 +33,7 @@ type t = bool */ let fromInt: int => option -/** Convert a [String](String.mdx#) into a {!Bool}. +/** Convert a [String](String.mdx#) into a [Bool](Bool.mdx#). ## Examples @@ -50,7 +49,6 @@ let fromInt: int => option */ let fromString: string => option -/** # Basic operations */ /** The exclusive or operator. Returns `true` if *exactly one* of its operands is `true`. @@ -66,7 +64,7 @@ let fromString: string => option */ let xor: (bool, bool) => bool -/** Negate a [bool]. +/** Negate a `bool`. ## Examples @@ -77,7 +75,7 @@ let xor: (bool, bool) => bool */ let not: t => bool -/** The logical conjunction [AND] operator. +/** The logical conjunction `AND` operator. Returns `true` if *both* of its operands are `true`. If the 'left' operand evaluates to `false`, the 'right' operand is not evaluated. @@ -93,8 +91,7 @@ let not: t => bool */ let and_: (bool, bool) => bool -/** # Convert */ -/** Convert a [bool] to a [String](String.mdx#) +/** Convert a `bool` to a [String](String.mdx#) ## Examples @@ -105,7 +102,7 @@ let and_: (bool, bool) => bool */ let toString: bool => string -/** Convert a [bool] to an {!Int}. +/** Convert a `bool` to an [Int](Int.mdx#). ## Examples @@ -116,8 +113,7 @@ let toString: bool => string */ let toInt: bool => int -/** {1 Compare} */ -/** Test for the equality of two [bool] values. +/** Test for the equality of two `bool` values. ## Examples @@ -129,7 +125,7 @@ let toInt: bool => int */ let equal: (bool, bool) => bool -/** Compare two [bool] values. +/** Compare two `bool` values. ## Examples diff --git a/src/TableclothChar.resi b/src/TableclothChar.resi index 7dbcdce..61aa1df 100644 --- a/src/TableclothChar.resi +++ b/src/TableclothChar.resi @@ -10,23 +10,15 @@ *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}. + 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 -/** # Create +/** Convert an ASCII [code point](https://en.wikipedia.org/wiki/Code_point) to a character. - You can also create a {!Char} using single quotes: - - ```rescript - let char = 'c' - ``` -*/ -/** Convert an ASCII {{: https://en.wikipedia.org/wiki/Code_point } code point } to a character. - - The full range of extended ASCII is from `0` to [255]. + The full range of extended ASCII is from `0` to `255`. For numbers outside that range, you get `None`. ## Examples @@ -42,7 +34,7 @@ let fromCode: int => option /** 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. ## Examples @@ -131,9 +123,9 @@ let isDigit: char => bool */ let isAlphanumeric: char => bool -/** 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 `'~'`). ## Examples @@ -148,12 +140,12 @@ let isAlphanumeric: char => bool let isPrintable: char => bool /** Detect one of the following characters: - - ['\t'] (tab) - - ['\n'] (newline) - - ['\011'] (vertical tab) - - ['\012'] (form feed) - - ['\r'] (carriage return) - - [' '] (space) + - `'\t'` (tab) + - `'\n'` (newline) + - `'\011'` (vertical tab) + - `'\012'` (form feed) + - `'\r'` (carriage return) + - `' '` (space) ## Examples @@ -190,7 +182,7 @@ let toLowercase: char => char */ let toUppercase: char => char -/** 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). ## Examples @@ -201,7 +193,7 @@ let toUppercase: char => char */ let toCode: char => int -/** Convert a character into a [string]. +/** Convert a character into a `string`. ## Examples @@ -213,28 +205,28 @@ let toCode: char => int */ let toString: char => string -/** 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. ## Examples ```rescript - Char.toDigit("7") == Some(7) - Char.toDigit("0") == Some(0) - Char.toDigit("A") == None - Char.toDigit("") == None + Char.toDigit('7') == Some(7) + Char.toDigit('0') == Some(0) + Char.toDigit('A') == None + Char.toDigit('') == None ``` */ let toDigit: char => option -/** Test two {!Char}s for equality */ +/** Test two [Char](Char.mdx#)s for equality */ let equal: (t, t) => bool -/** Compare two {!Char}s */ +/** Compare two [Char](Char.mdx#)s */ let compare: (t, t) => int -/** 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 9282dd5..fc991d1 100644 --- a/src/TableclothComparator.resi +++ b/src/TableclothComparator.resi @@ -1,6 +1,6 @@ -/** Comparator provide a way for custom data structures to be used with {!Map}s and {!Set}s. +/** Comparator provide a way for custom data structures to be used with [Map](Map.mdx#)s and [Set](Set.mdx#)s. - Say we have a module [Book] which we want to be able to create a {!Set} of + Say we have a module [Book] which we want to be able to create a [Set](Set.mdx#) of ```rescript module Book = { @@ -13,9 +13,9 @@ } ``` - First we need to make our module conform to the {!S} signature. + First we need to make our module conform to the [S](#S) signature. - This can be done by using the {!Make} functor. + This can be done by using the [Make](Make.mdx#) functor. ```rescript module Book = { @@ -44,7 +44,7 @@ ``` */ module type T = { - /** 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 @@ -52,11 +52,11 @@ module type T = { type t<'a, 'identity> -/** 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 = { - /** The output type of {!Make}. */ + /** The output type of [Make](Make.mdx#). */ type t type identity @@ -65,11 +65,11 @@ 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) -/** Create a new comparator by providing a module which satisifies {!T}. +/** Create a new comparator by providing a module which satisifies [T](#T). ## Examples diff --git a/src/TableclothContainer.res b/src/TableclothContainer.res index afebf47..060ef29 100644 --- a/src/TableclothContainer.res +++ b/src/TableclothContainer.res @@ -3,7 +3,7 @@ */ module type Sum = { /** Modules which conform to this signature can be used with functions like - {!Array.sum} or {!List.sum}. + [Array.sum](Array.mdx#sum) or [List.sum](List.mdx#sum). */ type t diff --git a/src/TableclothFloat.resi b/src/TableclothFloat.resi index 73c1fa3..d848075 100644 --- a/src/TableclothFloat.resi +++ b/src/TableclothFloat.resi @@ -1,6 +1,6 @@ -/** A module for working with {{: https://en.wikipedia.org/wiki/Floating-point_arithmetic } floating-point numbers}. +/** A module for working with [ floating-point numbers](https://en.wikipedia.org/wiki/Floating-point_arithmetic). - Valid syntax for [float]s includes: + Valid syntax for `float`s includes: ```rescript 0. 42. @@ -14,24 +14,23 @@ 1e3 // = (1 * 10 ** 3) = 1000. ``` - *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 + *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 -/** {1 Constants} */ -/** The literal [0.0] as a named value. */ +/** The literal `0.0` as a named value. */ let zero: t -/** The literal [1.0] as a named value. */ +/** The literal `1.0` as a named value. */ let one: t -/** [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). - *Note * comparing values with {!Float.nan} will *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) ## Examples @@ -43,7 +42,7 @@ let one: t */ let nan: t -/** 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). ```rescript Float.divide(Float.pi, ~by=0.0) == Float.infinity @@ -51,54 +50,51 @@ let nan: t */ let infinity: t -/** 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 -/** An approximation of {{: https://en.wikipedia.org/wiki/Pi } pi}. */ +/** An approximation of [ pi](https://en.wikipedia.org/wiki/Pi). */ let pi: t /** The smallest interval between two representable numbers. */ let epsilon: t -/** 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 -/** The smallest representable positive [float]. +/** 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 + Has a value of approximately `5E-324`, in browsers and in Node.js is 2^-1074 */ let smallestValue: t /** 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]. + [ 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 /** 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]. + [ 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 -/** # Create */ -/** Convert an {!Int} to a [float]. +/** Convert an [Int](Int.mdx#) to a `float`. ## Examples @@ -110,9 +106,8 @@ let minimumSafeInteger: t */ let fromInt: int => t -/** Convert a [String](String.mdx#) to a [float]. - The behaviour of this function is platform specific. - Parses [Infinity] case-sensitive, [NaN] is case-insensitive. +/** Convert a [String](String.mdx#) to a `float`. + Parses `Infinity` case-sensitive, `NaN` is case-insensitive. ## Examples @@ -127,22 +122,21 @@ let fromInt: int => t */ let fromString: string => option -/** {1 Basic arithmetic and operators} */ /** Addition for floating point numbers. - 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} 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 + So if you needed to add a [Array.length](Array.mdx#length) to a `float` for some reason, you could: ```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 + 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. @@ -200,7 +194,7 @@ let divide: (t, ~by: t) => t */ let power: (~base: t, ~exponent: t) => t -/** 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. ## Examples @@ -212,7 +206,7 @@ let power: (~base: t, ~exponent: t) => t */ let negate: t => t -/** 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. ## Examples @@ -224,9 +218,9 @@ let negate: t => t */ let absolute: t => t -/** 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` ## Examples @@ -238,9 +232,9 @@ let absolute: t => t */ let maximum: (t, t) => t -/** 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`. ## Examples @@ -252,11 +246,11 @@ let maximum: (t, t) => t */ let minimum: (t, t) => t -/** Clamps `n` within the inclusive [lower] and [upper] bounds. +/** Clamps `n` within the inclusive `lower` and `upper` bounds. ### Exceptions - Throws an `Invalid_argument` exception if [lower > upper]. + Throws an `Invalid_argument` exception if `lower > upper`. ## Examples @@ -268,10 +262,9 @@ let minimum: (t, t) => t */ let clamp: (t, ~lower: t, ~upper: t) => t -/** {1 Fancier math} */ /** 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. ## Examples @@ -293,10 +286,9 @@ let squareRoot: t => t */ let log: (t, ~base: t) => t -/** # Query */ -/** Determine whether a [float] is an [undefined] or unrepresentable number. +/** 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]: + *Note:* this function is more useful than it might seem since `NaN` *does not* equal `NaN`: ```rescript (Float.nan == Float.nan) == false @@ -313,9 +305,9 @@ let log: (t, ~base: t) => t */ let isNaN: t => bool -/** 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! ## Examples @@ -354,7 +346,7 @@ let isInfinite: t => bool */ let isInteger: t => bool -/** 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). ## Examples @@ -366,13 +358,13 @@ let isInteger: t => bool */ let isSafeInteger: t => bool -/** 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`. ### Exceptions - Throws an `Invalid_argument` exception if [lower > upper] + Throws an `Invalid_argument` exception if `lower > upper` ## Examples @@ -384,7 +376,6 @@ let isSafeInteger: t => bool */ let inRange: (t, ~lower: t, ~upper: t) => bool -/** {1 Angles} */ /** This type is just an alias for [float]. Its purpose is to make understanding the signatures of the following @@ -392,7 +383,7 @@ let inRange: (t, ~lower: t, ~upper: t) => bool */ type radians = float -/** [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)`. ## Examples @@ -402,7 +393,7 @@ type radians = float */ let hypotenuse: (t, t) => t -/** 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). ## Examples @@ -414,9 +405,9 @@ let hypotenuse: (t, t) => t */ let degrees: t => radians -/** 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). - *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. ## Examples @@ -426,7 +417,7 @@ let degrees: t => radians */ let radians: t => radians -/** 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. @@ -439,8 +430,7 @@ let radians: t => radians */ let turns: t => radians -/** {1 Polar coordinates} */ -/** 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)`. ## Examples @@ -450,7 +440,7 @@ let turns: t => radians */ let fromPolar: ((float, radians)) => (float, float) -/** 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)`. ## Examples @@ -462,7 +452,7 @@ let fromPolar: ((float, radians)) => (float, float) */ let toPolar: ((float, float)) => (float, radians) -/** 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). ## Examples @@ -473,7 +463,7 @@ let toPolar: ((float, float)) => (float, radians) */ let cos: radians => t -/** 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): ## Examples @@ -483,7 +473,7 @@ let cos: radians => t */ let acos: radians => t -/** 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). ## Examples @@ -494,7 +484,7 @@ let acos: radians => t */ let sin: radians => t -/** 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): ## Examples @@ -516,19 +506,19 @@ let asin: radians => t */ let tan: radians => t -/** This helps you find the angle (in radians) to an [(x, y)] coordinate, but +/** This helps you find the angle (in radians) to an `(x, y)` coordinate, but in a way that is rarely useful in programming. - *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 + 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 + 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! + [Float.atan2](Float.mdx#atan2) instead! ## Examples @@ -541,9 +531,9 @@ let tan: radians => t */ let atan: t => radians -/** 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: ## Examples @@ -556,10 +546,9 @@ let atan: t => radians */ let atan2: (~y: t, ~x: t) => radians -/** {1 Rounding} */ -/** The possible [direction]s availible when doing {!Float.round}. +/** The possible `direction`s availible when doing [Float.round](Float.mdx#round). - See {!Float.round} for what each variant represents. + See [Float.round](Float.mdx#round) for what each variant represents. */ type direction = [ | #Zero @@ -569,9 +558,9 @@ type direction = [ | #Closest([#Zero | #AwayFromZero | #Up | #Down | #ToEven]) ] -/** 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. ## Examples @@ -584,7 +573,7 @@ type direction = [ Float.round(-1.8) == -2.0 ``` - {3 Towards zero} + ### Towards zero ```rescript Float.round(1.2, ~direction=#Zero) == 1.0 @@ -595,7 +584,7 @@ type direction = [ Float.round(-1.8, ~direction=#Zero) == -1.0 ``` - {3 Away from zero} + ### Away from zero ```rescript Float.round(1.2, ~direction=#AwayFromZero) == 2.0 @@ -606,9 +595,9 @@ type direction = [ 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). ```rescript Float.round(1.2, ~direction=#Up) == 2.0 @@ -619,9 +608,9 @@ type direction = [ 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). ```rescript Array.map( @@ -630,11 +619,11 @@ type direction = [ ) == [-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]. - {3 Halves rounded towards zero} + ### Halves rounded towards zero ```rescript Array.map( @@ -643,7 +632,7 @@ type direction = [ ) == [-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 *commercial rounding*. @@ -654,7 +643,7 @@ type direction = [ ) == [-2.0, -2.0, -1.0, 1.0, 2.0, 2.0] ``` - {3 Halves rounded down} + ### Halves rounded down ```rescript Array.map( @@ -663,13 +652,13 @@ type direction = [ ) == [-2.0, -2.0, -1.0, 1.0, 1.0, 2.0] ``` - {3 Halves rounded up} + ### Halves rounded up 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 ```rescript Float.round(-1.5, ~direction=#Closest(#ToEven)) == -2.0 @@ -678,7 +667,7 @@ type direction = [ */ let round: (~direction: direction=?, t) => t -/** Floor function, equivalent to [Float.round(~direction=#Down)]. +/** Floor function, equivalent to `Float.round(~direction=#Down)`. ## Examples @@ -693,7 +682,7 @@ let round: (~direction: direction=?, t) => t */ let floor: t => t -/** Ceiling function, equivalent to [Float.round(~direction=#Up)]. +/** Ceiling function, equivalent to `Float.round(~direction=#Up)`. ## Examples @@ -708,7 +697,7 @@ let floor: t => t */ let ceiling: t => t -/** Ceiling function, equivalent to [Float.round(~direction=#Zero)]. +/** Ceiling function, equivalent to `Float.round(~direction=#Zero)`. ## Examples @@ -724,12 +713,11 @@ let ceiling: t => t */ let truncate: t => t -/** # Convert */ -/** Converts a [float] to an {!Int} by *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. ## Examples @@ -744,14 +732,13 @@ let truncate: t => t */ let toInt: t => option -/** Convert a [float] to a [String](String.mdx#) +/** 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. */ let toString: t => string -/** {1 Compare} */ /** Test two floats for equality. */ let equal: (t, t) => bool diff --git a/src/TableclothFun.resi b/src/TableclothFun.resi index 7f02d74..d718fe4 100644 --- a/src/TableclothFun.resi +++ b/src/TableclothFun.resi @@ -11,7 +11,7 @@ Array.initialize(6, ~f=Fun.identity) == [0, 1, 2, 3, 4, 5] ``` - (In this particular case you probably want to use {!Array.range}.) + (In this particular case you probably want to use [Array.range](Array.mdx#range).) Or maybe you need to register a callback, but dont want to do anything: @@ -24,10 +24,10 @@ */ external identity: 'a => 'a = "%identity" -/** 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, + or to avoid `unused value` compiler warnings when you really meant it, and haven't just made a mistake. ## Examples @@ -52,7 +52,7 @@ external ignore: _ => unit = "%ignore" /** 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). ## Examples @@ -68,7 +68,7 @@ let sequence: ('a, 'b) => 'b /** 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. @@ -77,7 +77,7 @@ let flip: (('a, 'b) => 'c, 'b, 'a) => 'c /** 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). ## Examples @@ -90,16 +90,16 @@ let negate: ('a => bool, 'a) => bool /** 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 /** Function composition, passing result from left to right. This is usefull in cases when you want to make multiple transformations - during a [map] operation. + during a `map` operation. ## Examples @@ -115,10 +115,10 @@ let compose: ('a, 'a => 'b, 'b => 'c) => 'c /** 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. + during a `map` operation. ## Examples @@ -132,7 +132,7 @@ let compose: ('a, 'a => 'b, 'b => 'c) => 'c */ let composeRight: ('a, 'b => 'c, 'a => 'b) => 'c -/** 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. @@ -170,7 +170,7 @@ let forever: (unit => unit) => exn */ let times: (int, ~f: unit => unit) => unit -/** 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. ## Examples @@ -195,8 +195,8 @@ let curry: ((('a, 'b)) => 'c, 'a, 'b) => 'c */ let uncurry: (('a, 'b) => 'c, ('a, 'b)) => 'c -/** 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 -/** 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 9e32894..69013bb 100644 --- a/src/TableclothInt.resi +++ b/src/TableclothInt.resi @@ -1,15 +1,15 @@ -/** An [int] is a whole number. +/** An `int` is a whole number. - 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] + 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] - [int]s are subject to {{: https://en.wikipedia.org/wiki/Integer_overflow } overflow }, meaning that [Int.maximumValue + 1 == Int.minimumValue]. + `int`s are subject to [ overflow ](https://en.wikipedia.org/wiki/Integer_overflow), meaning that `Int.maximumValue + 1 == Int.minimumValue`. - 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. + 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. - Valid syntax for [int]s includes: + Valid syntax for `int`s includes: ```rescript 0 42 @@ -20,28 +20,26 @@ 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. + ~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 -/** {1 Constants } */ /** The literal `0` as a named value. */ let zero: t -/** The literal [1] as a named value. */ +/** The literal `1` as a named value. */ let one: t -/** The maximum representable [int] on the current platform. */ +/** The maximum representable `int` on the current platform. */ let maximumValue: t -/** The minimum representable [int] on the current platform. */ +/** The minimum representable `int` on the current platform. */ let minimumValue: t -/** # Create */ -/** Attempt to parse a [string] into a [int]. +/** Attempt to parse a `string` into a `int`. ## Examples @@ -58,12 +56,11 @@ let minimumValue: t */ let fromString: string => option -/** {1 Operators} */ -/** 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. ## Examples @@ -83,7 +80,7 @@ let add: (t, t) => t */ let subtract: (t, t) => t -/** Multiply [int]s. +/** Multiply `int`s. ## Examples @@ -143,7 +140,7 @@ let power: (~base: t, ~exponent: t) => t */ let negate: t => t -/** 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. ## Examples @@ -155,15 +152,15 @@ let negate: t => t */ let absolute: t => t -/** Perform {{: https://en.wikipedia.org/wiki/Modular_arithmetic } modular arithmetic }. +/** Perform [ modular arithmetic ](https://en.wikipedia.org/wiki/Modular_arithmetic). - *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. ## Examples @@ -181,13 +178,13 @@ let absolute: t => t */ let modulo: (t, ~by: t) => t -/** 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]). + of the dividend (`~by`) while with a [modulo](#modulo) the sign + of the result is the same as the divisor (`t`). ## Examples @@ -198,7 +195,7 @@ let modulo: (t, ~by: t) => t */ let remainder: (t, ~by: t) => t -/** Returns the larger of two [int]s. +/** Returns the larger of two `int`s. ## Examples @@ -209,7 +206,7 @@ let remainder: (t, ~by: t) => t */ let maximum: (t, t) => t -/** Returns the smaller of two [int]s. +/** Returns the smaller of two `int`s. ## Examples @@ -220,8 +217,7 @@ let maximum: (t, t) => t */ let minimum: (t, t) => t -/** # Query */ -/** Check if an [int] is even. +/** Check if an `int` is even. ## Examples @@ -233,7 +229,7 @@ let minimum: (t, t) => t */ let isEven: t => bool -/** Check if an [int] is odd. +/** Check if an `int` is odd. ## Examples @@ -245,11 +241,11 @@ let isEven: t => bool */ let isOdd: t => bool -/** Clamps `n` within the inclusive [lower] and [upper] bounds. +/** Clamps `n` within the inclusive `lower` and `upper` bounds. ### Exceptions - Throws an `Invalid_argument` exception if [lower > upper] + Throws an `Invalid_argument` exception if `lower > upper` ## Examples @@ -261,11 +257,11 @@ let isOdd: t => bool */ let clamp: (t, ~lower: t, ~upper: t) => t -/** 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`. ### Exceptions - Throws an `Invalid_argument` exception if [lower > upper] + Throws an `Invalid_argument` exception if `lower > upper` ## Examples @@ -278,8 +274,7 @@ let clamp: (t, ~lower: t, ~upper: t) => t */ let inRange: (t, ~lower: t, ~upper: t) => bool -/** # Convert */ -/** Convert an [int] into a [float]. Useful when mixing {!Int} and {!Float} values like this: +/** Convert an `int` into a `float`. Useful when mixing [Int](Int.mdx#) and [Float](Float.mdx#) values like this: ## Examples @@ -291,7 +286,7 @@ let inRange: (t, ~lower: t, ~upper: t) => bool */ let toFloat: t => float -/** Convert an [int] into a [string] representation. +/** Convert an `int` into a `string` representation. Guarantees that @@ -309,14 +304,13 @@ let toFloat: t => float */ let toString: t => string -/** {1 Compare} */ -/** Test two [int]s for equality. */ +/** Test two `int`s for equality. */ let equal: (t, t) => bool -/** Compare two [int]s. */ +/** Compare two `int`s. */ let compare: (t, t) => int -/** 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 3aa5e61..2de18a6 100644 --- a/src/TableclothList.resi +++ b/src/TableclothList.resi @@ -1,11 +1,11 @@ /** 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} - - Getting the {!tail} - - Creating a new list by adding an element to the front using {!cons} + 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: @@ -22,16 +22,12 @@ - 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. + 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}. + If those are important to your use-case, perhaps you need an [Array](Array.mdx#). */ type t<'a> = list<'a> -/** # Create - - You can create a [list] with the [list{1, 2, 3}] syntax. -*/ /** An empty list. ## Examples @@ -54,7 +50,7 @@ let empty: t<'a> */ let singleton: 'a => t<'a> -/** 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. ## Examples @@ -80,7 +76,7 @@ let range: (~from: int=?, int) => t /** 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)`. ## Examples @@ -91,7 +87,7 @@ let range: (~from: int=?, int) => t */ let initialize: (int, ~f: int => 'a) => t<'a> -/** Create a list from an {!Array}. +/** Create a list from an [Array](Array.mdx#). ## Examples @@ -101,7 +97,6 @@ let initialize: (int, ~f: int => 'a) => t<'a> */ let fromArray: array<'a> => t<'a> -/** # Basic operations */ /** Returns, as an [Option](Option.mdx#), the first element of a list. If the list is empty, returns `None`. @@ -131,7 +126,7 @@ let tail: t<'a> => option> /** 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. ## Examples @@ -145,11 +140,11 @@ let tail: t<'a> => option> */ let cons: (t<'a>, 'a) => t<'a> -/** 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{}`. ## Examples @@ -174,9 +169,9 @@ let take: (t<'a>, ~count: int) => t<'a> */ let takeWhile: (t<'a>, ~f: 'a => bool) => t<'a> -/** 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. @@ -248,7 +243,7 @@ let getAt: (t<'a>, ~index: int) => option<'a> /** 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: @@ -319,8 +314,8 @@ let reverse: t<'a> => t<'a> let sort: (t<'a>, ~compare: ('a, 'a) => int) => t<'a> /** - [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, + `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} @@ -328,7 +323,6 @@ let sort: (t<'a>, ~compare: ('a, 'a) => int) => t<'a> */ let sortBy: (t<'a>, ~f: 'a => 'b) => t<'a> -/** # Query */ /** Determine if a list is empty. ## Examples @@ -343,9 +337,9 @@ let isEmpty: t<_> => bool /** Return the number of elements in a list. - *Warning* [List.length] needs to access the *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: @@ -424,11 +418,11 @@ let all: (t<'a>, ~f: 'a => bool) => bool let count: (t<'a>, ~f: 'a => bool) => int /** - [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. ## Examples @@ -441,7 +435,7 @@ let count: (t<'a>, ~f: 'a => bool) => int */ let uniqueBy: (list<'a>, ~f: 'a => string) => list<'a> -/** 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`. @@ -457,7 +451,7 @@ let find: (t<'a>, ~f: 'a => bool) => option<'a> /** 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`. ## Examples @@ -470,10 +464,10 @@ let find: (t<'a>, ~f: 'a => bool) => option<'a> */ let findIndex: (t<'a>, ~f: (int, 'a) => bool) => option<(int, 'a)> -/** 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. + repeatedly perform this check, maybe you want a [Set](Set.mdx#) instead. ## Examples @@ -486,14 +480,14 @@ let findIndex: (t<'a>, ~f: (int, 'a) => bool) => option<(int, 'a)> let includes: (t<'a>, 'a, ~equal: ('a, 'a) => bool) => bool /** - [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]. + that can be compared: for example, a `string` or `int`. ## Examples @@ -507,14 +501,14 @@ let includes: (t<'a>, 'a, ~equal: ('a, 'a) => bool) => bool let minimumBy: (~f: 'a => 'comparable, list<'a>) => option<'a> /** - [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]. + that can be compared: for example, a `string` or `int`. ## Examples @@ -551,7 +545,7 @@ let minimum: (t<'a>, ~compare: ('a, 'a) => int) => option<'a> */ let maximum: (t<'a>, ~compare: ('a, 'a) => int) => option<'a> -/** 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. @@ -585,7 +579,6 @@ let extent: (t<'a>, ~compare: ('a, 'a) => int) => option<('a, 'a)> */ let sum: (t<'a>, module(TableclothContainer.Sum with type t = 'a)) => 'a -/** # Transform */ /** Create a new list which is the result of applying a function `f` to every element. ## Examples @@ -618,17 +611,17 @@ let mapWithIndex: (t<'a>, ~f: (int, 'a) => 'b) => t<'b> */ let filter: (t<'a>, ~f: 'a => bool) => t<'a> -/** 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> -/** 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`. - Why [filterMap] and not just {!filter} then {!map}? + Why `filterMap` and not just [filter](#filter) then [map](#map)? - {!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. + [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. ## Examples @@ -643,7 +636,7 @@ let filterWithIndex: (t<'a>, ~f: (int, 'a) => bool) => t<'a> */ let filterMap: (t<'a>, ~f: 'a => option<'b>) => t<'b> -/** 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. ## Examples @@ -675,7 +668,7 @@ let flatMap: (t<'a>, ~f: 'a => t<'b>) => t<'b> + [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)) *Examples continued* @@ -694,12 +687,9 @@ let flatMap: (t<'a>, ~f: 'a => t<'b>) => t<'b> */ 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 -/** {1 Combine} */ /** Creates a new list which is the result of appending the second list onto the end of the first. ## Examples @@ -722,11 +712,11 @@ let append: (t<'a>, t<'a>) => t<'a> */ let flatten: t> => t<'a> -/** 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. - The same as [List.map2(~f=Tuple2.make)]. + The same as `List.map2(~f=Tuple2.make)`. ## Examples @@ -771,8 +761,7 @@ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> */ let map3: (t<'a>, t<'b>, t<'c>, ~f: ('a, 'b, 'c) => 'd) => t<'d> -/** # Deconstruct */ -/** Split a list into a {!Tuple2} of lists. Values which `f` returns true for will end up in {!Tuple2.first}. +/** 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). ## Examples @@ -782,7 +771,7 @@ let map3: (t<'a>, t<'b>, t<'c>, ~f: ('a, 'b, 'c) => 'd) => t<'d> */ let partition: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) -/** 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. @@ -802,7 +791,7 @@ let partition: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) */ let splitAt: (t<'a>, ~index: int) => (t<'a>, t<'a>) -/** 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 @@ -817,7 +806,7 @@ let splitAt: (t<'a>, ~index: int) => (t<'a>, t<'a>) */ let splitWhen: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) -/** Decompose a list of {!Tuple2} into a {!Tuple2} of lists. +/** Decompose a list of [Tuple2](Tuple2.mdx#) into a [Tuple2](Tuple2.mdx#) of lists. ## Examples @@ -828,10 +817,9 @@ let splitWhen: (t<'a>, ~f: 'a => bool) => (t<'a>, t<'a>) */ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) -/** # Iterate */ /** 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. @@ -849,7 +837,7 @@ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) */ let forEach: (t<'a>, ~f: 'a => unit) => unit -/** Like {!forEach} but `f` is also called with the elements index. +/** Like [forEach](#forEach) but `f` is also called with the elements index. ## Examples @@ -933,7 +921,6 @@ let sliding: (~step: int=?, t<'a>, ~size: int) => t> */ let groupWhile: (t<'a>, ~f: ('a, 'a) => bool) => t> -/** # Convert */ /** Converts a list of strings into a [String](String.mdx#), placing `sep` between each string in the result. ## Examples @@ -962,10 +949,9 @@ let groupBy: ( ~f: 'value => 'key, ) => TableclothMap.t<'key, list<'value>, 'id> -/** Converts a list to an {!Array}. */ +/** Converts a list to an [Array](Array.mdx#). */ let toArray: t<'a> => array<'a> -/** {1 Compare} */ /** Test two lists for equality using the provided function to test elements. */ let equal: (t<'a>, t<'a>, ('a, 'a) => bool) => bool diff --git a/src/TableclothMap.resi b/src/TableclothMap.resi index 7187245..2711600 100644 --- a/src/TableclothMap.resi +++ b/src/TableclothMap.resi @@ -1,10 +1,14 @@ -/** A [Map] represents a unique mapping from keys to values. +/** A `Map` represents a unique mapping from keys to values. - [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. + `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. - 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. + 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. - Custom data types can be used with maps as long as the module satisfies the {!Comparator.S} interface. + 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). + + 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. + + Custom data types can be used with maps as long as the module satisfies the [Comparator.S](Comparator.mdx#S) interface. ```rescript module Point = { @@ -27,19 +31,13 @@ ) ``` - See the {!Comparator} module for a more details. + See the [Comparator](Comparator.mdx#) module for a more details. */ type t<'key, 'value, 'cmp> = Belt.Map.t<'key, 'value, 'cmp> -/** # Create - - You can create sets of modules types which 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. -*/ /** A map with nothing in it. - Often used as an intial value for functions like {!Array.fold}. + Often used as an intial value for functions like [Array.fold](Array.mdx#fold). ## Examples @@ -51,7 +49,7 @@ type t<'key, 'value, 'cmp> = Belt.Map.t<'key, 'value, 'cmp> [(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> @@ -69,7 +67,7 @@ let singleton: ( ~value: 'value, ) => t<'key, 'value, 'identity> -/** 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)>, @@ -81,8 +79,7 @@ let fromList: ( list<('key, 'value)>, ) => t<'key, 'value, 'identity> -/** # Basic operations */ -/** Adds a new entry to a map. If [key] is allready present, its previous value is replaced with `value`. +/** Adds a new entry to a map. If `key` is allready present, its previous value is replaced with `value`. ## Examples @@ -135,7 +132,7 @@ let remove: (t<'key, 'value, 'id>, 'key) => t<'key, 'value, 'id> */ let get: (t<'key, 'value, 'id>, 'key) => option<'value> -/** Update the value for a specific key using `f`. If [key] is not present in the map `f` will be called with `None`. +/** Update the value for a specific key using `f`. If `key` is not present in the map `f` will be called with `None`. ## Examples @@ -168,7 +165,6 @@ let update: ( ~f: option<'value> => option<'value>, ) => t<'key, 'value, 'id> -/** # Query */ /** Determine if a map is empty. */ let isEmpty: t<_, _, _> => bool @@ -208,10 +204,10 @@ let all: (t<_, 'value, _>, ~f: 'value => bool) => bool */ let find: (t<'key, 'value, _>, ~f: (~key: 'key, ~value: 'value) => bool) => option<('key, 'value)> -/** Determine if a map includes [key]. */ +/** Determine if a map includes `key`. */ let includes: (t<'key, _, _>, 'key) => bool -/** Returns, as an [Option](Option.mdx#), the smallest *key * in the map. +/** Returns, as an [Option](Option.mdx#), the smallest *key* in the map. Returns `None` if the map is empty. @@ -224,7 +220,7 @@ let includes: (t<'key, _, _>, 'key) => bool */ let minimum: t<'key, _, _> => option<'key> -/** Returns the largest *key * in the map. +/** Returns the largest *key* in the map. Returns `None` if the map is empty. @@ -237,7 +233,7 @@ let minimum: t<'key, _, _> => option<'key> */ let maximum: t<'key, _, _> => option<'key> -/** Returns, as an [Option](Option.mdx#), a {!Tuple2} of the [(minimum, maximum)] *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. @@ -250,7 +246,6 @@ let maximum: t<'key, _, _> => option<'key> */ let extent: t<'key, _, _> => option<('key, 'key)> -/** {1 Combine} */ /** Combine two maps. You provide a function `f` which is provided the key and the optional @@ -288,7 +283,6 @@ let merge: ( ~f: ('key, option<'v1>, option<'v2>) => option<'v3>, ) => t<'key, 'v3, 'id> -/** # Transform */ /** Apply a function to all values in a dictionary. ## Examples @@ -301,7 +295,7 @@ let merge: ( */ let map: (t<'key, 'value, 'id>, ~f: 'value => 'b) => t<'key, 'b, 'id> -/** 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> /** Keep elements that `f` returns `true` for. @@ -317,7 +311,7 @@ let mapWithIndex: (t<'key, 'value, 'id>, ~f: ('key, 'value) => 'b) => t<'key, 'b */ let filter: (t<'key, 'value, 'id>, ~f: 'value => bool) => t<'key, 'value, 'id> -/** 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`. */ @@ -349,17 +343,15 @@ let partition: ( ~f: (~key: 'key, ~value: 'value) => bool, ) => (t<'key, 'value, 'id>, t<'key, 'value, 'id>) -/** 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 -/** # Iterate */ /** Runs a function `f` against each *value* in the map. */ let forEach: (t<_, 'value, _>, ~f: 'value => unit) => unit -/** 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 -/** # Convert */ /** Get a [List](List.mdx#) of all of the keys in a map. ## Examples @@ -392,15 +384,13 @@ let keys: t<'key, _, _> => list<'key> */ let values: t<_, 'value, _> => list<'value> -/** 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)> /** 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 @@ -419,14 +409,14 @@ module Poly: { */ let singleton: (~key: 'key, ~value: 'value) => t<'key, 'value> - /** 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> /** Create a map from a [List](List.mdx#) of key-value tuples. */ let fromList: list<('key, 'value)> => t<'key, 'value> } -/** Construct a Map with {!Int}s for keys. */ +/** Construct a Map with [Int](Int.mdx#)s for keys. */ module Int: { type identity @@ -445,7 +435,7 @@ module Int: { */ let singleton: (~key: int, ~value: 'value) => t<'value> - /** 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> /** Create a map of a [List](List.mdx#) of key-value tuples. */ @@ -471,7 +461,7 @@ module String: { */ let singleton: (~key: string, ~value: 'value) => t<'value> - /** 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> /** Create a map from a [List](List.mdx#) of key-value tuples. */ diff --git a/src/TableclothOption.resi b/src/TableclothOption.resi index e3a8756..3f4db0e 100644 --- a/src/TableclothOption.resi +++ b/src/TableclothOption.resi @@ -1,6 +1,6 @@ /** [Option](Option.mdx#) 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> = @@ -8,7 +8,7 @@ | 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 @@ -17,15 +17,15 @@ - 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 + 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} or {!andThen} - - Unwrapping it using {!unwrap} - - Converting a `None` into an exception using{!unwrapUnsafe} + - Using [map](#map) or [andThen](#andThen) + - Unwrapping it using [unwrap](#unwrap) + - Converting a `None` into an exception using[unwrapUnsafe](#unwrapUnsafe) - If the function you are writing can fail in a variety of ways, use a {!Result} instead to + 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. @@ -36,9 +36,9 @@ type t<'a> = option<'a> In most situations you just want to use the `Some` constructor directly. - Note that when using the Rescript syntax you *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. ## Examples @@ -51,9 +51,9 @@ let some: 'a => option<'a> /** 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. ## Examples @@ -66,10 +66,10 @@ let some: 'a => option<'a> */ let and_: (t<'a>, t<'a>) => t<'a> -/** 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. ## Examples @@ -82,9 +82,9 @@ let and_: (t<'a>, t<'a>) => t<'a> */ let or_: (t<'a>, t<'a>) => t<'a> -/** 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 ## Examples @@ -97,7 +97,7 @@ let or_: (t<'a>, t<'a>) => t<'a> */ let orElse: (t<'a>, t<'a>) => t<'a> -/** 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. @@ -184,9 +184,9 @@ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> Int.fromString(userInput)->Option.andThen(~f=toValidMonth) ``` - If [Int.fromString] produces `None` (because the [userInput] was not an + 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 + `None`. If `toValidMonth` results in `None`, again the chain of computations will result in `None`. ## Examples @@ -198,12 +198,12 @@ let map2: (t<'a>, t<'b>, ~f: ('a, 'b) => 'c) => t<'c> */ let andThen: (t<'a>, ~f: 'a => t<'b>) => t<'b> -/** 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](Option.mdx#). + 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#). - *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). ## Examples @@ -215,9 +215,9 @@ let andThen: (t<'a>, ~f: 'a => t<'b>) => t<'b> */ let unwrap: (t<'a>, ~default: 'a) => 'a -/** Unwrap an [option('a)] returning the enclosed ['a]. +/** Unwrap an `option<'a>` returning the enclosed `'a`. - *Note* in most situations it is better to use pattern matching, {!unwrap}, {!map} or {!andThen}. + *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? ### Exceptions @@ -259,7 +259,7 @@ let isSome: t<'a> => bool */ let isNone: t<'a> => bool -/** Run a function against an [Some(value)], ignores `None`s. +/** Run a function against an `Some(value)`, ignores `None`s. ## Examples @@ -270,7 +270,7 @@ let isNone: t<'a> => bool */ let tap: (t<'a>, ~f: 'a => unit) => unit -/** 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. @@ -296,7 +296,6 @@ let toArray: t<'a> => array<'a> */ let toList: t<'a> => list<'a> -/** {1 Compare} */ /** Test two optional values for equality using the provided function. ## Examples diff --git a/src/TableclothResult.resi b/src/TableclothResult.resi index 0dddd67..3f0095a 100644 --- a/src/TableclothResult.resi +++ b/src/TableclothResult.resi @@ -1,7 +1,7 @@ -/** A {!Result} is used to represent a computation which may fail. +/** A [Result](Result.mdx#) is used to represent a computation which may fail. - A [Result] is a variant, which has a constructor for successful results - [Ok('ok)], and one for unsuccessful results ([Error('error)]). + A [Result](Result.mdx#) is a variant, which has a constructor for successful results + `Ok('ok)`, and one for unsuccessful results `[Error('error)]`. ```rescript type t<'ok, 'error> = @@ -9,7 +9,7 @@ | Error('error) ``` - Here is how you would annotate a [Result] variable whose [Ok] + Here is how you would annotate a [Result](Result.mdx#) variable whose `Ok` variant is an integer and whose `Error` variant is a string: ```rescript @@ -17,18 +17,17 @@ let error: Result.t = Error("This computation failed!") ``` - *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 {{: https://dev.to/kevanstannard/exploring-rescript-exception-handling-57o3 } this excellent article} for more information on this approach. + *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> -/** # Create */ -/** 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). ## Examples @@ -40,17 +39,17 @@ type t<'ok, 'error> = result<'ok, 'error> let ok: 'ok => t<'ok, 'error> /** 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}. + the constructor isn't permitted such as at the of a [Fun.pipe](Fun.mdx#pipe) or functions like [List.map](List.mdx#map). *Note* - In Rescript you *can* use constructors with the fast pipe ([->]). + In Rescript you *can* use constructors with the fast pipe (`->`). ```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. ## Examples @@ -61,7 +60,7 @@ let ok: 'ok => t<'ok, 'error> */ let error: 'error => t<'ok, 'error> -/** 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. ## Examples @@ -76,7 +75,7 @@ let error: 'error => t<'ok, 'error> */ let attempt: (unit => 'ok) => t<'ok, exn> -/** Convert an [Option](Option.mdx#) 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)`. ## Examples @@ -88,15 +87,15 @@ let attempt: (unit => 'ok) => t<'ok, exn> */ let fromOption: (option<'ok>, ~error: 'error) => t<'ok, 'error> -/** 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. + an `Ok` like logging. - *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) ## Examples @@ -107,15 +106,15 @@ let fromOption: (option<'ok>, ~error: 'error) => t<'ok, 'error> */ let isOk: t<_, _> => bool -/** 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. - *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) ## Examples @@ -126,10 +125,10 @@ let isOk: t<_, _> => bool */ let isError: t<_, _> => bool -/** 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. ## Examples @@ -148,10 +147,10 @@ let isError: t<_, _> => bool */ let and_: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> -/** 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. ## Examples @@ -166,29 +165,37 @@ let and_: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> */ let or_: (t<'ok, 'error>, t<'ok, 'error>) => t<'ok, 'error> -/** 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 ## Examples - ```rescriptResult.orElse (Ok "Boar") (Ok "Gecko") = (Ok "Gecko")``` + ```rescript + Result.orElse (Ok "Boar") (Ok "Gecko") = (Ok "Gecko") + ``` - ```rescriptResult.orElse (Error (`UnexpectedInvertabrate "Periwinkle")) (Ok "Gecko") = (Ok "Gecko")``` + ```rescript + Result.orElse (Error (`UnexpectedInvertabrate "Periwinkle")) (Ok "Gecko") = (Ok "Gecko") + ``` - ```rescriptResult.orElse (Ok "Boar") (Error (`UnexpectedInvertabrate "Periwinkle")) = (Ok "Boar") ``` + ```rescript + Result.orElse (Ok "Boar") (Error (`UnexpectedInvertabrate "Periwinkle")) = (Ok "Boar") + ``` - ```rescriptResult.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> -/** 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`. - The same as writing [Result.map2(~f=Tuple2.make)]. + The same as writing `Result.map2(~f=Tuple2.make)`. ## Examples @@ -225,7 +232,7 @@ let both: (t<'a, 'error>, t<'b, 'error>) => t<('a, 'b), 'error> */ let flatten: t, 'error> => t<'ok, 'error> -/** Unwrap a Result using the [~default] value in case of an `Error`. +/** Unwrap a Result using the `~default` value in case of an `Error`. ## Examples @@ -236,13 +243,17 @@ let flatten: t, 'error> => t<'ok, 'error> */ let unwrap: (t<'ok, 'error>, ~default: 'ok) => 'ok -/** 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` ## Examples - ```rescriptResult.unwrapLazy ~default:(lazy 0) (Ok 12) = 12``` + ```rescript + Result.unwrapLazy ~default:(lazy 0) (Ok 12) = 12 + ``` - ```rescriptResult.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 @@ -250,7 +261,7 @@ let unwrapLazy: (t<'ok, 'error>, ~default: Lazy.t<'ok>) => 'ok ### Exceptions - Raises an [Not_found] exception. + Raises an `Not_found` exception. ## Examples @@ -261,7 +272,7 @@ let unwrapLazy: (t<'ok, 'error>, ~default: Lazy.t<'ok>) => 'ok */ let unwrapUnsafe: t<'ok, _> => 'ok -/** Like {!Result.unwrap} but unwraps an `Error` value instead. +/** Like [Result.unwrap](Result.mdx#unwrap) but unwraps an `Error` value instead. ## Examples @@ -294,7 +305,7 @@ let unwrapError: (t<'ok, 'error>, ~default: 'error) => 'error */ let map2: (t<'a, 'error>, t<'b, 'error>, ~f: ('a, 'b) => 'c) => t<'c, 'error> -/** 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 *any* of the elements are an `Error`, the first one encountered is returned. @@ -308,13 +319,13 @@ let map2: (t<'a, 'error>, t<'b, 'error>, ~f: ('a, 'b) => 'c) => t<'c, 'error> let values: list> => t, 'error> /** - [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`. ## Examples @@ -325,7 +336,7 @@ let values: list> => t, 'error> */ let combine: list> => result, 'error> -/** Transforms the ['ok] in a result using `f`. Leaves the ['error] untouched. +/** Transforms the `'ok` in a result using `f`. Leaves the `'error` untouched. ## Examples @@ -336,7 +347,7 @@ let combine: list> => result, 'error> */ let map: (t<'a, 'error>, ~f: 'a => 'b) => t<'b, 'error> -/** Transforms the value in an `Error` using `f`. Leaves an [Ok] untouched. +/** Transforms the value in an `Error` using `f`. Leaves an `Ok` untouched. ## Examples @@ -378,7 +389,7 @@ let mapError: (t<'ok, 'a>, ~f: 'a => 'b) => t<'ok, 'b> */ let andThen: (t<'a, 'error>, ~f: 'a => t<'b, 'error>) => t<'b, 'error> -/** Run a function against an [Ok(value)], ignores `Error`s. +/** Run a function against an `Ok(value)`, ignores `Error`s. ## Examples @@ -389,12 +400,11 @@ let andThen: (t<'a, 'error>, ~f: 'a => t<'b, 'error>) => t<'b, 'error> */ let tap: (t<'ok, _>, ~f: 'ok => unit) => unit -/** # Convert */ -/** Convert a {!Result} to an [Option](Option.mdx#). +/** Convert a [Result](Result.mdx#) to an [Option](Option.mdx#). - An [Ok x] becomes [Some x] + An `Ok(x)` becomes `Some(x)` - An [Error _] becomes `None` + An `Error(_)` becomes `None` ## Examples @@ -405,7 +415,6 @@ let tap: (t<'ok, _>, ~f: 'ok => unit) => unit */ let toOption: t<'ok, _> => option<'ok> -/** {1 Compare} */ /** Test two results for equality using the provided functions. ## Examples @@ -421,9 +430,9 @@ let toOption: t<'ok, _> => option<'ok> let equal: (t<'ok, 'error>, t<'ok, 'error>, ('ok, 'ok) => bool, ('error, 'error) => bool) => bool /** Compare results for using the provided functions. - `f` will be used to compare [Ok]'s and [g] will be used on `Error`s. + `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. ## Examples diff --git a/src/TableclothSet.resi b/src/TableclothSet.resi index bd10fc3..ce44c6f 100644 --- a/src/TableclothSet.resi +++ b/src/TableclothSet.resi @@ -1,10 +1,14 @@ -/** A {!Set} represents a collection of unique values. +/** A [Set](Set.mdx#) represents a collection of unique values. - [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. + `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. - 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. + 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. - Custom data types can be used with sets as long as the module satisfies the {!Comparator.S} interface. + 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). + + 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. + + Custom data types can be used with sets as long as the module satisfies the [Comparator.S](Comparator.mdx#S) interface. ```rescript module Point = { @@ -19,19 +23,13 @@ let points = Set.fromArray(module(Point), [(0, 0), (3, 4), (6, 7)]) ``` - See the {!Comparator} module for a more details. + See the [Comparator](Comparator.mdx#) module for a more details. */ type t<'a, 'id> = Belt.Set.t<'a, 'id> -/** # 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. -*/ /** 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) ## Examples @@ -46,7 +44,7 @@ type t<'a, 'id> = Belt.Set.t<'a, 'id> */ let empty: TableclothComparator.s<'a, 'identity> => t<'a, 'identity> -/** Create a set from a single {!Int}. +/** Create a set from a single [Int](#Int). ## Examples @@ -56,7 +54,7 @@ let empty: TableclothComparator.s<'a, 'identity> => t<'a, 'identity> */ let singleton: ('a, TableclothComparator.s<'a, 'identity>) => t<'a, 'identity> -/** Create a set from an {!Array}. +/** Create a set from an [Array](#Array). ## Examples @@ -77,7 +75,6 @@ let fromArray: (array<'a>, TableclothComparator.s<'a, 'identity>) => t<'a, 'iden */ let fromList: (list<'a>, TableclothComparator.s<'a, 'identity>) => t<'a, 'identity> -/** # Basic operations */ /** Insert a value into a set. ## Examples @@ -136,7 +133,6 @@ let length: t<_, _> => int */ let find: (t<'value, _>, ~f: 'value => bool) => option<'value> -/** # Query */ /** Check if a set is empty. ## Examples @@ -172,7 +168,6 @@ let any: (t<'value, _>, ~f: 'value => bool) => bool */ let all: (t<'value, _>, ~f: 'value => bool) => bool -/** {1 Combine} */ /** Returns a new set with the values from the first set which are not in the second set. ## Examples @@ -217,7 +212,6 @@ let intersection: (t<'a, 'id>, t<'a, 'id>) => t<'a, 'id> */ let union: (t<'a, 'id>, t<'a, 'id>) => t<'a, 'id> -/** # Transform */ /** Keep elements that `f` returns `true` for. ## Examples @@ -245,7 +239,7 @@ let partition: (t<'a, 'id>, ~f: 'a => bool) => (t<'a, 'id>, t<'a, 'id>) /** 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. ## Examples @@ -258,16 +252,13 @@ let fold: (t<'a, _>, ~initial: 'b, ~f: ('b, 'a) => 'b) => 'b /** Runs a function `f` against each element of the set. */ let forEach: (t<'a, _>, ~f: 'a => unit) => unit -/** # Convert */ -/** Converts a set into an {!Array} */ +/** Converts a set into an [Array](#Array) */ let toArray: t<'a, _> => array<'a> /** 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 @@ -289,7 +280,7 @@ module Poly: { */ let singleton: 'a => t<'a> - /** Create a set from an {!Array} + /** Create a set from an [Array](#Array) ## Examples @@ -312,7 +303,7 @@ module Poly: { let fromList: list<'a> => t<'a> } -/** Construct sets of {!Int}s */ +/** Construct sets of [Int](#Int)s */ module Int: { type identity @@ -321,7 +312,7 @@ module Int: { /** A set with nothing in it. */ let empty: t - /** Create a set from a single {!Int} + /** Create a set from a single [Int](#Int) ## Examples @@ -331,7 +322,7 @@ module Int: { */ let singleton: int => t - /** Create a set from an {!Array} + /** Create a set from an [Array](Array.mdx#) ## Examples @@ -371,7 +362,7 @@ module String: { */ let singleton: string => t - /** Create a set from an {!Array}. + /** Create a set from an [Array](Array.mdx#). ## Examples diff --git a/src/TableclothString.resi b/src/TableclothString.resi index b270843..4a07dea 100644 --- a/src/TableclothString.resi +++ b/src/TableclothString.resi @@ -1,16 +1,13 @@ -/** 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 -/** # Create - - Strings literals are created with the ["double quotes"], [`backticks`] syntax. - *Warning* If string contains non-ASCII characters, use [`backticks`] - -*/ /** Converts the given character to an equivalent string of length one. */ let fromChar: char => string -/** 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. @@ -36,11 +33,11 @@ let fromArray: array => string */ let fromList: list => string -/** Create a string by repeating a string [count] time. +/** Create a string by repeating a string `count` time. ### Exceptions - If [count] is negative, [String.repeat] throws a [RangeError] exception. + If `count` is negative, [String.repeat] throws a [RangeError] exception. ## Examples @@ -64,13 +61,12 @@ let repeat: (string, ~count: int) => string */ let initialize: (int, ~f: int => char) => string -/** # Basic operations */ /** Get the character at the specified index ### Exceptions If index out of range, throws a `Invalid_argument` exception. - Concider using {!getAt}, it returns an [option] + Concider using [getAt](#getAt), it returns an `option` ## Examples @@ -81,7 +77,7 @@ let initialize: (int, ~f: int => char) => string */ let get: (string, int) => char -/** Get the character at [~index] */ +/** Get the character at `~index` */ let getAt: (string, ~index: int) => option /** Reverse a string @@ -96,11 +92,10 @@ let reverse: string => string /** Extract a substring from the specified indicies. - See {!Array.slice}. + See [Array.slice](Array.mdx#slice). */ let slice: (~to_: int=?, string, ~from: int) => string -/** # Query */ /** Check if a string is empty */ let isEmpty: string => bool @@ -114,7 +109,7 @@ let isEmpty: string => bool */ let length: string => int -/** See if the string starts with [prefix]. +/** See if the string starts with `~prefix`. ## Examples @@ -125,7 +120,7 @@ let length: string => int */ let startsWith: (string, ~prefix: string) => bool -/** See if the string ends with [suffix]. +/** See if the string ends with `~suffix`. ## Examples @@ -159,7 +154,7 @@ let includes: (string, ~substring: string) => bool */ let isCapitalized: string => bool -/** Drop [count] characters from the left side of a string. +/** Drop `count` characters from the left side of a string. ## Examples @@ -173,7 +168,7 @@ let isCapitalized: string => bool */ let dropLeft: (string, ~count: int) => string -/** Drop [count] characters from the right side of a string. +/** Drop `count` characters from the right side of a string. ## Examples @@ -187,7 +182,7 @@ let dropLeft: (string, ~count: int) => string */ let dropRight: (string, ~count: int) => string -/** 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` ## Examples @@ -198,7 +193,7 @@ let dropRight: (string, ~count: int) => string */ let indexOf: (string, string) => option -/** 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` ## Examples @@ -256,7 +251,7 @@ let toUppercase: string => string */ let uncapitalize: string => string -/** 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. ## Examples @@ -266,7 +261,7 @@ let uncapitalize: string => string */ let capitalize: string => string -/** Removes leading and trailing {{!Char.isWhitespace} whitespace} from a string +/** Removes leading and trailing [whitespace](Char.mdx#isWhitespace) from a string ## Examples @@ -278,15 +273,15 @@ let capitalize: string => string */ let trim: string => string -/** 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 -/** 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 /** Pad a string up to a minimum length. - If the string is shorted than the proivded length, adds [with_] + If the string is shorted than the proivded length, adds `with_` to the left of the string until the minimum length is met. ## Examples @@ -299,7 +294,7 @@ let padLeft: (string, int, ~with_: string) => string /** Pad a string up to a minimum length. - If the string is shorted than the proivded length, adds [with_] + If the string is shorted than the proivded length, adds `with_` to the left of the string until the minimum length is met. ## Examples @@ -310,7 +305,7 @@ let padLeft: (string, int, ~with_: string) => string */ let padRight: (string, int, ~with_: string) => string -/** Returns, as an [Option](Option.mdx#), 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`. @@ -324,7 +319,7 @@ let padRight: (string, int, ~with_: string) => string */ let uncons: string => option<(char, string)> -/** 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. ## Examples @@ -338,15 +333,13 @@ let uncons: string => option<(char, string)> */ let split: (string, ~on: string) => list -/** # Iterate */ /** Run `f` on each character in a string. */ let forEach: (string, ~f: char => unit) => unit -/** 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 -/** # Convert */ -/** Returns an {!Array} of the individual characters in the given string. +/** Returns an [Array](Array.mdx#) of the individual characters in the given string. ## Examples @@ -368,13 +361,12 @@ let toArray: string => array */ let toList: string => list -/** {1 Compare} */ /** Test two string for equality. */ let equal: (string, string) => bool /** Compare two strings. Strings use 'dictionary' ordering. -1 - Also known as {{: https://en.wikipedia.org/wiki/Lexicographical_order } lexicographical ordering }. + + Also known as [ lexicographical ordering ](https://en.wikipedia.org/wiki/Lexicographical_order). ## Examples @@ -387,7 +379,7 @@ let equal: (string, string) => bool */ let compare: (string, string) => int -/** 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 e59cfcc..d35d338 100644 --- a/src/TableclothTuple2.resi +++ b/src/TableclothTuple2.resi @@ -1,7 +1,6 @@ /** Functions for manipulating pairs of values */ type t<'a, 'b> = ('a, 'b) -/** # Create */ /** Create a two-tuple with the given values. The values do not have to be of the same type. @@ -14,7 +13,7 @@ type t<'a, 'b> = ('a, 'b) */ let make: ('a, 'b) => ('a, 'b) -/** 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. @@ -68,8 +67,7 @@ let first: (('a, 'b)) => 'a */ let second: (('a, 'b)) => 'b -/** # Transform */ -/** Transform the {!first} value in a tuple. +/** Transform the [first](#first) value in a tuple. ## Examples @@ -91,7 +89,7 @@ let mapFirst: (('a, 'b), ~f: 'a => 'x) => ('x, 'b) */ let mapSecond: (('a, 'b), ~f: 'b => 'c) => ('a, 'c) -/** 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. ## Examples @@ -126,8 +124,7 @@ let mapAll: (('a, 'a), ~f: 'a => 'b) => ('b, 'b) */ let swap: (('a, 'b)) => ('b, 'a) -/** # Convert */ -/** 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. @@ -151,7 +148,7 @@ let toArray: (('a, 'a)) => array<'a> */ let toList: (('a, 'a)) => list<'a> -/** Test two {!Tuple2}s for equality, using the provided functions to test the +/** Test two [Tuple2](Tuple2.mdx#)s for equality, using the provided functions to test the first and second components. ## Examples @@ -163,8 +160,8 @@ let toList: (('a, 'a)) => list<'a> */ let equal: (t<'a, 'b>, t<'a, 'b>, ('a, 'a) => bool, ('b, 'b) => bool) => bool -/** 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`. ## Examples diff --git a/src/TableclothTuple3.resi b/src/TableclothTuple3.resi index 6d44e0e..53542c2 100644 --- a/src/TableclothTuple3.resi +++ b/src/TableclothTuple3.resi @@ -1,8 +1,7 @@ /** Functions for manipulating trios of values */ type t<'a, 'b, 'c> = ('a, 'b, 'c) -/** # Create */ -/** Create a {!Tuple3}. +/** Create a [Tuple3](Tuple3.mdx#). ## Examples @@ -19,7 +18,7 @@ type t<'a, 'b, 'c> = ('a, 'b, 'c) */ let make: ('a, 'b, 'c) => ('a, 'b, 'c) -/** 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. @@ -84,7 +83,7 @@ let second: (('a, 'b, 'c)) => 'b */ let third: (('a, 'b, 'c)) => 'c -/** 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#). ## Examples @@ -95,7 +94,7 @@ let third: (('a, 'b, 'c)) => 'c */ let initial: (('a, 'b, 'c)) => ('a, 'b) -/** 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#). ## Examples @@ -106,7 +105,6 @@ let initial: (('a, 'b, 'c)) => ('a, 'b) */ let tail: (('a, 'b, 'c)) => ('b, 'c) -/** {1 Modify} */ /** Move each value in the tuple one position to the left, moving the value in the first position into the last position. ## Examples @@ -161,7 +159,7 @@ let mapSecond: (('a, 'b, 'c), ~f: 'b => 'y) => ('a, 'y, 'c) */ let mapThird: (('a, 'b, 'c), ~f: 'c => 'z) => ('a, 'b, 'z) -/** 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. ## Examples @@ -178,7 +176,7 @@ let mapEach: (('a, 'b, 'c), ~f: 'a => 'x, ~g: 'b => 'y, ~h: 'c => 'z) => ('x, 'y /** 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. ## Examples @@ -215,7 +213,7 @@ let toArray: (('a, 'a, 'a)) => array<'a> */ let toList: (('a, 'a, 'a)) => list<'a> -/** Test two {!Tuple3}s for equality, using the provided functions to test the +/** Test two [Tuple3](Tuple3.mdx#)s for equality, using the provided functions to test the first, second and third components. ## Examples @@ -233,9 +231,9 @@ let equal: ( ('c, 'c) => bool, ) => bool -/** 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`. ## Examples diff --git a/test/ArrayTest.res b/test/ArrayTest.res index 99f1647..efa31b5 100644 --- a/test/ArrayTest.res +++ b/test/ArrayTest.res @@ -162,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]) ) )