From 6dd6465a022f45882b669cf36acdd1263fccc1db Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Thu, 4 Jan 2024 11:14:20 -0300 Subject: [PATCH] Pretty docstrings (#6417) * add metatag rescript codeblocks * remove deprecated attr to js_promise.res * remove deprecated attr from docstrings * update * remove deprecated comments * add header * dedent comments * fixes * fixes * last edits * update js_math.ml * update CHANGELOG.md * more polish * update CHANGELOG.md * restore release.ninja * restore release.ninja * [skip ci]: update CHANGELOG.md --- CHANGELOG.md | 4 + jscomp/others/belt.res | 44 +- jscomp/others/belt_Array.resi | 694 +++++++++-------- jscomp/others/belt_Float.resi | 90 ++- jscomp/others/belt_HashMap.resi | 490 ++++++------ jscomp/others/belt_HashMapInt.resi | 5 +- jscomp/others/belt_HashMapString.resi | 5 +- jscomp/others/belt_HashSet.resi | 70 +- jscomp/others/belt_HashSetInt.resi | 8 +- jscomp/others/belt_HashSetString.resi | 8 +- jscomp/others/belt_Id.resi | 69 +- jscomp/others/belt_Int.resi | 90 ++- jscomp/others/belt_List.resi | 818 +++++++++++--------- jscomp/others/belt_Map.resi | 526 +++++++------ jscomp/others/belt_MapDict.resi | 139 ++-- jscomp/others/belt_MapInt.resi | 89 ++- jscomp/others/belt_MapString.resi | 89 ++- jscomp/others/belt_MutableMap.resi | 68 +- jscomp/others/belt_MutableMapInt.resi | 54 +- jscomp/others/belt_MutableMapString.resi | 54 +- jscomp/others/belt_MutableQueue.resi | 44 +- jscomp/others/belt_MutableSet.resi | 706 +++++++++-------- jscomp/others/belt_MutableSetInt.resi | 38 +- jscomp/others/belt_MutableSetString.resi | 38 +- jscomp/others/belt_MutableStack.resi | 12 +- jscomp/others/belt_Option.resi | 271 ++++--- jscomp/others/belt_Range.resi | 91 ++- jscomp/others/belt_Result.resi | 184 ++--- jscomp/others/belt_Set.cppo.resi | 67 +- jscomp/others/belt_Set.resi | 556 ++++++++------ jscomp/others/belt_SetDict.resi | 676 +++++++++-------- jscomp/others/belt_SetInt.resi | 78 +- jscomp/others/belt_SetString.resi | 79 +- jscomp/others/belt_SortArray.resi | 75 +- jscomp/others/belt_SortArrayInt.resi | 40 +- jscomp/others/belt_SortArrayString.resi | 40 +- jscomp/others/belt_internalAVLset.resi | 13 +- jscomp/others/belt_internalAVLtree.resi | 2 +- jscomp/others/hashmap.cppo.resi | 5 +- jscomp/others/js.ml | 63 +- jscomp/others/js_array.res | 915 +++++++++++++---------- jscomp/others/js_array2.res | 258 +++++-- jscomp/others/js_cast.resi | 27 +- jscomp/others/js_date.res | 264 +++++-- jscomp/others/js_dict.resi | 40 +- jscomp/others/js_exn.resi | 36 +- jscomp/others/js_float.res | 305 ++++---- jscomp/others/js_global.res | 45 +- jscomp/others/js_int.res | 48 +- jscomp/others/js_json.resi | 74 +- jscomp/others/js_list.resi | 3 +- jscomp/others/js_mapperRt.resi | 3 +- jscomp/others/js_math.ml | 676 +++++++++-------- jscomp/others/js_null.resi | 8 +- jscomp/others/js_null_undefined.resi | 15 +- jscomp/others/js_obj.res | 11 +- jscomp/others/js_option.res | 192 ++--- jscomp/others/js_promise.res | 13 +- jscomp/others/js_re.res | 165 ++-- jscomp/others/js_string.res | 184 +++-- jscomp/others/js_string2.res | 182 +++-- jscomp/others/js_typed_array.res | 113 +-- jscomp/others/js_typed_array2.res | 113 +-- jscomp/others/js_types.resi | 16 +- jscomp/others/js_undefined.resi | 8 +- jscomp/others/js_vector.res | 5 +- jscomp/others/map.cppo.resi | 89 ++- jscomp/others/mapm.cppo.resi | 54 +- jscomp/others/setm.cppo.resi | 38 +- jscomp/others/sort.cppo.resi | 40 +- 70 files changed, 5897 insertions(+), 4535 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d96be4665..4541f7631b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,10 @@ - GenType: now emits full suffix on JS import path to be compatible with `.res.js`. https://github.com/rescript-lang/rescript-compiler/pull/6541 +#### :nail_care: Polish + +- Format docstrings. https://github.com/rescript-lang/rescript-compiler/pull/6417 + # 11.0.0-rc.8 #### :rocket: New Feature diff --git a/jscomp/others/belt.res b/jscomp/others/belt.res index aec22e6a23..c97d77f454 100644 --- a/jscomp/others/belt.res +++ b/jscomp/others/belt.res @@ -40,7 +40,9 @@ Belt provides: To use modules from Belt, either refer to them by their fully qualified name (`Belt.List`, `Belt.Array` etc.) or open the `Belt` module by putting -``` +## Examples + +```rescript open Belt ``` @@ -49,7 +51,9 @@ at the top of your source files. After opening Belt this way, `Array` will refer If you want to open Belt globally for all files in your project instead, you can put ```json - "bsc-flags": ["-open Belt"], +{ + "bsc-flags": ["-open Belt"] +} ``` into your `bsconfig.json`. @@ -58,7 +62,9 @@ into your `bsconfig.json`. Example usage: -``` +## Examples + +```rescript let someNumbers = [1, 1, 4, 2, 3, 6, 3, 4, 2] let greaterThan2UniqueAndSorted = @@ -81,7 +87,9 @@ available: E.g.: -``` +## Examples + +```rescript let forEach: (t<'a>, 'a => unit) => unit let forEachU: (t<'a>, (. 'a) => unit) => unit @@ -91,7 +99,9 @@ The uncurried version will be faster in some cases, but for simplicity we recomm The two versions can be invoked as follows: -``` +## Examples + +```rescript ["a", "b", "c"]->Belt.Array.forEach(x => Js.log(x)) ["a", "b", "c"]->Belt.Array.forEachU((. x) => Js.log(x)) @@ -104,8 +114,8 @@ For collections types like set or map, Belt provides both a generic module as we For example, Belt has the following set modules: - [Belt.Set](belt/set) -- [Belt.Set.Int](belt/set-int) -- [Belt.Set.String](belt/set-string) +- [Belt.Set.Int](belt/set/int) +- [Belt.Set.String](belt/set/string) ## Implementation Details @@ -113,7 +123,9 @@ For example, Belt has the following set modules: One common confusion comes from the way Belt handles array access. It differs from than the default standard library's. -``` +## Examples + +```rescript let letters = ["a", "b", "c"] let a = letters[0] // a == "a" let capitalA = Js.String.toUpperCase(a) @@ -122,7 +134,9 @@ let k = letters[10] // Raises an exception! The 10th index doesn't exist. Because Belt avoids exceptions and returns `options` instead, this code behaves differently: -``` +## Examples + +```rescript open Belt let letters = ["a", "b", "c"] let a = letters[0] // a == Some("a") @@ -138,7 +152,9 @@ Although we've fixed the problem where `k` raises an exception, we now have a ty Fortunately, this is easy to fix: -```res example +## Examples + +```rescript open Belt let letters = ["a", "b", "c"] let a = letters[0] @@ -161,7 +177,9 @@ When we create a collection library for a custom data type we need a way to prov We use a phantom type to solve the problem: -``` +## Examples + +```rescript module Comparable1 = Belt.Id.MakeComparable( { @@ -193,7 +211,9 @@ let mySet2 = Belt.Set.make(~id=module(Comparable2)) Here, the compiler would infer `mySet1` and `mySet2` having different type, so e.g. a `merge` operation that tries to merge these two sets will correctly fail. -``` +## Examples + +```rescript let mySet1: t<(int, int), Comparable1.identity> let mySet2: t<(int, int), Comparable2.identity> ``` diff --git a/jscomp/others/belt_Array.resi b/jscomp/others/belt_Array.resi index fade1cc619..01a7f50934 100644 --- a/jscomp/others/belt_Array.resi +++ b/jscomp/others/belt_Array.resi @@ -12,682 +12,752 @@ /* ********************************************************************* */ /* Adapted significantly by Authors of ReScript */ -/*** Utililites for `Array` functions. +/*** +Utililites for `Array` functions. ### Note about index syntax -Code like `arr[0]` does *not* compile to JavaScript `arr[0]`. Reason transforms the `[]` index syntax into a function: `Array.get(arr, 0)`. By default, this uses the default standard library's `Array.get` function, which may raise an exception if the index isn't found. If you `open Belt`, it will use the `Belt.Array.get` function which returns options instead of raising exceptions. [See this for more information](../belt.mdx#array-access-runtime-safety). +Code like `arr[0]` does *not* compile to JavaScript `arr[0]`. Reason transforms +the `[]` index syntax into a function: `Array.get(arr, 0)`. By default, this +uses the default standard library's `Array.get` function, which may raise an +exception if the index isn't found. If you `open Belt`, it will use the +`Belt.Array.get` function which returns options instead of raising exceptions. +[See this for more information](../belt.mdx#array-access-runtime-safety). */ type t<'a> = array<'a> -/** return the size of the array +/** +Return the size of the array + +## Examples -```res example +```rescript // Returns 1 Belt.Array.length(["test"]) ``` */ external length: t<'a> => int = "%array_length" -/** **See** [`length`]() */ +/** See [`Belt.Array.length`]() */ external size: t<'a> => int = "%array_length" /** - If `i <= 0 <= length(arr)` returns `Some(value)` where `value` is the item at index `i`. - If `i` is out of range returns `None`. - ``` - Belt.Array.get(["a", "b", "c"], 0) == Some("a") - Belt.Array.get(["a", "b", "c"], 3) == None - Belt.Array.get(["a", "b", "c"], -1) == None - ``` +If `i <= 0 <= length(arr)` returns `Some(value)` where `value` is the item at index `i`. +If `i` is out of range returns `None`. + +## Examples + +```rescript +Belt.Array.get(["a", "b", "c"], 0) == Some("a") +Belt.Array.get(["a", "b", "c"], 3) == None +Belt.Array.get(["a", "b", "c"], -1) == None +``` */ let get: (t<'a>, int) => option<'a> /** - Raise an exception if `i` is out of range. - Otherwise return the value at index `i` in `arr`. +Raise an exception if `i` is out of range. +Otherwise return the value at index `i` in `arr`. */ let getExn: (t<'a>, int) => 'a /** - `getUnsafe(arr, i)` +`getUnsafe(arr, i)` - **Unsafe** +**Unsafe** - no bounds checking; this would cause type error if `i` does not stay within range +no bounds checking; this would cause type error if `i` does not stay within range */ external getUnsafe: (t<'a>, int) => 'a = "%array_unsafe_get" /** - `getUndefined(arr, i)` +`getUndefined(arr, i)` - It does the samething in the runtime as [`getUnsafe`](); - it is _type safe_ since the return type still track whether it is - in range or not +It does the samething in the runtime as [`getUnsafe`](); +it is _type safe_ since the return type still track whether it is +in range or not */ external getUndefined: (t<'a>, int) => Js.undefined<'a> = "%array_unsafe_get" /** - `set(arr, n, x)` modifies `arr` in place; it replaces the nth element of `arr` with `x`. - Returning `false` means not updated due to out of range. +`set(arr, n, x)` modifies `arr` in place; it replaces the nth element of `arr` +with `x`. Returning `false` means not updated due to out of range. */ let set: (t<'a>, int, 'a) => bool /** - `setExn(arr, i, x)` raise an exception if `i` is out of range. +`setExn(arr, i, x)` raise an exception if `i` is out of range. */ let setExn: (t<'a>, int, 'a) => unit external setUnsafe: (t<'a>, int, 'a) => unit = "%array_unsafe_set" -/** `shuffleInPlace(arr)` randomly re-orders the items in `arr` */ +/** +`shuffleInPlace(arr)` randomly re-orders the items in `arr` +*/ let shuffleInPlace: t<'a> => unit /** Returns a fresh array with items in original array randomly shuffled. */ let shuffle: t<'a> => t<'a> /** - `reverseInPlace(arr)` reverses items in `arr` in place. +`reverseInPlace(arr)` reverses items in `arr` in place. + +## Examples - ```res example - let arr = [10, 11, 12, 13, 14] +```rescript +let arr = [10, 11, 12, 13, 14] - let () = Belt.Array.reverseInPlace(arr) +let () = Belt.Array.reverseInPlace(arr) - arr == [14, 13, 12, 11, 10] - ``` +arr == [14, 13, 12, 11, 10] +``` */ let reverseInPlace: t<'a> => unit /** - `reverse(arr)` returns a fresh array with items in arr in reverse order. +`reverse(arr)` returns a fresh array with items in arr in reverse order. + +## Examples - ```res example - Belt.Array.reverse([10, 11, 12, 13, 14]) == [14, 13, 12, 11, 10] - ``` +```rescript +Belt.Array.reverse([10, 11, 12, 13, 14]) == [14, 13, 12, 11, 10] +``` */ let reverse: t<'a> => t<'a> @new /** - `makeUninitialized(n)` creates an array of length `n` filled with the undefined value. You must specify the type of data that will eventually fill the array. +`makeUninitialized(n)` creates an array of length `n` filled with the undefined +value. You must specify the type of data that will eventually fill the array. + +## Examples - ```res example - let arr: array> = Belt.Array.makeUninitialized(5) +```rescript +let arr: array> = Belt.Array.makeUninitialized(5) - Belt.Array.getExn(arr, 0) == Js.undefined - ``` +Belt.Array.getExn(arr, 0) == Js.undefined +``` */ external makeUninitialized: int => array> = "Array" @new /** - **Unsafe** +**Unsafe** + +## Examples - ```res example - let arr = Belt.Array.makeUninitializedUnsafe(5) +```rescript +let arr = Belt.Array.makeUninitializedUnsafe(5) - Js.log(Belt.Array.getExn(arr, 0)) // undefined +Js.log(Belt.Array.getExn(arr, 0)) // undefined - Belt.Array.setExn(arr, 0, "example") +Belt.Array.setExn(arr, 0, "example") - Js.log(Belt.Array.getExn(arr, 0) == "example") - ``` +Js.log(Belt.Array.getExn(arr, 0) == "example") +``` */ external makeUninitializedUnsafe: int => t<'a> = "Array" /** - `make(n, e)` return an array of size `n` filled with value `e`. - Returns an empty array when `n` is negative. +`make(n, e)` return an array of size `n` filled with value `e`. +Returns an empty array when `n` is negative. */ let make: (int, 'a) => t<'a> /** - `range(start, finish)` create an inclusive array. +`range(start, finish)` create an inclusive array. + +## Examples - ```res example - Belt.Array.range(0, 3) == [0, 1, 2, 3] +```rescript +Belt.Array.range(0, 3) == [0, 1, 2, 3] - Belt.Array.range(3, 0) == [] +Belt.Array.range(3, 0) == [] - Belt.Array.range(3, 3) == [3] - ``` +Belt.Array.range(3, 3) == [3] +``` */ let range: (int, int) => array /** - `rangeBy(start, finish, ~step)` +`rangeBy(start, finish, ~step)` returns empty array when step is 0 or negative. +It also return an empty array when `start > finish`. - Returns empty array when step is 0 or negative. It also return an empty array when `start > finish`. +## Examples - ```res example - Belt.Array.rangeBy(0, 10, ~step=3) == [0, 3, 6, 9] +```rescript +Belt.Array.rangeBy(0, 10, ~step=3) == [0, 3, 6, 9] - Belt.Array.rangeBy(0, 12, ~step=3) == [0, 3, 6, 9, 12] +Belt.Array.rangeBy(0, 12, ~step=3) == [0, 3, 6, 9, 12] - Belt.Array.rangeBy(33, 0, ~step=1) == [] +Belt.Array.rangeBy(33, 0, ~step=1) == [] - Belt.Array.rangeBy(33, 0, ~step=-1) == [] +Belt.Array.rangeBy(33, 0, ~step=-1) == [] - Belt.Array.rangeBy(3, 12, ~step=-1) == [] +Belt.Array.rangeBy(3, 12, ~step=-1) == [] - Belt.Array.rangeBy(3, 3, ~step=0) == [] +Belt.Array.rangeBy(3, 3, ~step=0) == [] - Belt.Array.rangeBy(3, 3, ~step=1) == [3] - ``` +Belt.Array.rangeBy(3, 3, ~step=1) == [3] +``` */ let rangeBy: (int, int, ~step: int) => array let makeByU: (int, (. int) => 'a) => t<'a> /** - `makeBy(n, f)` +`makeBy(n, f)` return an empty array when n is negative return an array of size +n populated by `f(i)` start from `0` to `n - 1`. - Return an empty array when n is negative return an array of size n populated by `f(i)` start from `0` to `n - 1`. +## Examples - ```res example - Belt.Array.makeBy(5, (i) => i) == [0, 1, 2, 3, 4] +```rescript +Belt.Array.makeBy(5, (i) => i) == [0, 1, 2, 3, 4] - Belt.Array.makeBy(5, (i) => i * i) == [0, 1, 4, 9, 16] - ``` +Belt.Array.makeBy(5, (i) => i * i) == [0, 1, 4, 9, 16] +``` */ let makeBy: (int, int => 'a) => t<'a> let makeByAndShuffleU: (int, (. int) => 'a) => t<'a> /** - Equivalent to `shuffle(makeBy(n, f))` +Equivalent to `shuffle(makeBy(n, f))` */ let makeByAndShuffle: (int, int => 'a) => t<'a> /** - `zip(a, b)` +`zip(a, b)` create an array of pairs from corresponding elements of a and b. +Stop with the shorter array. - Create an array of pairs from corresponding elements of a and b. Stop with the shorter array. +## Examples - ```res example - Belt.Array.zip([1, 2], [3, 4, 5]) == [(1, 3), (2, 4)] - ``` +```rescript +Belt.Array.zip([1, 2], [3, 4, 5]) == [(1, 3), (2, 4)] +``` */ let zip: (t<'a>, array<'b>) => array<('a, 'b)> let zipByU: (t<'a>, array<'b>, (. 'a, 'b) => 'c) => array<'c> /** - `zipBy(xs, ys, f)` +`zipBy(xs, ys, f)` create an array by applying `f` to corresponding elements of +`xs` and `ys`. Stops with shorter array. - Create an array by applying `f` to corresponding elements of `xs` and `ys`. Stops with shorter array. +Equivalent to `map(zip(xs, ys), ((a, b)) => f(a, b))` - Equivalent to `map(zip(xs, ys), ((a, b)) => f(a, b))` +## Examples - ```res example - Belt.Array.zipBy([1, 2, 3], [4, 5], (a, b) => 2 * a + b) == [6, 9] - ``` +```rescript +Belt.Array.zipBy([1, 2, 3], [4, 5], (a, b) => 2 * a + b) == [6, 9] +``` */ let zipBy: (t<'a>, array<'b>, ('a, 'b) => 'c) => array<'c> /** - `unzip(a)` takes an array of pairs and creates a pair of arrays. The first array contains all the first items of the pairs; the second array contains all the second items. +`unzip(a)` takes an array of pairs and creates a pair of arrays. The first array +contains all the first items of the pairs; the second array contains all the +second items. + +## Examples - ```res example - Belt.Array.unzip([(1, 2), (3, 4)]) == ([1, 3], [2, 4]) +```rescript +Belt.Array.unzip([(1, 2), (3, 4)]) == ([1, 3], [2, 4]) - Belt.Array.unzip([(1, 2), (3, 4), (5, 6), (7, 8)]) == ([1, 3, 5, 7], [2, 4, 6, 8]) - ``` +Belt.Array.unzip([(1, 2), (3, 4), (5, 6), (7, 8)]) == ([1, 3, 5, 7], [2, 4, 6, 8]) +``` */ let unzip: array<('a, 'b)> => (t<'a>, array<'b>) /** - `concat(xs, ys)` +`concat(xs, ys)` returns a fresh array containing the concatenation of the arrays +`v1` and `v2`, so even if `v1` or `v2` is empty; it can not be shared. - Returns a fresh array containing the concatenation of the arrays `v1` and `v2`;so even if `v1` or `v2` is empty; it can not be shared +## Examples - ```res example - Belt.Array.concat([1, 2, 3], [4, 5]) == [1, 2, 3, 4, 5] +```rescript +Belt.Array.concat([1, 2, 3], [4, 5]) == [1, 2, 3, 4, 5] - Belt.Array.concat([], ["a", "b", "c"]) == ["a", "b", "c"] - ``` +Belt.Array.concat([], ["a", "b", "c"]) == ["a", "b", "c"] +``` */ let concat: (t<'a>, t<'a>) => t<'a> /** - `concatMany(xss)` +`concatMany(xss)` returns a fresh array as the concatenation of `xss` (an array of arrays) - Returns a fresh array as the concatenation of `xss` (an array of arrays) +## Examples - ```res example - Belt.Array.concatMany([[1, 2, 3], [4, 5, 6], [7, 8]]) == [1, 2, 3, 4, 5, 6, 7, 8] - ``` +```rescript +Belt.Array.concatMany([[1, 2, 3], [4, 5, 6], [7, 8]]) == [1, 2, 3, 4, 5, 6, 7, 8] +``` */ let concatMany: array> => t<'a> /** - `slice(xs, offset, len)` creates a new array with the len elements of `xs` - starting at `offset` for `offset` can be negative;and is evaluated as - `length(xs) - offset(slice, xs) - 1(1)` means get the last element as a - singleton array `slice(xs, ~-len, len)` will return a copy of the array if the - array does not have enough data; `slice` extracts through the end of sequence. +`slice(xs, offset, len)` creates a new array with the len elements of `xs` +starting at `offset` for `offset` can be negative;and is evaluated as +`length(xs) - offset(slice, xs) - 1(1)` means get the last element as a +singleton array `slice(xs, ~-len, len)` will return a copy of the array if the +array does not have enough data; `slice` extracts through the end of sequence. + +if `len` is negative; returns the empty array. - if `len` is negative; returns the empty array. +## Examples - ```res example - Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=2, ~len=3) == [12, 13, 14] +```rescript +Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=2, ~len=3) == [12, 13, 14] - Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=-4, ~len=3) == [13, 14, 15] +Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=-4, ~len=3) == [13, 14, 15] - Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=4, ~len=9) == [14, 15, 16] - ``` +Belt.Array.slice([10, 11, 12, 13, 14, 15, 16], ~offset=4, ~len=9) == [14, 15, 16] +``` */ let slice: (t<'a>, ~offset: int, ~len: int) => t<'a> /** - `sliceToEnd(xs, offset)` creates a new array with the elements of `xs` starting at `offset` +`sliceToEnd(xs, offset)` creates a new array with the elements of `xs` starting +at `offset` + +`offset` can be negative; and is evaluated as `length(xs) - offset(sliceToEnd, xs) - 1` +means get the last element as a singleton array - `offset` can be negative; and is evaluated as `length(xs) - offset(sliceToEnd, xs) - 1` means get the last element as a singleton array +`sliceToEnd(xs, 0)` will return a copy of the array - `sliceToEnd(xs, 0)` will return a copy of the array +## Examples - ```res example - Belt.Array.sliceToEnd([10, 11, 12, 13, 14, 15, 16], 2) == [12, 13, 14, 15, 16] +```rescript +Belt.Array.sliceToEnd([10, 11, 12, 13, 14, 15, 16], 2) == [12, 13, 14, 15, 16] - Belt.Array.sliceToEnd([10, 11, 12, 13, 14, 15, 16], -4) == [13, 14, 15, 16] - ``` +Belt.Array.sliceToEnd([10, 11, 12, 13, 14, 15, 16], -4) == [13, 14, 15, 16] +``` */ let sliceToEnd: (t<'a>, int) => t<'a> @send /** - `copy(a)` - - Returns a copy of a; that is; a fresh array containing the same elements as a. +`copy(a)` returns a copy of `a`; that is; a fresh array containing the same +elements as `a`. */ external copy: (t<'a>, @as(0) _) => t<'a> = "slice" /** - `fill(arr, ~offset, ~len, x)` +`fill(arr, ~offset, ~len, x)` modifies `arr` in place, storing `x` in elements +number `offset` to `offset + len - 1`. `offset` can be negative; and is evaluated +as `length(arr - offset)`. - Modifies `arr` in place, storing `x` in elements number `offset` to `offset + len - 1`. - `offset` can be negative; and is evaluated as `length(arr - offset)` +`fill(arr, ~offset=-1, ~len=1)` means fill the last element, if the array does not have enough data; `fill` will ignore it - `fill(arr, ~offset=-1, ~len=1)` means fill the last element, if the array does not have enough data; `fill` will ignore it +## Examples - ```res example - let arr = Belt.Array.makeBy(5, (i) => i) +```rescript +let arr = Belt.Array.makeBy(5, (i) => i) - Belt.Array.fill(arr, ~offset=2, ~len=2, 9) +Belt.Array.fill(arr, ~offset=2, ~len=2, 9) - arr == [0, 1, 9, 9, 4] +arr == [0, 1, 9, 9, 4] - Belt.Array.fill(arr, ~offset=7, ~len=2, 8) +Belt.Array.fill(arr, ~offset=7, ~len=2, 8) - arr == [0, 1, 9, 9, 4] +arr == [0, 1, 9, 9, 4] */ let fill: (t<'a>, ~offset: int, ~len: int, 'a) => unit /** - `blit(~src=v1, ~srcOffset=o1, ~dst=v2, ~dstOffset=o2, ~len)` - - copies `len` elements from array `v1`;starting at element number `o1`;to array `v2`, starting at element number `o2`. +`blit(~src=v1, ~srcOffset=o1, ~dst=v2, ~dstOffset=o2, ~len)` copies `len` elements +from array `v1`;starting at element number `o1`;to array `v2`, starting at element +number `o2`. It works correctly even if `v1` and `v2` are the same array and the +source and destination chunks overlap. - It works correctly even if `v1` and `v2` are the same array;and the source and destination chunks overlap. +`offset` can be negative; `-1` means `len - 1`; if `len + offset` is still negative;it will be set as 0 - `offset` can be negative; `-1` means `len - 1`; if `len + offset` is still negative;it will be set as 0 +For each of the examples;presume that `v1 == [10, 11, 12, 13, 14, 15, 16, 17]` and `v2 == [20, 21, 22, 23, 24, 25, 26, 27]`. The result shown is the content of the destination array. - For each of the examples;presume that `v1 == [10, 11, 12, 13, 14, 15, 16, 17]` and `v2 == [20, 21, 22, 23, 24, 25, 26, 27]`. The result shown is the content of the destination array. +## Examples - ```res example - let v1 = [10, 11, 12, 13, 14, 15, 16, 17] - let v2 = [20, 21, 22, 23, 24, 25, 26, 27] +```rescript +let v1 = [10, 11, 12, 13, 14, 15, 16, 17] +let v2 = [20, 21, 22, 23, 24, 25, 26, 27] - Belt.Array.blit(~src=v1, ~srcOffset=4, ~dst=v2, ~dstOffset=2, ~len=3) - v2 == [20, 21, 14, 15, 16, 25, 26, 27] +Belt.Array.blit(~src=v1, ~srcOffset=4, ~dst=v2, ~dstOffset=2, ~len=3) +v2 == [20, 21, 14, 15, 16, 25, 26, 27] - Belt.Array.blit(~src=v1, ~srcOffset=4, ~dst=v1, ~dstOffset=2, ~len=3) - v1 == [10, 11, 14, 15, 16, 15, 16, 17] - ``` +Belt.Array.blit(~src=v1, ~srcOffset=4, ~dst=v1, ~dstOffset=2, ~len=3) +v1 == [10, 11, 14, 15, 16, 15, 16, 17] +``` */ let blit: (~src: t<'a>, ~srcOffset: int, ~dst: t<'a>, ~dstOffset: int, ~len: int) => unit /** - Unsafe blit without bounds checking. +Unsafe blit without bounds checking. */ let blitUnsafe: (~src: t<'a>, ~srcOffset: int, ~dst: t<'a>, ~dstOffset: int, ~len: int) => unit let forEachU: (t<'a>, (. 'a) => unit) => unit /** - `forEach(xs, f)` +`forEach(xs, f)` + +Call `f` on each element of `xs` from the beginning to end. `f` returns `unit` +so no new array is created. Use `forEach` when you are primarily concerned with +repetitively creating side effects. - Call `f` on each element of `xs` from the beginning to end. `f` returns `unit`;so no new array is created. Use `forEach` when you are primarily concerned with repetitively creating side effects. +## Examples - ```res example - Belt.Array.forEach(["a", "b", "c"], x => Js.log("Item: " ++ x)) +```rescript +Belt.Array.forEach(["a", "b", "c"], x => Js.log("Item: " ++ x)) - /* - prints: - Item: a - Item: b - Item: c - */ - let total = ref(0) +/* + prints: + Item: a + Item: b + Item: c +*/ +let total = ref(0) - Belt.Array.forEach([1, 2, 3, 4], x => total := total.contents + x) +Belt.Array.forEach([1, 2, 3, 4], x => total := total.contents + x) - total.contents == 1 + 2 + 3 + 4 - ``` +total.contents == 1 + 2 + 3 + 4 +``` */ let forEach: (t<'a>, 'a => unit) => unit let mapU: (t<'a>, (. 'a) => 'b) => array<'b> /** - `map(xs, f)` +`map(xs, f)` returns a new array by calling `f` for each element of `xs` from +the beginning to end. - Returns a new array by calling `f` for each element of `xs` from the beginning to end. +## Examples - ```res example - Belt.Array.map([1, 2], (x) => x + 1) == [3, 4] - ``` +```rescript +Belt.Array.map([1, 2], (x) => x + 1) == [3, 4] +``` */ let map: (t<'a>, 'a => 'b) => array<'b> let flatMapU: (t<'a>, (. 'a) => array<'b>) => array<'b> /** - `flatMap(xs, f)` +`flatMap(xs, f)` returns a new array by calling `f` for each element of `xs` from +the beginning to end, concatenating the results. - **Returns** a new array by calling `f` for each element of `xs` from - the beginning to end, concatenating the results. +## Examples - ```res example - flatMap([1, 2], x => [x + 10, x + 20]) == [11, 21, 12, 22] - ``` +```rescript +Belt.Array.flatMap([1, 2], x => [x + 10, x + 20]) == [11, 21, 12, 22] +``` */ let flatMap: (t<'a>, 'a => array<'b>) => array<'b> let getByU: (t<'a>, (. 'a) => bool) => option<'a> /** - `getBy(xs, p)` +`getBy(xs, p)` returns `Some(value)` for the first value in `xs` that satisifies +the predicate function `p`; returns `None` if no element satisifies the function. - Returns `Some(value)` for the first value in `xs` that satisifies the predicate function `p`; returns `None` if no element satisifies the function. +## Examples - ```res example - Belt.Array.getBy([1, 4, 3, 2], (x) => mod(x, 2) == 0) == Some(4) - Belt.Array.getBy([15, 13, 11], (x) => mod(x, 2) == 0) == None - ``` +```rescript +Belt.Array.getBy([1, 4, 3, 2], (x) => mod(x, 2) == 0) == Some(4) +Belt.Array.getBy([15, 13, 11], (x) => mod(x, 2) == 0) == None +``` */ let getBy: (t<'a>, 'a => bool) => option<'a> let getIndexByU: (t<'a>, (. 'a) => bool) => option /** - `getIndexBy(xs, p)` returns `Some(index)` for the first value in `xs` that satisifies the predicate function `p`; - returns `None` if no element satisifies the function. +`getIndexBy(xs, p)` returns `Some(index)` for the first value in `xs` that +satisifies the predicate function `p`; returns `None` if no element satisifies +the function. + +## Examples - ```res example - Belt.Array.getIndexBy([1, 4, 3, 2], (x) => mod(x, 2) == 0) == Some(1) - Belt.Array.getIndexBy([15, 13, 11], (x) => mod(x, 2) == 0) == None - ``` +```rescript +Belt.Array.getIndexBy([1, 4, 3, 2], (x) => mod(x, 2) == 0) == Some(1) +Belt.Array.getIndexBy([15, 13, 11], (x) => mod(x, 2) == 0) == None +``` */ let getIndexBy: (t<'a>, 'a => bool) => option let keepU: (t<'a>, (. 'a) => bool) => t<'a> /** - `keep(xs, p)` returns a new array that keep all elements satisfy `p`. +`keep(xs, p)` returns a new array that keep all elements satisfy `p`. */ let keep: (t<'a>, 'a => bool) => t<'a> let keepWithIndexU: (t<'a>, (. 'a, int) => bool) => t<'a> /** - `keepWithIndex(xs, p)` +`keepWithIndex(xs, p)` returns a new array that keep all elements satisfy `p`. - Returns a new array that keep all elements satisfy `p`. +## Examples - ```res example - Belt.Array.keepWithIndex([1, 2, 3], (_x, i) => i == 1) == [2] - ``` +```rescript +Belt.Array.keepWithIndex([1, 2, 3], (_x, i) => i == 1) == [2] +``` */ let keepWithIndex: (t<'a>, ('a, int) => bool) => t<'a> let keepMapU: (t<'a>, (. 'a) => option<'b>) => array<'b> /** - `keepMap(xs, p)` +`keepMap(xs, p)` returns a new array that keep all elements that return a non +None applied `p`. - Returns a new array that keep all elements that return a non-None applied `p`. +## Examples - ```res example - Belt.Array.keepMap([1, 2, 3], x => - if mod(x, 2) == 0 { - Some(x) - } else { - None - } - ) - == [2] - ``` +```rescript +Belt.Array.keepMap([1, 2, 3], x => + if mod(x, 2) == 0 { + Some(x) + } else { + None + } +) +== [2] +``` */ let keepMap: (t<'a>, 'a => option<'b>) => array<'b> let forEachWithIndexU: (t<'a>, (. int, 'a) => unit) => unit /** - `forEachWithIndex(xs, f)` +`forEachWithIndex(xs, f)` same as `Belt.Array.forEach`, except that `f` is +supplied two arguments: the index starting from 0 and the element from `xs`. - The same as `Belt.Array.forEach`; - except that `f` is supplied two arguments: the index starting from 0 and the element from `xs`. +## Examples - ```res example - Belt.Array.forEachWithIndex(["a", "b", "c"], (i, x) => Js.log("Item " ++ Belt.Int.toString(i) ++ " is " ++ x)) +```rescript +Belt.Array.forEachWithIndex(["a", "b", "c"], (i, x) => Js.log("Item " ++ Belt.Int.toString(i) ++ " is " ++ x)) - /* - prints: - Item 0 is a - Item 1 is b - Item 2 is cc - */ - let total = ref(0) +/* + prints: + Item 0 is a + Item 1 is b + Item 2 is cc +*/ +let total = ref(0) - Belt.Array.forEachWithIndex([10, 11, 12, 13], (i, x) => total := total.contents + x + i) +Belt.Array.forEachWithIndex([10, 11, 12, 13], (i, x) => total := total.contents + x + i) - total.contents == 0 + 10 + 1 + 11 + 2 + 12 + 3 + 13 - ``` +total.contents == 0 + 10 + 1 + 11 + 2 + 12 + 3 + 13 +``` */ let forEachWithIndex: (t<'a>, (int, 'a) => unit) => unit let mapWithIndexU: (t<'a>, (. int, 'a) => 'b) => array<'b> /** - `mapWithIndex(xs, f)` +`mapWithIndex(xs, f)` applies `f` to each element of `xs`. Function `f` takes +two arguments: the index starting from 0 and the element from `xs`. - `mapWithIndex(xs, f)` applies `f` to each element of `xs`. Function `f` takes two arguments: the index starting from 0 and the element from `xs`. +## Examples - ```res example - Belt.Array.mapWithIndex([1, 2, 3], (i, x) => i + x) == [0 + 1, 1 + 2, 2 + 3] - ``` +```rescript +Belt.Array.mapWithIndex([1, 2, 3], (i, x) => i + x) == [0 + 1, 1 + 2, 2 + 3] +``` */ let mapWithIndex: (t<'a>, (int, 'a) => 'b) => array<'b> let partitionU: (t<'a>, (. 'a) => bool) => (t<'a>, t<'a>) /** - `partition(f, a)` split array into tuple of two arrays based on predicate `f`; first of tuple where predicate cause true, second where predicate cause false +`partition(f, a)` split array into tuple of two arrays based on predicate `f`; +first of tuple where predicate cause true, second where predicate cause false - ```res example - Belt.Array.partition([1, 2, 3, 4, 5], (x) => mod(x, 2) == 0) == ([2, 4], [1, 3, 5]) +## Examples - Belt.Array.partition([1, 2, 3, 4, 5], (x) => mod(x, 2) != 0) == ([1, 3, 5], [2, 4]) - ``` +```rescript +Belt.Array.partition([1, 2, 3, 4, 5], (x) => mod(x, 2) == 0) == ([2, 4], [1, 3, 5]) + +Belt.Array.partition([1, 2, 3, 4, 5], (x) => mod(x, 2) != 0) == ([1, 3, 5], [2, 4]) +``` */ let partition: (t<'a>, 'a => bool) => (t<'a>, t<'a>) let reduceU: (array<'b>, 'a, (. 'a, 'b) => 'a) => 'a /** - `reduce(xs, init, f)` +`reduce(xs, init, f)` applies `f` to each element of `xs` from beginning to end. +Function `f` has two parameters: the item from the list and an “accumulator”; +which starts with a value of `init`. `reduce` returns the final value of the +accumulator. - Applies `f` to each element of `xs` from beginning to end. Function `f` has two parameters: the item from the list and an “accumulator”; which starts with a value of `init`. `reduce` returns the final value of the accumulator. +## Examples - ```res example - Belt.Array.reduce([2, 3, 4], 1, (a, b) => a + b) == 10 +```rescript +Belt.Array.reduce([2, 3, 4], 1, (a, b) => a + b) == 10 - Belt.Array.reduce(["a", "b", "c", "d"], "", (a, b) => a ++ b) == "abcd" - ``` +Belt.Array.reduce(["a", "b", "c", "d"], "", (a, b) => a ++ b) == "abcd" +``` */ let reduce: (array<'b>, 'a, ('a, 'b) => 'a) => 'a let reduceReverseU: (array<'b>, 'a, (. 'a, 'b) => 'a) => 'a /** - `reduceReverse(xs, init, f)` +`reduceReverse(xs, init, f)` works like `Belt.Array.reduce` except that +function `f` is applied to each item of `xs` from the last back to the first. - Works like `Belt_Array.reduce`; except that function `f` is applied to each item of `xs` from the last back to the first. +## Examples - ```res example - Belt.Array.reduceReverse(["a", "b", "c", "d"], "", (a, b) => a ++ b) == "dcba" - ``` +```rescript +Belt.Array.reduceReverse(["a", "b", "c", "d"], "", (a, b) => a ++ b) == "dcba" +``` */ let reduceReverse: (array<'b>, 'a, ('a, 'b) => 'a) => 'a let reduceReverse2U: (t<'a>, array<'b>, 'c, (. 'c, 'a, 'b) => 'c) => 'c /** - `reduceReverse2(xs, ys, init, f)` +`reduceReverse2(xs, ys, init, f)` reduces two arrays xs and ys;taking items +starting at `min(length(xs), length(ys))` down to and including zero. - Reduces two arrays xs and ys;taking items starting at `min(length(xs), length(ys))` down to and including zero. +## Examples - ```res example - Belt.Array.reduceReverse2([1, 2, 3], [1, 2], 0, (acc, x, y) => acc + x + y) == 6 - ``` +```rescript +Belt.Array.reduceReverse2([1, 2, 3], [1, 2], 0, (acc, x, y) => acc + x + y) == 6 +``` */ let reduceReverse2: (t<'a>, array<'b>, 'c, ('c, 'a, 'b) => 'c) => 'c let reduceWithIndexU: (t<'a>, 'b, (. 'b, 'a, int) => 'b) => 'b /** - Applies `f` to each element of `xs` from beginning to end. Function `f` has three parameters: the item from the array and an “accumulator”, which starts with a value of `init` and the index of each element. `reduceWithIndex` returns the final value of the accumulator. +Applies `f` to each element of `xs` from beginning to end. Function `f` has +three parameters: the item from the array and an “accumulator”, which starts +with a value of `init` and the index of each element. `reduceWithIndex` returns +the final value of the accumulator. + +## Examples - ```res example - Belt.Array.reduceWithIndex([1, 2, 3, 4], 0, (acc, x, i) => acc + x + i) == 16 - ``` +```rescript +Belt.Array.reduceWithIndex([1, 2, 3, 4], 0, (acc, x, i) => acc + x + i) == 16 +``` */ let reduceWithIndex: (t<'a>, 'b, ('b, 'a, int) => 'b) => 'b let joinWithU: (t<'a>, string, (. 'a) => string) => string /** - `joinWith(xs, sep, toString)` +`joinWith(xs, sep, toString)` + +Concatenates all the elements of `xs` converted to string with `toString`, each +separated by `sep`, the string given as the second argument, into a single string. +If the array has only one element, then that element will be returned without +using the separator. If the array is empty, the empty string will be returned. - Concatenates all the elements of `xs` converted to string with `toString`, each separated by `sep`, the string - given as the second argument, into a single string. - If the array has only one element, then that element will be returned - without using the separator. - If the array is empty, the empty string will be returned. +## Examples - ```res example - joinWith([0, 1], ", ", string_of_int) == "0, 1" - joinWith([], " ", string_of_int) == "" - joinWith([1], " ", string_of_int) == "1" - ``` +```rescript +Belt.Array.joinWith([0, 1], ", ", Js.Int.toString) == "0, 1" +Belt.Array.joinWith([], " ", Js.Int.toString) == "" +Belt.Array.joinWith([1], " ", Js.Int.toString) == "1" +``` */ let joinWith: (t<'a>, string, 'a => string) => string let someU: (t<'a>, (. 'a) => bool) => bool /** - `some(xs, p)` +`some(xs, p)` returns true if at least one of the elements in `xs` satifies `p`; +where `p` is a predicate: a function taking an element and returning a `bool`. - Returns true if at least one of the elements in `xs` satifies `p`; where `p` is a predicate: a function taking an element and returning a `bool`. +## Examples - ```res example - Belt.Array.some([2, 3, 4], (x) => mod(x, 2) == 1) == true +```rescript +Belt.Array.some([2, 3, 4], (x) => mod(x, 2) == 1) == true - Belt.Array.some([(-1), (-3), (-5)], (x) => x > 0) == false - ``` +Belt.Array.some([(-1), (-3), (-5)], (x) => x > 0) == false +``` */ let some: (t<'a>, 'a => bool) => bool let everyU: (t<'a>, (. 'a) => bool) => bool /** - `every(xs, p)` +`every(xs, p)` returns `true` if all elements satisfy `p`; where `p` is a +predicate: a function taking an element and returning a `bool`. - Returns `true` if all elements satisfy `p`; where `p` is a predicate: a function taking an element and returning a `bool`. +## Examples - ```res example - Belt.Array.every([1, 3, 5], (x) => mod(x, 2) == 1) == true +```rescript +Belt.Array.every([1, 3, 5], (x) => mod(x, 2) == 1) == true - Belt.Array.every([1, (-3), 5], (x) => x > 0) == false - ``` +Belt.Array.every([1, (-3), 5], (x) => x > 0) == false +``` */ let every: (t<'a>, 'a => bool) => bool let every2U: (t<'a>, array<'b>, (. 'a, 'b) => bool) => bool /** - `every2(xs, ys, p)` +`every2(xs, ys, p)` returns true if `p(xi, yi)` is true for all pairs of +elements up to the shorter length (i.e. `min(length(xs), length(ys))`) - returns true if `p(xi, yi)` is true for all pairs of elements up to the shorter length (i.e. `min(length(xs), length(ys))`) +## Examples - ```res example - Belt.Array.every2([1, 2, 3], [0, 1], (a, b) => a > b) == true +```rescript +Belt.Array.every2([1, 2, 3], [0, 1], (a, b) => a > b) == true - Belt.Array.every2([], [1], (x, y) => x > y) == true +Belt.Array.every2([], [1], (x, y) => x > y) == true - Belt.Array.every2([2, 3], [1], (x, y) => x > y) == true +Belt.Array.every2([2, 3], [1], (x, y) => x > y) == true - Belt.Array.every2([0, 1], [5, 0], (x, y) => x > y) == false - ``` +Belt.Array.every2([0, 1], [5, 0], (x, y) => x > y) == false +``` */ let every2: (t<'a>, array<'b>, ('a, 'b) => bool) => bool let some2U: (t<'a>, array<'b>, (. 'a, 'b) => bool) => bool /** - `some2(xs, ys, p)` +`some2(xs, ys, p)` returns true if `p(xi, yi)` is true for any pair of elements +up to the shorter length (i.e. `min(length(xs), length(ys))`) - returns true if `p(xi, yi)` is true for any pair of elements up to the shorter length (i.e. `min(length(xs), length(ys))`) +## Examples - ```res example - Belt.Array.some2([0, 2], [1, 0, 3], (a, b) => a > b) == true +```rescript +Belt.Array.some2([0, 2], [1, 0, 3], (a, b) => a > b) == true - Belt.Array.some2([], [1], (x, y) => x > y) == false +Belt.Array.some2([], [1], (x, y) => x > y) == false - Belt.Array.some2([2, 3], [1, 4], (x, y) => x > y) == true - ``` +Belt.Array.some2([2, 3], [1, 4], (x, y) => x > y) == true +``` */ let some2: (t<'a>, array<'b>, ('a, 'b) => bool) => bool let cmpU: (t<'a>, t<'a>, (. 'a, 'a) => int) => int /** - `cmp(xs, ys, f)` +`cmp(xs, ys, f)` compared by length if `length(xs) != length(ys)`; returning `-1` +if `length(xs) < length(ys)` or 1 if `length(xs) > length(ys)`. Otherwise +compare one by one `f(x, y)`. `f` returns a negative number if `x` is “less than” `y` +zero if `x` is “equal to” `y` a positive number if `x` is “greater than” +`y`. The comparison returns the first non-zero result of `f`; or zero if `f` +returns zero for all `x` and `y`. - Compared by length if `length(xs) != length(ys)`; returning -1 if `length(xs) < length(ys)` or 1 if `length(xs) > length(ys)` - Otherwise compare one by one `f(x, y)`. `f` returns - a negative number if `x` is “less than” `y` - zero if `x` is “equal to” `y` - a positive number if `x` is “greater than” `y` - The comparison returns the first non-zero result of `f`;or zero if `f` returns zero for all `x` and `y`. +## Examples - ```res example - Belt.Array.cmp([1, 3, 5], [1, 4, 2], (a, b) => compare(a, b)) == -1 +```rescript +Belt.Array.cmp([1, 3, 5], [1, 4, 2], (a, b) => compare(a, b)) == -1 - Belt.Array.cmp([1, 3, 5], [1, 2, 3], (a, b) => compare(a, b)) == 1 +Belt.Array.cmp([1, 3, 5], [1, 2, 3], (a, b) => compare(a, b)) == 1 - Belt.Array.cmp([1, 3, 5], [1, 3, 5], (a, b) => compare(a, b)) == 0 - ``` +Belt.Array.cmp([1, 3, 5], [1, 3, 5], (a, b) => compare(a, b)) == 0 +``` */ let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => int let eqU: (t<'a>, t<'a>, (. 'a, 'a) => bool) => bool /** - `eq(xs, ys)` +`eq(xs, ys)` return `false` if length is not the same otherwise compare items +one by one using `f(xi, yi)`; and return true if all results are true false otherwise - return false if length is not the same - otherwise compare items one by one using `f(xi, yi)`; and return true if all results are truefalse otherwise +## Examples - ```res example - Belt.Array.eq([1, 2, 3], [(-1), (-2), (-3)], (a, b) => abs(a) == abs(b)) == true - ``` +```rescript +Belt.Array.eq([1, 2, 3], [(-1), (-2), (-3)], (a, b) => abs(a) == abs(b)) == true +``` */ let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => bool @set /** - Unsafe `truncateToLengthUnsafe(xs, n)` sets length of array `xs` to `n`. - - If `n` is greater than the length of `xs`; the extra elements are set to `Js.Null_undefined.null`. +Unsafe `truncateToLengthUnsafe(xs, n)` sets length of array `xs` to `n`. If `n` +is greater than the length of `xs`; the extra elements are set to `Js.Null_undefined.null`. +If `n` is less than zero; raises a `RangeError`. - If `n` is less than zero; raises a `RangeError`. +## Examples - ```res example - let arr = ["ant", "bee", "cat", "dog", "elk"] +```rescript +let arr = ["ant", "bee", "cat", "dog", "elk"] - Belt.Array.truncateToLengthUnsafe(arr, 3) +Belt.Array.truncateToLengthUnsafe(arr, 3) - arr == ["ant", "bee", "cat"] - ``` +arr == ["ant", "bee", "cat"] +``` */ external truncateToLengthUnsafe: (t<'a>, int) => unit = "length" @@ -695,7 +765,7 @@ let initU: (int, (. int) => 'a) => t<'a> let init: (int, int => 'a) => t<'a> /** - `arr->push(item)` pushes an element `item` into an array `arr`. +`arr->push(item)` pushes an element `item` into an array `arr`. */ @send external push: (t<'a>, 'a) => unit = "push" diff --git a/jscomp/others/belt_Float.resi b/jscomp/others/belt_Float.resi index d8d8979dc3..bc6fbf9915 100644 --- a/jscomp/others/belt_Float.resi +++ b/jscomp/others/belt_Float.resi @@ -27,80 +27,96 @@ /** Converts a given `float` to an `int`. -```res example +## Examples + +```rescript Js.log(Belt.Float.toInt(1.0) === 1) /* true */ ``` */ external toInt: float => int = "%intoffloat" /** - Converts a given `int` to a `float`. +Converts a given `int` to a `float`. + +## Examples - ```res example - Js.log(Belt.Float.fromInt(1) === 1.0) /* true */ - ``` +```rescript +Js.log(Belt.Float.fromInt(1) === 1.0) /* true */ +``` */ external fromInt: int => float = "%identity" /** - Converts a given `string` to a `float`. Returns `Some(float)` when the input is a number, `None` otherwise. +Converts a given `string` to a `float`. Returns `Some(float)` when the input is a number, `None` otherwise. + +## Examples - ```res example - Js.log(Belt.Float.fromString("1.0") === Some(1.0)) /* true */ - ``` +```rescript +Js.log(Belt.Float.fromString("1.0") === Some(1.0)) /* true */ +``` */ let fromString: string => option @val /** - Converts a given `float` to a `string`. Uses the JavaScript `String` constructor under the hood. +Converts a given `float` to a `string`. Uses the JavaScript `String` constructor under the hood. + +## Examples - ```res example - Js.log(Belt.Float.toString(1.0) === "1.0") /* true */ - ``` +```rescript +Js.log(Belt.Float.toString(1.0) === "1.0") /* true */ +``` */ external toString: float => string = "String" /** - Addition of two `float` values. - Can be opened in a module to avoid dot-notation (`+.`), however this yields a shadow warning (Warning number 44) in the default configuration. +Addition of two `float` values. +Can be opened in a module to avoid dot-notation (`+.`), however this yields a shadow warning (Warning number 44) in the default configuration. + +## Examples - ```res example - open Belt.Float - Js.log(2.0 + 2.0 === 4.0) /* true */ - ``` +```rescript +open Belt.Float +Js.log(2.0 + 2.0 === 4.0) /* true */ +``` */ external \"+": (float, float) => float = "%addfloat" /** - Subtraction of two `float` values. - Can be opened in a module to avoid dot-notation (`-.`), however this yields a shadow warning (Warning number 44) in the default configuration. +Subtraction of two `float` values. +Can be opened in a module to avoid dot-notation (`-.`), however this yields a shadow warning (Warning number 44) in the default configuration. + +## Examples - ```res example - open Belt.Float - Js.log(2.0 - 1.0 === 1.0) /* true */ - ``` +```rescript +open Belt.Float +Js.log(2.0 - 1.0 === 1.0) /* true */ +``` */ external \"-": (float, float) => float = "%subfloat" /** - Multiplication of two `float` values. - Can be opened in a module to avoid dot-notation (`*.`), however this yields a shadow warning (Warning number 44) in the default configuration. +Multiplication of two `float` values. +Can be opened in a module to avoid dot-notation (`*.`), however this yields a shadow warning (Warning number 44) in the default configuration. + +## Examples - ```res example - open Belt.Float - Js.log(2.0 * 2.0 === 4.0) /* true */ - ``` +```rescript +open Belt.Float +Js.log(2.0 * 2.0 === 4.0) /* true */ +``` */ external \"*": (float, float) => float = "%mulfloat" /** - Division of two `float` values. - Can be opened in a module to avoid dot-notation (`/.`), however this yields a shadow warning (Warning number 44) in the default configuration. +Division of two `float` values. +Can be opened in a module to avoid dot-notation (`/.`), however this yields a shadow warning (Warning number 44) in the default configuration. + +## Examples - ```res example - open Belt.Float - Js.log(4.0 / 2.0 === 2.0) /* true */ - ``` +```rescript +open Belt.Float +Js.log(4.0 / 2.0 === 2.0) /* true */ +``` */ external \"/": (float, float) => float = "%divfloat" diff --git a/jscomp/others/belt_HashMap.resi b/jscomp/others/belt_HashMap.resi index 6003f73e83..972b85819f 100644 --- a/jscomp/others/belt_HashMap.resi +++ b/jscomp/others/belt_HashMap.resi @@ -23,52 +23,54 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - A **mutable** Hash map which allows customized [`hash`]() behavior. +A **mutable** Hash map which allows customized [`hash`]() behavior. - All data are parameterized by not its only type but also a unique identity in - the time of initialization, so that two _HashMaps of ints_ initialized with different - _hash_ functions will have different type. +All data are parameterized by not its only type but also a unique identity in +the time of initialization, so that two _HashMaps of ints_ initialized with different +_hash_ functions will have different type. - For example: +## Examples - ``` - type t = int - module I0 = unpack(Belt.Id.hashableU(~hash=(. a: t) => "&"(a, 0xff_ff), ~eq=(. a, b) => a == b)) - let s0: t<_, string, _> = make(~hintSize=40, ~id=module(I0)) +```rescript +type t = int +module I0 = unpack(Belt.Id.hashableU(~hash=(. a: t) => "&"(a, 0xff_ff), ~eq=(. a, b) => a == b)) +let s0: t<_, string, _> = make(~hintSize=40, ~id=module(I0)) + +module I1 = unpack(Belt.Id.hashableU(~hash=(. a: t) => "&"(a, 0xff), ~eq=(. a, b) => a == b)) +let s1: t<_, string, _> = make(~hintSize=40, ~id=module(I1)) +``` - module I1 = unpack(Belt.Id.hashableU(~hash=(. a: t) => "&"(a, 0xff), ~eq=(. a, b) => a == b)) - let s1: t<_, string, _> = make(~hintSize=40, ~id=module(I1)) - ``` +The invariant must be held: for two elements who are _equal_, +their hashed value should be the same - The invariant must be held: for two elements who are _equal_, - their hashed value should be the same +Here the compiler would infer `s0` and `s1` having different type so that +it would not mix. - Here the compiler would infer `s0` and `s1` having different type so that - it would not mix. +## Examples + +```rescript +let s0: t +let s1: t +``` - ``` - let s0: t - let s1: t - ``` +We can add elements to the collection: - We can add elements to the collection: +## Examples - ``` - let () = { - add(s1, 0, "3") - add(s1, 1, "3") - } - ``` +```rescript +let () = { + add(s1, 0, "3") + add(s1, 1, "3") +} +``` - Since this is an mutable data strucure, `s1` will contain two pairs. +Since this is an mutable data strucure, `s1` will contain two pairs. */ -/** Specalized when key type is `int`, more efficient - than the generic type */ +/** Specalized when key type is `int`, more efficient than the generic type */ module Int = Belt_HashMapInt -/** Specalized when key type is `string`, more efficient - than the generic type */ +/** Specalized when key type is `string`, more efficient than the generic type */ module String = Belt_HashMapString /** The type of hash tables from type `'key` to type `'value`. */ @@ -78,99 +80,111 @@ type t<'key, 'value, 'id> type id<'a, 'id> = Belt_Id.hashable<'a, 'id> /** - `make(~hintSize=10, ~id)` creates a new map by taking in the comparator and `hintSize`. +`make(~hintSize=10, ~id)` creates a new map by taking in the comparator and `hintSize`. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let hMap = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) + +let hMap = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(hMap, 0, "a") - ``` +Belt.HashMap.set(hMap, 0, "a") +``` */ let make: (~hintSize: int, ~id: id<'key, 'id>) => t<'key, 'value, 'id> /* TODO: allow randomization for security */ /** - Clears a hash table. - - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) - - let hMap = Belt.HashMap.fromArray([(1, "1")], ~id=module(IntHash)) - Belt.HashMap.clear(hMap) - Belt.HashMap.isEmpty(hMap) == true - ``` +Clears a hash table. + +## Examples + +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) + +let hMap = Belt.HashMap.fromArray([(1, "1")], ~id=module(IntHash)) +Belt.HashMap.clear(hMap) +Belt.HashMap.isEmpty(hMap) == true +``` */ let clear: t<'key, 'value, 'id> => unit /** - `isEmpty(m)` checks whether a hash map is empty. +`isEmpty(m)` checks whether a hash map is empty. + +## Examples - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - Belt.HashMap.isEmpty(Belt.HashMap.fromArray([(1, "1")], ~id=module(IntHash))) == false - ``` +Belt.HashMap.isEmpty(Belt.HashMap.fromArray([(1, "1")], ~id=module(IntHash))) == false +``` */ let isEmpty: t<_> => bool /** - `set(hMap, k, v)` if `k` does not exist, add the binding `k,v`, otherwise, update the old value with the new `v`. +`set(hMap, k, v)` if `k` does not exist, add the binding `k,v`, otherwise, update the old value with the new `v`. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let s0 = Belt.HashMap.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntHash)) +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) + +let s0 = Belt.HashMap.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntHash)) - Belt.HashMap.set(s0, 2, "3") +Belt.HashMap.set(s0, 2, "3") - Belt.HashMap.valuesToArray(s0) == ["1", "3", "3"] - ``` +Belt.HashMap.valuesToArray(s0) == ["1", "3", "3"] +``` */ let set: (t<'key, 'value, 'id>, 'key, 'value) => unit /** - Creates copy of a hash map. +Creates copy of a hash map. + +## Examples - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - let s0 = Belt.HashMap.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntHash)) - let s1 = Belt.HashMap.copy(s0) +let s0 = Belt.HashMap.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntHash)) +let s1 = Belt.HashMap.copy(s0) - Belt.HashMap.set(s0, 2, "3") +Belt.HashMap.set(s0, 2, "3") - Belt.HashMap.get(s0, 2) != Belt.HashMap.get(s1, 2) - ``` +Belt.HashMap.get(s0, 2) != Belt.HashMap.get(s1, 2) +``` */ let copy: t<'key, 'value, 'id> => t<'key, 'value, 'id> /** Returns value bound under specific key. If values not exist returns `None`. -```res example +## Examples + +```rescript module IntHash = Belt.Id.MakeHashable({ type t = int let hash = a => a @@ -187,39 +201,43 @@ Belt.HashMap.get(s0, 2) == None let get: (t<'key, 'value, 'id>, 'key) => option<'value> /** - Checks if `x` is bound in `tbl`. +Checks if `x` is bound in `tbl`. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) + +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.has(s0, 1) == true - Belt.HashMap.has(s0, 2) == false - ``` +Belt.HashMap.has(s0, 1) == true +Belt.HashMap.has(s0, 2) == false +``` */ let has: (t<'key, 'value, 'id>, 'key) => bool /** - If bound exists, removes it from the hash map. - - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) - - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.remove(s0, 1) - Belt.HashMap.has(s0, 1) == false - ``` +If bound exists, removes it from the hash map. + +## Examples + +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) + +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.remove(s0, 1) +Belt.HashMap.has(s0, 1) == false +``` */ let remove: (t<'key, 'value, 'id>, 'key) => unit @@ -227,42 +245,46 @@ let remove: (t<'key, 'value, 'id>, 'key) => unit let forEachU: (t<'key, 'value, 'id>, (. 'key, 'value) => unit) => unit /** - `forEach(tbl, f)` applies `f` to all bindings in table `tbl`. `f` receives the key as first argument, and the associated value as second argument. Each binding is presented exactly once to `f`. - - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) - - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.forEach(s0, (key, value) => Js.log2(key, value)) - // prints (1, "value1") - ``` +`forEach(tbl, f)` applies `f` to all bindings in table `tbl`. `f` receives the key as first argument, and the associated value as second argument. Each binding is presented exactly once to `f`. + +## Examples + +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) + +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.forEach(s0, (key, value) => Js.log2(key, value)) +// prints (1, "value1") +``` */ let forEach: (t<'key, 'value, 'id>, ('key, 'value) => unit) => unit let reduceU: (t<'key, 'value, 'id>, 'c, (. 'c, 'key, 'value) => 'c) => 'c /** - `reduce(tbl, init, f)` computes `(f(kN, dN) ... (f(k1, d1, init))...)`, where `k1 ... kN` are the keys of all bindings in `tbl`, and `d1 ... dN` are the associated values. Each binding is presented exactly once to `f`. +`reduce(tbl, init, f)` computes `(f(kN, dN) ... (f(k1, d1, init))...)`, where `k1 ... kN` are the keys of all bindings in `tbl`, and `d1 ... dN` are the associated values. Each binding is presented exactly once to `f`. - The order in which the bindings are passed to `f` is unspecified. However, if the table contains several bindings for the same key, they are passed to `f` in reverse order of introduction, that is, the most recent binding is passed first. +The order in which the bindings are passed to `f` is unspecified. However, if the table contains several bindings for the same key, they are passed to `f` in reverse order of introduction, that is, the most recent binding is passed first. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.set(s0, 2, "value2") +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - Belt.HashMap.reduce(s0, "", (acc, key, value) => acc ++ (", " ++ value)) == "value1, value2" - ``` +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.set(s0, 2, "value2") + +Belt.HashMap.reduce(s0, "", (acc, key, value) => acc ++ (", " ++ value)) == "value1, value2" +``` */ let reduce: (t<'key, 'value, 'id>, 'c, ('c, 'key, 'value) => 'c) => 'c @@ -270,97 +292,107 @@ let reduce: (t<'key, 'value, 'id>, 'c, ('c, 'key, 'value) => 'c) => 'c let keepMapInPlaceU: (t<'key, 'value, 'id>, (. 'key, 'value) => option<'value>) => unit /** - Filters out values for which function `f` returned `None`. +Filters out values for which function `f` returned `None`. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.set(s0, 2, "value2") +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - Belt.HashMap.keepMapInPlace(s0, (key, value) => key == 1 ? None : Some(value)) - ``` +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.set(s0, 2, "value2") + +Belt.HashMap.keepMapInPlace(s0, (key, value) => key == 1 ? None : Some(value)) +``` */ let keepMapInPlace: (t<'key, 'value, 'id>, ('key, 'value) => option<'value>) => unit /** - `size(tbl)` returns the number of bindings in `tbl`. It takes constant time. +`size(tbl)` returns the number of bindings in `tbl`. It takes constant time. + +## Examples - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.set(s0, 2, "value2") +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.set(s0, 2, "value2") - Belt.HashMap.size(s0) == 2 - ``` +Belt.HashMap.size(s0) == 2 +``` */ let size: t<_> => int /** - Returns array of key value pairs. +Returns array of key value pairs. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.set(s0, 2, "value2") +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - Belt.HashMap.toArray(s0) == [(1, "value1"), (2, "value2")] - ``` +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.set(s0, 2, "value2") + +Belt.HashMap.toArray(s0) == [(1, "value1"), (2, "value2")] +``` */ let toArray: t<'key, 'value, 'id> => array<('key, 'value)> /** - Returns array of keys. +Returns array of keys. + +## Examples - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.set(s0, 2, "value2") +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.set(s0, 2, "value2") - Belt.HashMap.keysToArray(s0) == [1, 2] - ``` +Belt.HashMap.keysToArray(s0) == [1, 2] +``` */ let keysToArray: t<'key, _, _> => array<'key> /** - Returns array of values. +Returns array of values. - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) +## Examples - let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(s0, 1, "value1") - Belt.HashMap.set(s0, 2, "value2") +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) - Belt.HashMap.valuesToArray(s0) == ["value1", "value2"] - ``` +let s0 = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(s0, 1, "value1") +Belt.HashMap.set(s0, 2, "value2") + +Belt.HashMap.valuesToArray(s0) == ["value1", "value2"] +``` */ let valuesToArray: t<_, 'value, _> => array<'value> @@ -369,7 +401,9 @@ Creates new hash map from array of pairs. Returns array of values. -```res example +## Examples + +```rescript module IntHash = Belt.Id.MakeHashable({ type t = int let hash = a => a @@ -383,7 +417,9 @@ Belt.HashMap.toArray(s0) == [(1, "value1"), (2, "value2")] let fromArray: (array<('key, 'value)>, ~id: id<'key, 'id>) => t<'key, 'value, 'id> /** -```res example +## Examples + +```rescript module IntHash = Belt.Id.MakeHashable({ type t = int let hash = a => a @@ -397,31 +433,35 @@ Belt.HashMap.mergeMany(hMap, [(1, "1"), (2, "2")]) let mergeMany: (t<'key, 'value, 'id>, array<('key, 'value)>) => unit /** - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) - let hMap = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(hMap, 1, "1") - - Belt.HashMap.getBucketHistogram(hMap) - ``` +## Examples + +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) +let hMap = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(hMap, 1, "1") + +Belt.HashMap.getBucketHistogram(hMap) +``` */ let getBucketHistogram: t<_> => array /** - ```res example - module IntHash = Belt.Id.MakeHashable({ - type t = int - let hash = a => a - let eq = (a, b) => a == b - }) - let hMap = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) - Belt.HashMap.set(hMap, 1, "1") - - Belt.HashMap.logStats(hMap) - ``` +## Examples + +```rescript +module IntHash = Belt.Id.MakeHashable({ + type t = int + let hash = a => a + let eq = (a, b) => a == b +}) +let hMap = Belt.HashMap.make(~hintSize=10, ~id=module(IntHash)) +Belt.HashMap.set(hMap, 1, "1") + +Belt.HashMap.logStats(hMap) +``` */ let logStats: t<_> => unit diff --git a/jscomp/others/belt_HashMapInt.resi b/jscomp/others/belt_HashMapInt.resi index 0a0eee7cf0..67ea502346 100644 --- a/jscomp/others/belt_HashMapInt.resi +++ b/jscomp/others/belt_HashMapInt.resi @@ -9,9 +9,8 @@ let clear: t<'b> => unit let isEmpty: t<_> => bool /** - `setDone tbl k v` if `k` does not exist, - add the binding `k,v`, otherwise, update the old value with the new - `v` +`setDone(tbl, k, v)` if `k` does not exist, add the binding `k,v`, otherwise, +update the old value with the new `v` */ let set: (t<'a>, key, 'a) => unit diff --git a/jscomp/others/belt_HashMapString.resi b/jscomp/others/belt_HashMapString.resi index 6466e37415..be4cf461ae 100644 --- a/jscomp/others/belt_HashMapString.resi +++ b/jscomp/others/belt_HashMapString.resi @@ -9,9 +9,8 @@ let clear: t<'b> => unit let isEmpty: t<_> => bool /** - `setDone tbl k v` if `k` does not exist, - add the binding `k,v`, otherwise, update the old value with the new - `v` +`setDone(tbl, k, v)` if `k` does not exist, add the binding `k,v`, otherwise, +update the old value with the new `v` */ let set: (t<'a>, key, 'a) => unit diff --git a/jscomp/others/belt_HashSet.resi b/jscomp/others/belt_HashSet.resi index 64579bf280..6055194a48 100644 --- a/jscomp/others/belt_HashSet.resi +++ b/jscomp/others/belt_HashSet.resi @@ -23,58 +23,58 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - A **mutable** Hash set which allows customized `hash` behavior. +A **mutable** Hash set which allows customized `hash` behavior. - All data are parameterized by not its only type but also a unique identity in - the time of initialization, so that two _HashSets of ints_ initialized with - different _hash_ functions will have different type. +All data are parameterized by not its only type but also a unique identity in +the time of initialization, so that two _HashSets of ints_ initialized with +different _hash_ functions will have different type. - For example: +## Examples - ```res prelude - module I0 = unpack( - Belt.Id.hashableU( - ~hash=(. a: int) => land(a, 65535), - ~eq=(. a, b) => a == b, - ) +```rescript +module I0 = unpack( + Belt.Id.hashableU( + ~hash=(. a: int) => land(a, 65535), + ~eq=(. a, b) => a == b, ) +) - let s0 = Belt.HashSet.make(~id=module(I0), ~hintSize=40) +let s0 = Belt.HashSet.make(~id=module(I0), ~hintSize=40) - module I1 = unpack( - Belt.Id.hashableU( - ~hash=(. a: int) => land(a, 255), - ~eq=(. a, b) => a == b, - ) +module I1 = unpack( + Belt.Id.hashableU( + ~hash=(. a: int) => land(a, 255), + ~eq=(. a, b) => a == b, ) +) - let s1 = Belt.HashSet.make(~id=module(I1), ~hintSize=40) +let s1 = Belt.HashSet.make(~id=module(I1), ~hintSize=40) - Belt.HashSet.add(s1, 0) - Belt.HashSet.add(s1, 1) - ``` +Belt.HashSet.add(s1, 0) +Belt.HashSet.add(s1, 1) +``` - The invariant must be held: for two elements who are equal, their hashed - value should be the same. +The invariant must be held: for two elements who are equal, their hashed +value should be the same. - Here the compiler would infer `s0` and `s1` having different type so that it - would not mix. +Here the compiler would infer `s0` and `s1` having different type so that it +would not mix. - ```res sig - let s0: Belt.HashSet.t - let s1: Belt.HashSet.t - ``` +## Examples - We can add elements to the collection (see last two lines in the example - above). Since this is an mutable data structure, `s1` will contain two pairs. +```rescript +let s0: Belt.HashSet.t +let s1: Belt.HashSet.t +``` + +We can add elements to the collection (see last two lines in the example +above). Since this is an mutable data structure, `s1` will contain two pairs. */ -/** Specalized when key type is `int`, more efficient - than the generic type */ +/** Specalized when key type is `int`, more efficient than the generic type */ module Int = Belt_HashSetInt -/** Specalized when key type is `string`, more efficient - than the generic type */ +/** Specalized when key type is `string`, more efficient than the generic type */ module String = Belt_HashSetString /* TODO: add a poly module diff --git a/jscomp/others/belt_HashSetInt.resi b/jscomp/others/belt_HashSetInt.resi index 85a7e6e541..05325e845a 100644 --- a/jscomp/others/belt_HashSetInt.resi +++ b/jscomp/others/belt_HashSetInt.resi @@ -23,12 +23,12 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.HashSet`]() specialized with key type to be a primitive type. +This module is [`Belt.HashSet`]() specialized with key type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt.HashSet`]() except its key type is fixed, - and identity is not needed(using the built-in one) +It is more efficient in general, the API is the same with [`Belt.HashSet`]() except its key type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.HashSet`]() +**See** [`Belt.HashSet`]() */ type key = int diff --git a/jscomp/others/belt_HashSetString.resi b/jscomp/others/belt_HashSetString.resi index bbe2617b3f..3c2532f418 100644 --- a/jscomp/others/belt_HashSetString.resi +++ b/jscomp/others/belt_HashSetString.resi @@ -23,12 +23,12 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.HashSet`]() specialized with key type to be a primitive type. +This module is [`Belt.HashSet`]() specialized with key type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt.HashSet`]() except its key type is fixed, - and identity is not needed(using the built-in one) +It is more efficient in general, the API is the same with [`Belt.HashSet`]() except its key type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.HashSet`]() +**See** [`Belt.HashSet`]() */ type key = string diff --git a/jscomp/others/belt_Id.resi b/jscomp/others/belt_Id.resi index 04b07e9d63..72aecc4274 100644 --- a/jscomp/others/belt_Id.resi +++ b/jscomp/others/belt_Id.resi @@ -23,36 +23,36 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - [`Belt.Id`]() +[`Belt.Id`]() - Provide utiliites to create identified comparators or hashes for - data structures used below. +Provide utiliites to create identified comparators or hashes for +data structures used below. - It create a unique identifer per module of functions so that different data structures with slightly different - comparison functions won't mix. +It create a unique identifer per module of functions so that different data structures with slightly different +comparison functions won't mix. */ /** - `('a, 'id) hash` +`('a, 'id) hash` - Its runtime represenation is a `hash` function, but signed with a - type parameter, so that different hash functions type mismatch +Its runtime represenation is a `hash` function, but signed with a +type parameter, so that different hash functions type mismatch */ type hash<'a, 'id> /** - `('a, 'id) eq` +`('a, 'id) eq` - Its runtime represenation is an `eq` function, but signed with a - type parameter, so that different hash functions type mismatch +Its runtime represenation is an `eq` function, but signed with a +type parameter, so that different hash functions type mismatch */ type eq<'a, 'id> /** - `('a,'id) cmp` +`('a,'id) cmp` - Its runtime representation is a `cmp` function, but signed with a - type parameter, so that different hash functions type mismatch +Its runtime representation is a `cmp` function, but signed with a +type parameter, so that different hash functions type mismatch */ type cmp<'a, 'id> @@ -63,15 +63,15 @@ module type Comparable = { } /** - `('key, 'id) cmparable` is a module of functions, here it only includes `cmp`. +`('key, 'id) cmparable` is a module of functions, here it only includes `cmp`. - Unlike normal functions, when created, it comes with a unique identity (guaranteed - by the type system). +Unlike normal functions, when created, it comes with a unique identity (guaranteed +by the type system). - It can be created using function [`comparableU`]() or [`comparable`](). +It can be created using function [`comparableU`]() or [`comparable`](). - The idea of a unique identity when created is that it makes sure two sets would type - mismatch if they use different comparison function +The idea of a unique identity when created is that it makes sure two sets would type +mismatch if they use different comparison function */ type comparable<'key, 'id> = module(Comparable with type t = 'key and type identity = 'id) @@ -92,14 +92,15 @@ module MakeComparable: ( let comparableU: (~cmp: (. 'a, 'a) => int) => module(Comparable with type t = 'a) /** - ``` - module C = ( - val Belt.Id.comparable ~cmp:(compare : int -> int -> int) - ) - let m = Belt.Set.make(module C) - ``` - - Note that the name of C can not be ignored +## Examples + +```rescript +module C = ( + val Belt.Id.comparable ~cmp:(compare : int -> int -> int) +) +let m = Belt.Set.make(module C) +``` +Note that the name of C can not be ignored */ let comparable: (~cmp: ('a, 'a) => int) => module(Comparable with type t = 'a) @@ -111,15 +112,15 @@ module type Hashable = { } /** - `('key, 'id) hashable` is a module of functions, here it only includes `hash`, `eq`. +`('key, 'id) hashable` is a module of functions, here it only includes `hash`, `eq`. - Unlike normal functions, when created, it comes with a unique identity (guaranteed - by the type system). +Unlike normal functions, when created, it comes with a unique identity (guaranteed +by the type system). - It can be created using function [`hashableU`]() or [`hashable`](). +It can be created using function [`hashableU`]() or [`hashable`](). - The idea of a unique identity when created is that it makes sure two hash sets would type - mismatch if they use different comparison function +The idea of a unique identity when created is that it makes sure two hash sets would type +mismatch if they use different comparison function */ type hashable<'key, 'id> = module(Hashable with type t = 'key and type identity = 'id) diff --git a/jscomp/others/belt_Int.resi b/jscomp/others/belt_Int.resi index 2c414e40b1..0d64b76458 100644 --- a/jscomp/others/belt_Int.resi +++ b/jscomp/others/belt_Int.resi @@ -23,82 +23,98 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module includes convenience methods for handling `int` types. +This module includes convenience methods for handling `int` types. */ /** - Converts a given `int` to a `float`. +Converts a given `int` to a `float`. - ```res example - Js.log(Belt.Int.toFloat(1) === 1.0) /* true */ - ``` +## Examples + +```rescript +Js.log(Belt.Int.toFloat(1) === 1.0) /* true */ +``` */ external toFloat: int => float = "%identity" /** - Converts a given `float` to an `int`. +Converts a given `float` to an `int`. + +## Examples - ```res example - Js.log(Belt.Int.fromFloat(1.0) === 1) /* true */ - ``` +```rescript +Js.log(Belt.Int.fromFloat(1.0) === 1) /* true */ +``` */ external fromFloat: float => int = "%intoffloat" /** - Converts a given `string` to an `int`. Returns `Some(int)` when the input is a number, `None` otherwise. +Converts a given `string` to an `int`. Returns `Some(int)` when the input is a number, `None` otherwise. - ```res example - Js.log(Belt.Int.fromString("1") === Some(1)) /* true */ - ``` +## Examples + +```rescript +Js.log(Belt.Int.fromString("1") === Some(1)) /* true */ +``` */ let fromString: string => option /** - Converts a given `int` to a `string`. Uses the JavaScript `String` constructor under the hood. +Converts a given `int` to a `string`. Uses the JavaScript `String` constructor under the hood. + +## Examples - ```res example - Js.log(Belt.Int.toString(1) === "1") /* true */ - ``` +```rescript +Js.log(Belt.Int.toString(1) === "1") /* true */ +``` */ @val external toString: int => string = "String" /** - Addition of two `int` values. Same as the addition from `Pervasives`. +Addition of two `int` values. Same as the addition from `Pervasives`. - ```res example - open Belt.Int - Js.log(2 + 2 === 4) /* true */ - ``` +## Examples + +```rescript +open Belt.Int +Js.log(2 + 2 === 4) /* true */ +``` */ external \"+": (int, int) => int = "%addint" /** - Subtraction of two `int` values. Same as the subtraction from `Pervasives`. +Subtraction of two `int` values. Same as the subtraction from `Pervasives`. + +## Examples - ```res example - open Belt.Int - Js.log(2 - 1 === 1) /* true */ - ``` +```rescript +open Belt.Int +Js.log(2 - 1 === 1) /* true */ +``` */ external \"-": (int, int) => int = "%subint" /** - Multiplication of two `int` values. Same as the multiplication from `Pervasives`. +Multiplication of two `int` values. Same as the multiplication from `Pervasives`. - ```res example - open Belt.Int - Js.log(2 * 2 === 4) /* true */ - ``` +## Examples + +```rescript +open Belt.Int +Js.log(2 * 2 === 4) /* true */ +``` */ external \"*": (int, int) => int = "%mulint" /** - Division of two `int` values. Same as the division from `Pervasives`. +Division of two `int` values. Same as the division from `Pervasives`. + +## Examples - ```res example - open Belt.Int - Js.log(4 / 2 === 2); /* true */ - ``` +```rescript +open Belt.Int +Js.log(4 / 2 === 2); /* true */ +``` */ external \"/": (int, int) => int = "%divint" diff --git a/jscomp/others/belt_List.resi b/jscomp/others/belt_List.resi index cb1b495b68..15811ed7d0 100644 --- a/jscomp/others/belt_List.resi +++ b/jscomp/others/belt_List.resi @@ -23,122 +23,140 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Collection functions for manipulating the `list` data structures, a singly-linked list. +Collection functions for manipulating the `list` data structures, a singly-linked list. - **Prefer Array** if you need any of the following: +**Prefer Array** if you need any of the following: - - Random access of element - - Better interop with JavaScript - - Better memory usage & performance. +- Random access of element +- Better interop with JavaScript +- Better memory usage & performance. */ /** `'a t` is compatible with built-in `list` type */ type t<'a> = list<'a> /** - Returns the length of a list. +Returns the length of a list. - ```res example - Belt.List.length(list{1, 2, 3}) // 3 - ``` +## Examples + +```rescript +Belt.List.length(list{1, 2, 3}) // 3 +``` */ let length: t<'a> => int -/** **See** [`length`](##length) */ +/** See `Belt.List.length` */ let size: t<'a> => int /** - Returns `Some(value)` where `value` is the first element in the list, or - `None` if `someList` is an empty list. +Returns `Some(value)` where `value` is the first element in the list, or +`None` if `someList` is an empty list. - ```res example - Belt.List.head(list{}) // None - Belt.List.head(list{1, 2, 3}) // Some(1) - ``` +## Examples + +```rescript +Belt.List.head(list{}) // None +Belt.List.head(list{1, 2, 3}) // Some(1) +``` */ let head: t<'a> => option<'a> /** - Same as [head](#head), but raises an exception if `someList` is empty. Use - with care. +Same as `Belt.List.head` but raises an exception if `someList` is empty. Use +with care. - ```res example - Belt.List.headExn(list{1, 2, 3}) // 1 +## Examples - Belt.List.headExn(list{}) // Raises an Error - ``` +```rescript +Belt.List.headExn(list{1, 2, 3}) // 1 + +Belt.List.headExn(list{}) // Raises an Error +``` */ let headExn: t<'a> => 'a /** - Returns `None` if `someList` is empty, otherwise it returns `Some(tail)` - where `tail` is everything except the first element of `someList`. +Returns `None` if `someList` is empty, otherwise it returns `Some(tail)` +where `tail` is everything except the first element of `someList`. - ```res example - Belt.List.tail(list{1, 2, 3}) // Some(list{2, 3}) +## Examples - Belt.List.tail(list{}) // None - ``` +```rescript +Belt.List.tail(list{1, 2, 3}) // Some(list{2, 3}) + +Belt.List.tail(list{}) // None +``` */ let tail: t<'a> => option> /** - Same as [tail](#tail), but raises an exception if `someList` is empty. Use - with care. +Same as `Belt.List.tail` but raises an exception if `someList` is empty. Use +with care. - ```res example - Belt.List.tailExn(list{1, 2, 3}) // list{2, 3} +## Examples - Belt.List.tailExn(list{}) // Raises an Error - ``` +```rescript +Belt.List.tailExn(list{1, 2, 3}) // list{2, 3} + +Belt.List.tailExn(list{}) // Raises an Error +``` */ let tailExn: t<'a> => t<'a> /** - Adds `value` to the beginning of `someList`. +Adds `value` to the beginning of `someList`. - ```res example - Belt.List.add(list{2, 3}, 1) // list{1, 2, 3} +## Examples - Belt.List.add(list{"World", "!"}, "Hello") // list{"Hello", "World", "!"} - ``` +```rescript +Belt.List.add(list{2, 3}, 1) // list{1, 2, 3} + +Belt.List.add(list{"World", "!"}, "Hello") // list{"Hello", "World", "!"} +``` */ let add: (t<'a>, 'a) => t<'a> /** - Return the nth element in `someList`, or `None` if `index` is larger than the - length. +Return the nth element in `someList`, or `None` if `index` is larger than the +length. - ```res example - let abc = list{"A", "B", "C"} +## Examples - abc->Belt.List.get(1) // Some("B") +```rescript +let abc = list{"A", "B", "C"} - abc->Belt.List.get(4) // None - ``` +abc->Belt.List.get(1) // Some("B") + +abc->Belt.List.get(4) // None +``` */ let get: (t<'a>, int) => option<'a> /** - Same as [get](#get), but raises an exception if `index` is larger than the - length. Use with care. +Same as `Belt.List.get` but raises an exception if `index` is larger than the +length. Use with care. + +## Examples - ```res example - let abc = list{"A", "B", "C"} +```rescript +let abc = list{"A", "B", "C"} - abc->Belt.List.getExn(1) // "B" +abc->Belt.List.getExn(1) // "B" - abc->Belt.List.getExn(4) // Raises an Error - ``` +abc->Belt.List.getExn(4) // Raises an Error +``` */ let getExn: (t<'a>, int) => 'a /** - Returns a list of length `numItems` with each element filled with value `v`. Returns an empty list if `numItems` is negative. +Returns a list of length `numItems` with each element filled with value `v`. Returns an empty list if `numItems` is negative. + +## Examples - ```res example - Belt.List.make(3, 1) // list{1, 1, 1} - ``` +```rescript +Belt.List.make(3, 1) // list{1, 1, 1} +``` */ let make: (int, 'a) => t<'a> @@ -149,7 +167,9 @@ let makeByU: (int, (. int) => 'a) => t<'a> Return a list of length `numItems` with element `i` initialized with `f(i)`. Returns an empty list if `numItems` is negative. -```res example +## Examples + +```rescript Belt.List.makeBy(5, i => i) // list{0, 1, 2, 3, 4} Belt.List.makeBy(5, i => i * i) // list{0, 1, 4, 9, 16} @@ -158,31 +178,37 @@ Belt.List.makeBy(5, i => i * i) // list{0, 1, 4, 9, 16} let makeBy: (int, int => 'a) => t<'a> /** - Returns a new list in random order. +Returns a new list in random order. - ```res example - Belt.List.shuffle(list{1, 2, 3}) // list{2, 1, 3} - ``` +## Examples + +```rescript +Belt.List.shuffle(list{1, 2, 3}) // list{2, 1, 3} +``` */ let shuffle: t<'a> => t<'a> /** - Return a new list, dropping the first `n` elements. Returns `None` if `someList` has fewer than `n` elements. +Return a new list, dropping the first `n` elements. Returns `None` if `someList` has fewer than `n` elements. + +## Examples - ```res example - list{1, 2, 3}->Belt.List.drop(2) // Some(list{3}) +```rescript +list{1, 2, 3}->Belt.List.drop(2) // Some(list{3}) - list{1, 2, 3}->Belt.List.drop(3) // Some(list{}) +list{1, 2, 3}->Belt.List.drop(3) // Some(list{}) - list{1, 2, 3}->Belt.List.drop(4) // None - ``` +list{1, 2, 3}->Belt.List.drop(4) // None +``` */ let drop: (t<'a>, int) => option> /** Returns a list with the first `n` elements from `someList`, or `None` if `someList` has fewer than `n` elements. -```res example +## Examples + +```rescript list{1, 2, 3}->Belt.List.take(1) // Some(list{1}) list{1, 2, 3}->Belt.List.take(2) // Some(list{1, 2}) @@ -193,50 +219,60 @@ list{1, 2, 3}->Belt.List.take(4) // None let take: (t<'a>, int) => option> /** - Split the list `someList` at `index`. Returns `None` when the length of `someList` is less than `index`. +Split the list `someList` at `index`. Returns `None` when the length of `someList` is less than `index`. - ```res example - list{"Hello", "World"}->Belt.List.splitAt(1) // Some((list{"Hello"}, list{"World"})) +## Examples - list{0, 1, 2, 3, 4}->Belt.List.splitAt(2) // Some((list{0, 1}, list{2, 3, 4})) - ``` +```rescript +list{"Hello", "World"}->Belt.List.splitAt(1) // Some((list{"Hello"}, list{"World"})) + +list{0, 1, 2, 3, 4}->Belt.List.splitAt(2) // Some((list{0, 1}, list{2, 3, 4})) +``` */ let splitAt: (t<'a>, int) => option<(list<'a>, list<'a>)> /** - Returns the list obtained by adding `secondList` after `firstList`. +Returns the list obtained by adding `secondList` after `firstList`. - ```res example - Belt.List.concat(list{1, 2, 3}, list{4, 5}) // list{1, 2, 3, 4, 5} - ``` +## Examples + +```rescript +Belt.List.concat(list{1, 2, 3}, list{4, 5}) // list{1, 2, 3, 4, 5} +``` */ let concat: (t<'a>, t<'a>) => t<'a> /** - Returns the list obtained by concatenating all the lists in array `a`, in - order. +Returns the list obtained by concatenating all the lists in array `a`, in +order. + +## Examples - ```res example - Belt.List.concatMany([list{1, 2, 3}, list{}, list{3}]) // list{1, 2, 3, 3} - ``` +```rescript +Belt.List.concatMany([list{1, 2, 3}, list{}, list{3}]) // list{1, 2, 3, 3} +``` */ let concatMany: array> => t<'a> /** - Equivalent to writing: `concat(reverse(firstList, secondList)` +Equivalent to writing: `concat(reverse(firstList, secondList)` + +## Examples - ```res example - Belt.List.reverseConcat(list{1, 2}, list{3, 4}) // list{2, 1, 3, 4} - ``` +```rescript +Belt.List.reverseConcat(list{1, 2}, list{3, 4}) // list{2, 1, 3, 4} +``` */ let reverseConcat: (t<'a>, t<'a>) => t<'a> /** - Return the list obtained by concatenating all the lists in list `ls`, in order. +Return the list obtained by concatenating all the lists in list `ls`, in order. + +## Examples - ```res example - Belt.List.flatten(list{list{1, 2, 3}, list{}, list{3}}) // list{1, 2, 3, 3} - ``` +```rescript +Belt.List.flatten(list{list{1, 2, 3}, list{}, list{3}}) // list{1, 2, 3, 3} +``` */ let flatten: t> => t<'a> @@ -244,20 +280,24 @@ let flatten: t> => t<'a> let mapU: (t<'a>, (. 'a) => 'b) => t<'b> /** - Returns a new list with `f` applied to each element of `someList`. +Returns a new list with `f` applied to each element of `someList`. + +## Examples - ```res example - list{1, 2}->Belt.List.map(x => x + 1) // list{3, 4} - ``` +```rescript +list{1, 2}->Belt.List.map(x => x + 1) // list{3, 4} +``` */ let map: (t<'a>, 'a => 'b) => t<'b> /** - Returns a list of pairs from the two lists with the length of the shorter list. +Returns a list of pairs from the two lists with the length of the shorter list. + +## Examples - ```res example - Belt.List.zip(list{1, 2}, list{3, 4, 5}) // list{(1, 3), (2, 4)} - ``` +```rescript +Belt.List.zip(list{1, 2}, list{3, 4, 5}) // list{(1, 3), (2, 4)} +``` */ let zip: (t<'a>, t<'b>) => t<('a, 'b)> @@ -265,11 +305,13 @@ let zip: (t<'a>, t<'b>) => t<('a, 'b)> let zipByU: (t<'a>, t<'b>, (. 'a, 'b) => 'c) => t<'c> /** - **See:** [zip](#zip) +See [Belt.List.zip](#zip) + +## Examples - ```res example - Belt.List.zipBy(list{1, 2, 3}, list{4, 5}, (a, b) => 2 * a + b) // list{6, 9} - ``` +```rescript +Belt.List.zipBy(list{1, 2, 3}, list{4, 5}, (a, b) => 2 * a + b) // list{6, 9} +``` */ let zipBy: (t<'a>, t<'b>, ('a, 'b) => 'c) => t<'c> @@ -277,30 +319,36 @@ let zipBy: (t<'a>, t<'b>, ('a, 'b) => 'c) => t<'c> let mapWithIndexU: (t<'a>, (. int, 'a) => 'b) => t<'b> /** - Applies `f` to each element of `someList`. - Function `f` takes two arguments: the index starting from 0 and the element from `someList`, in that order. +Applies `f` to each element of `someList`. +Function `f` takes two arguments: the index starting from 0 and the element from `someList`, in that order. + +## Examples - ```res example - list{1, 2, 3}->Belt.List.mapWithIndex((index, x) => index + x) // list{1, 3, 5} - ``` +```rescript +list{1, 2, 3}->Belt.List.mapWithIndex((index, x) => index + x) // list{1, 3, 5} +``` */ let mapWithIndex: (t<'a>, (int, 'a) => 'b) => t<'b> /** - Converts the given array to a list. +Converts the given array to a list. + +## Examples - ```res example - Belt.List.fromArray([1, 2, 3]) // list{1, 2, 3} - ``` +```rescript +Belt.List.fromArray([1, 2, 3]) // list{1, 2, 3} +``` */ let fromArray: array<'a> => t<'a> /** - Converts the given list to an array. +Converts the given list to an array. - ```res example - Belt.List.toArray(list{1, 2, 3}) // [1, 2, 3] - ``` +## Examples + +```rescript +Belt.List.toArray(list{1, 2, 3}) // [1, 2, 3] +``` */ let toArray: t<'a> => array<'a> @@ -310,11 +358,13 @@ let toArray: t<'a> => array<'a> /* val fromJson : json -> (json -> 'a [@bs]) -> 'a t */ /** - Returns a new list whose elements are those of `someList` in reversed order. +Returns a new list whose elements are those of `someList` in reversed order. - ```res example - Belt.List.reverse(list{1, 2, 3}) /* list{3, 2, 1} */ - ``` +## Examples + +```rescript +Belt.List.reverse(list{1, 2, 3}) /* list{3, 2, 1} */ +``` */ let reverse: t<'a> => t<'a> @@ -322,15 +372,17 @@ let reverse: t<'a> => t<'a> let mapReverseU: (t<'a>, (. 'a) => 'b) => t<'b> /** - Equivalent to: +Equivalent to: - ```res - map(someList, f)->reverse - ``` +```res +map(someList, f)->reverse +``` + +## Examples - ```res example - list{3, 4, 5}->Belt.List.mapReverse(x => x * x) /* list{25, 16, 9} */ - ``` +```rescript +list{3, 4, 5}->Belt.List.mapReverse(x => x * x) /* list{25, 16, 9} */ +``` */ let mapReverse: (t<'a>, 'a => 'b) => t<'b> @@ -338,18 +390,20 @@ let mapReverse: (t<'a>, 'a => 'b) => t<'b> let forEachU: (t<'a>, (. 'a) => 'b) => unit /** - Call `f` on each element of `someList` from the beginning to end. - `f` returns `unit`, so no new array is created. Use `forEach` when you are primarily concerned with repetitively creating side effects. +Call `f` on each element of `someList` from the beginning to end. +`f` returns `unit`, so no new array is created. Use `forEach` when you are primarily concerned with repetitively creating side effects. - ```res example - Belt.List.forEach(list{"a", "b", "c"}, x => Js.log("Item: " ++ x)) - /* - prints: - Item: a - Item: b - Item: c - */ - ``` +## Examples + +```rescript +Belt.List.forEach(list{"a", "b", "c"}, x => Js.log("Item: " ++ x)) +/* + prints: + Item: a + Item: b + Item: c +*/ +``` */ let forEach: (t<'a>, 'a => 'b) => unit @@ -357,20 +411,22 @@ let forEach: (t<'a>, 'a => 'b) => unit let forEachWithIndexU: (t<'a>, (. int, 'a) => 'b) => unit /** - Call `f` on each element of `someList` from beginning to end. - Function `f` takes two arguments: the index starting from 0 and the element from `someList`. `f` returns `unit`. +Call `f` on each element of `someList` from beginning to end. +Function `f` takes two arguments: the index starting from 0 and the element from `someList`. `f` returns `unit`. + +## Examples - ```res example - Belt.List.forEachWithIndex(list{"a", "b", "c"}, (index, x) => { - Js.log("Item " ++ Belt.Int.toString(index) ++ " is " ++ x) - }) - /* - prints: - Item 0 is a - Item 1 is b - Item 2 is cc - */ - ``` +```rescript +Belt.List.forEachWithIndex(list{"a", "b", "c"}, (index, x) => { + Js.log("Item " ++ Belt.Int.toString(index) ++ " is " ++ x) +}) +/* + prints: + Item 0 is a + Item 1 is b + Item 2 is cc +*/ +``` */ let forEachWithIndex: (t<'a>, (int, 'a) => 'b) => unit @@ -378,15 +434,17 @@ let forEachWithIndex: (t<'a>, (int, 'a) => 'b) => unit let reduceU: (t<'a>, 'b, (. 'b, 'a) => 'b) => 'b /** - Applies `f` to each element of `someList` from beginning to end. Function `f` has two parameters: the item from the list and an “accumulator”, which starts with a value of `initialValue`. reduce returns the final value of the accumulator. +Applies `f` to each element of `someList` from beginning to end. Function `f` has two parameters: the item from the list and an “accumulator”, which starts with a value of `initialValue`. reduce returns the final value of the accumulator. + +## Examples - ```res example - list{1, 2, 3, 4}->Belt.List.reduce(0, (a, b) => a + b) /* 10 */ +```rescript +list{1, 2, 3, 4}->Belt.List.reduce(0, (a, b) => a + b) /* 10 */ - /* same as */ +/* same as */ - list{1, 2, 3, 4}->Belt.List.reduce(0, (acc, item) => acc + item) /* 10 */ - ``` +list{1, 2, 3, 4}->Belt.List.reduce(0, (acc, item) => acc + item) /* 10 */ +``` */ let reduce: (t<'a>, 'b, ('b, 'a) => 'b) => 'b @@ -394,11 +452,13 @@ let reduce: (t<'a>, 'b, ('b, 'a) => 'b) => 'b let reduceWithIndexU: (t<'a>, 'b, (. 'b, 'a, int) => 'b) => 'b /** - Applies `f` to each element of `someList` from beginning to end. Function `f` has three parameters: the item from the list and an “accumulator”, which starts with a value of `initialValue` and the index of each element. `reduceWithIndex` returns the final value of the accumulator. +Applies `f` to each element of `someList` from beginning to end. Function `f` has three parameters: the item from the list and an “accumulator”, which starts with a value of `initialValue` and the index of each element. `reduceWithIndex` returns the final value of the accumulator. + +## Examples - ```res example - list{1, 2, 3, 4}->Belt.List.reduceWithIndex(0, (acc, item, index) => acc + item + index) /* 16 */ - ``` +```rescript +list{1, 2, 3, 4}->Belt.List.reduceWithIndex(0, (acc, item, index) => acc + item + index) /* 16 */ +``` */ let reduceWithIndex: (t<'a>, 'b, ('b, 'a, int) => 'b) => 'b @@ -406,16 +466,18 @@ let reduceWithIndex: (t<'a>, 'b, ('b, 'a, int) => 'b) => 'b let reduceReverseU: (t<'a>, 'b, (. 'b, 'a) => 'b) => 'b /** - Works like [reduce](#reduce), except that function `f` is applied to each - item of `someList` from the last back to the first. +Works like [reduce](#reduce), except that function `f` is applied to each +item of `someList` from the last back to the first. + +## Examples - ```res example - list{1, 2, 3, 4}->Belt.List.reduceReverse(0, (a, b) => a + b) /* 10 */ +```rescript +list{1, 2, 3, 4}->Belt.List.reduceReverse(0, (a, b) => a + b) /* 10 */ - list{1, 2, 3, 4}->Belt.List.reduceReverse(10, (a, b) => a - b) /* 0 */ +list{1, 2, 3, 4}->Belt.List.reduceReverse(10, (a, b) => a - b) /* 0 */ - list{1, 2, 3, 4}->Belt.List.reduceReverse(list{}, Belt.List.add) // list{1, 2, 3, 4} - ``` +list{1, 2, 3, 4}->Belt.List.reduceReverse(list{}, Belt.List.add) // list{1, 2, 3, 4} +``` */ let reduceReverse: (t<'a>, 'b, ('b, 'a) => 'b) => 'b @@ -423,12 +485,14 @@ let reduceReverse: (t<'a>, 'b, ('b, 'a) => 'b) => 'b let mapReverse2U: (t<'a>, t<'b>, (. 'a, 'b) => 'c) => t<'c> /** - Equivalent to: `zipBy(xs, ys, f)->reverse` +Equivalent to: `zipBy(xs, ys, f)->reverse` + +## Examples - ```res example +```rescript - Belt.List.mapReverse2(list{1, 2, 3}, list{1, 2}, (a, b) => a + b) // list{4, 2} - ``` +Belt.List.mapReverse2(list{1, 2, 3}, list{1, 2}, (a, b) => a + b) // list{4, 2} +``` */ let mapReverse2: (t<'a>, t<'b>, ('a, 'b) => 'c) => t<'c> @@ -436,17 +500,19 @@ let mapReverse2: (t<'a>, t<'b>, ('a, 'b) => 'c) => t<'c> let forEach2U: (t<'a>, t<'b>, (. 'a, 'b) => 'c) => unit /** - Stops at the length of the shorter list. +Stops at the length of the shorter list. + +## Examples - ```res example - Belt.List.forEach2(list{"Z", "Y"}, list{"A", "B", "C"}, (x, y) => Js.log2(x, y)) +```rescript +Belt.List.forEach2(list{"Z", "Y"}, list{"A", "B", "C"}, (x, y) => Js.log2(x, y)) - /* - prints: - "Z" "A" - "Y" "B" - */ - ``` +/* + prints: + "Z" "A" + "Y" "B" +*/ +``` */ let forEach2: (t<'a>, t<'b>, ('a, 'b) => 'c) => unit @@ -454,11 +520,13 @@ let forEach2: (t<'a>, t<'b>, ('a, 'b) => 'c) => unit let reduce2U: (t<'b>, t<'c>, 'a, (. 'a, 'b, 'c) => 'a) => 'a /** - Applies `f` to each element of `firstList` and `secondList` from beginning to end. Stops with the shorter list. Function `f` has three parameters: an “accumulator” which starts with a value of `initialValue`, an item from `firstList`, and an item from `secondList`. `reduce2` returns the final value of the accumulator. +Applies `f` to each element of `firstList` and `secondList` from beginning to end. Stops with the shorter list. Function `f` has three parameters: an “accumulator” which starts with a value of `initialValue`, an item from `firstList`, and an item from `secondList`. `reduce2` returns the final value of the accumulator. - ```res example - Belt.List.reduce2(list{1, 2, 3}, list{4, 5}, 0, (acc, x, y) => acc + x * x + y) /* 0 + (1 * 1 + 4) + (2 * 2 + 5) */ - ``` +## Examples + +```rescript +Belt.List.reduce2(list{1, 2, 3}, list{4, 5}, 0, (acc, x, y) => acc + x * x + y) /* 0 + (1 * 1 + 4) + (2 * 2 + 5) */ +``` */ let reduce2: (t<'b>, t<'c>, 'a, ('a, 'b, 'c) => 'a) => 'a @@ -466,15 +534,17 @@ let reduce2: (t<'b>, t<'c>, 'a, ('a, 'b, 'c) => 'a) => 'a let reduceReverse2U: (t<'a>, t<'b>, 'c, (. 'c, 'a, 'b) => 'c) => 'c /** - Applies `f` to each element of `firstList` and `secondList` from end to - beginning. Stops with the shorter list. Function `f` has three parameters: an - “accumulator” which starts with a value of init, an item from `firstList`, - and an item from `secondList`. `reduce2` returns the final value of the - accumulator. +Applies `f` to each element of `firstList` and `secondList` from end to +beginning. Stops with the shorter list. Function `f` has three parameters: an +“accumulator” which starts with a value of init, an item from `firstList`, +and an item from `secondList`. `reduce2` returns the final value of the +accumulator. - ```res example - Belt.List.reduceReverse2(list{1, 2, 3}, list{4, 5}, 0, (acc, x, y) => acc + x * x + y) /* + (1 * 1 + 4) + (2 * 2 + 5) */ - ``` +## Examples + +```rescript +Belt.List.reduceReverse2(list{1, 2, 3}, list{4, 5}, 0, (acc, x, y) => acc + x * x + y) /* + (1 * 1 + 4) + (2 * 2 + 5) */ +``` */ let reduceReverse2: (t<'a>, t<'b>, 'c, ('c, 'a, 'b) => 'c) => 'c @@ -482,15 +552,17 @@ let reduceReverse2: (t<'a>, t<'b>, 'c, ('c, 'a, 'b) => 'c) => 'c let everyU: (t<'a>, (. 'a) => bool) => bool /** - Returns `true` if all elements satisfy `pred`, where `pred` is a predicate: a function taking an element and returning a bool. +Returns `true` if all elements satisfy `pred`, where `pred` is a predicate: a function taking an element and returning a bool. + +## Examples - ```res example - let isBelow10 = value => value < 10 +```rescript +let isBelow10 = value => value < 10 - list{1, 9, 8, 2}->Belt.List.every(isBelow10) /* true */ +list{1, 9, 8, 2}->Belt.List.every(isBelow10) /* true */ - list{1, 99, 8, 2}->Belt.List.every(isBelow10) /* false */ - ``` +list{1, 99, 8, 2}->Belt.List.every(isBelow10) /* false */ +``` */ let every: (t<'a>, 'a => bool) => bool @@ -498,17 +570,19 @@ let every: (t<'a>, 'a => bool) => bool let someU: (t<'a>, (. 'a) => bool) => bool /** - Returns `true` if at least _one_ of the elements in `someList` satisfies - `pred`, where `pred` is a predicate: a function taking an element and - returning a bool. +Returns `true` if at least _one_ of the elements in `someList` satisfies +`pred`, where `pred` is a predicate: a function taking an element and +returning a bool. + +## Examples - ```res example - let isAbove100 = value => value > 100 +```rescript +let isAbove100 = value => value > 100 - list{101, 1, 2, 3}->Belt.List.some(isAbove100) /* true */ +list{101, 1, 2, 3}->Belt.List.some(isAbove100) /* true */ - list{1, 2, 3, 4}->Belt.List.some(isAbove100) /* false */ - ``` +list{1, 2, 3, 4}->Belt.List.some(isAbove100) /* false */ +``` */ let some: (t<'a>, 'a => bool) => bool @@ -516,18 +590,20 @@ let some: (t<'a>, 'a => bool) => bool let every2U: (t<'a>, t<'b>, (. 'a, 'b) => bool) => bool /** - Returns `true` if predicate `pred(a, b)` is `true` for all pairs of elements - up to the shorter length (i.e. `min(length(firstList), length(secondList))`) +Returns `true` if predicate `pred(a, b)` is `true` for all pairs of elements +up to the shorter length (i.e. `min(length(firstList), length(secondList))`) + +## Examples - ```res example - Belt.List.every2(list{1, 2, 3}, list{0, 1}, (a, b) => a > b) /* true */ +```rescript +Belt.List.every2(list{1, 2, 3}, list{0, 1}, (a, b) => a > b) /* true */ - Belt.List.every2(list{}, list{1}, (a, b) => a > b) /* true */ +Belt.List.every2(list{}, list{1}, (a, b) => a > b) /* true */ - Belt.List.every2(list{2, 3}, list{1}, (a, b) => a > b) /* true */ +Belt.List.every2(list{2, 3}, list{1}, (a, b) => a > b) /* true */ - Belt.List.every2(list{0, 1}, list{5, 0}, (a, b) => a > b) /* false */ - ``` +Belt.List.every2(list{0, 1}, list{5, 0}, (a, b) => a > b) /* false */ +``` */ let every2: (t<'a>, t<'b>, ('a, 'b) => bool) => bool @@ -535,34 +611,38 @@ let every2: (t<'a>, t<'b>, ('a, 'b) => bool) => bool let some2U: (t<'a>, t<'b>, (. 'a, 'b) => bool) => bool /** - Returns `true` if predicate `pred(a, b)` is true for any pair of elements up - to the shorter length (i.e. `min(length(firstList), length(secondList))`) +Returns `true` if predicate `pred(a, b)` is true for any pair of elements up +to the shorter length (i.e. `min(length(firstList), length(secondList))`) + +## Examples - ```res example - Belt.List.some2(list{1, 2, 3}, list{0, 1}, (a, b) => a > b) /* true */ +```rescript +Belt.List.some2(list{1, 2, 3}, list{0, 1}, (a, b) => a > b) /* true */ - Belt.List.some2(list{}, list{1}, (a, b) => a > b) /* false */ +Belt.List.some2(list{}, list{1}, (a, b) => a > b) /* false */ - Belt.List.some2(list{2, 3}, list{1}, (a, b) => a > b) /* true */ +Belt.List.some2(list{2, 3}, list{1}, (a, b) => a > b) /* true */ - Belt.List.some2(list{0, 1}, list{5, 0}, (a, b) => a > b) /* true */ - ``` +Belt.List.some2(list{0, 1}, list{5, 0}, (a, b) => a > b) /* true */ +``` */ let some2: (t<'a>, t<'b>, ('a, 'b) => bool) => bool /** - Compare two lists solely by length. Returns `-1` if `length(firstList)` is - less than `length(secondList)`, `0` if `length(firstList)` equals - `length(secondList)`, and `1` if `length(firstList)` is greater than - `length(secondList)`. +Compare two lists solely by length. Returns `-1` if `length(firstList)` is +less than `length(secondList)`, `0` if `length(firstList)` equals +`length(secondList)`, and `1` if `length(firstList)` is greater than +`length(secondList)`. - ```res example - Belt.List.cmpByLength(list{1, 2}, list{3, 4, 5, 6}) /* -1 */ +## Examples - Belt.List.cmpByLength(list{1, 2, 3}, list{4, 5, 6}) /* = 0 */ +```rescript +Belt.List.cmpByLength(list{1, 2}, list{3, 4, 5, 6}) /* -1 */ - Belt.List.cmpByLength(list{1, 2, 3, 4}, list{5, 6}) /* = 1 */ - ``` +Belt.List.cmpByLength(list{1, 2, 3}, list{4, 5, 6}) /* = 0 */ + +Belt.List.cmpByLength(list{1, 2, 3, 4}, list{5, 6}) /* = 1 */ +``` */ let cmpByLength: (t<'a>, t<'a>) => int @@ -570,28 +650,30 @@ let cmpByLength: (t<'a>, t<'a>) => int let cmpU: (t<'a>, t<'a>, (. 'a, 'a) => int) => int /** - Compare elements one by one `compareFn(a, b)`. `compareFn` returns a negative number if `a` is "less than" `b`, zero if `a` is "equal to" `b`, a positive number if `a` is "greater than" `b`. +Compare elements one by one `compareFn(a, b)`. `compareFn` returns a negative number if `a` is "less than" `b`, zero if `a` is "equal to" `b`, a positive number if `a` is "greater than" `b`. - The comparison returns the first non-zero result of `compareFn`, or zero if `compareFn` returns zero for all `a` and `b`. +The comparison returns the first non-zero result of `compareFn`, or zero if `compareFn` returns zero for all `a` and `b`. - If all items have compared equal, but `firstList` is exhausted first, return `-1`. (`firstList` is shorter). - If all items have compared equal, but `secondList` is exhausted first, return `1` (`firstList` is longer). +If all items have compared equal, but `firstList` is exhausted first, return `-1`. (`firstList` is shorter). +If all items have compared equal, but `secondList` is exhausted first, return `1` (`firstList` is longer). - ```res example - Belt.List.cmp(list{3}, list{3, 7}, (a, b) => compare(a, b)) /* (-1) */ +## Examples - Belt.List.cmp(list{5, 3}, list{5}, (a, b) => compare(a, b)) /* 1 */ +```rescript +Belt.List.cmp(list{3}, list{3, 7}, (a, b) => compare(a, b)) /* (-1) */ - Belt.List.cmp(list{1, 3, 5}, list{1, 4, 2}, (a, b) => compare(a, b)) /* (-1) */ +Belt.List.cmp(list{5, 3}, list{5}, (a, b) => compare(a, b)) /* 1 */ - Belt.List.cmp(list{1, 3, 5}, list{1, 2, 3}, (a, b) => compare(a, b)) /* 1 */ +Belt.List.cmp(list{1, 3, 5}, list{1, 4, 2}, (a, b) => compare(a, b)) /* (-1) */ - Belt.List.cmp(list{1, 3, 5}, list{1, 3, 5}, (a, b) => compare(a, b)) /* 0 */ - ``` +Belt.List.cmp(list{1, 3, 5}, list{1, 2, 3}, (a, b) => compare(a, b)) /* 1 */ + +Belt.List.cmp(list{1, 3, 5}, list{1, 3, 5}, (a, b) => compare(a, b)) /* 0 */ +``` - **Please note:** The total ordering of List is different from Array, - for Array, we compare the length first and, only if the lengths are equal, elements one by one. - For lists, we just compare elements one by one. +**Please note:** The total ordering of List is different from Array, +for Array, we compare the length first and, only if the lengths are equal, elements one by one. +For lists, we just compare elements one by one. */ let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => int @@ -599,18 +681,20 @@ let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => int let eqU: (t<'a>, t<'a>, (. 'a, 'a) => bool) => bool /** - Check equality of `firstList` and `secondList` using `eqElem` for equality on - elements, where `eqElem` is a function that returns `true` if items `x` and - `y` meet some criterion for equality, `false` otherwise. eq `false` if length - of `firstList` and `secondList` are not the same. +Check equality of `firstList` and `secondList` using `eqElem` for equality on +elements, where `eqElem` is a function that returns `true` if items `x` and +`y` meet some criterion for equality, `false` otherwise. eq `false` if length +of `firstList` and `secondList` are not the same. - ```res example - Belt.List.eq(list{1, 2, 3}, list{1, 2}, (a, b) => a == b) /* false */ +## Examples - Belt.List.eq(list{1, 2}, list{1, 2}, (a, b) => a == b) /* true */ +```rescript +Belt.List.eq(list{1, 2, 3}, list{1, 2}, (a, b) => a == b) /* false */ - Belt.List.eq(list{1, 2, 3}, list{(-1), (-2), (-3)}, (a, b) => abs(a) == abs(b)) /* true */ - ``` +Belt.List.eq(list{1, 2}, list{1, 2}, (a, b) => a == b) /* true */ + +Belt.List.eq(list{1, 2, 3}, list{(-1), (-2), (-3)}, (a, b) => abs(a) == abs(b)) /* true */ +``` */ let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => bool @@ -618,16 +702,18 @@ let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => bool let hasU: (t<'a>, 'b, (. 'a, 'b) => bool) => bool /** - Returns `true` if the list contains at least one element for which - `eqFunction(x)` returns true. +Returns `true` if the list contains at least one element for which +`eqFunction(x)` returns true. + +## Examples - ```res example - list{1, 2, 3}->Belt.List.has(2, (a, b) => a == b) /* true */ +```rescript +list{1, 2, 3}->Belt.List.has(2, (a, b) => a == b) /* true */ - list{1, 2, 3}->Belt.List.has(4, (a, b) => a == b) /* false */ +list{1, 2, 3}->Belt.List.has(4, (a, b) => a == b) /* false */ - list{(-1), (-2), (-3)}->Belt.List.has(2, (a, b) => abs(a) == abs(b)) /* true */ - ``` +list{(-1), (-2), (-3)}->Belt.List.has(2, (a, b) => abs(a) == abs(b)) /* true */ +``` */ let has: (t<'a>, 'b, ('a, 'b) => bool) => bool @@ -635,14 +721,16 @@ let has: (t<'a>, 'b, ('a, 'b) => bool) => bool let getByU: (t<'a>, (. 'a) => bool) => option<'a> /** - Returns `Some(value)` for the first value in `someList` that satisfies the - predicate function `pred`. Returns `None` if no element satisfies the function. +Returns `Some(value)` for the first value in `someList` that satisfies the +predicate function `pred`. Returns `None` if no element satisfies the function. + +## Examples - ```res example - Belt.List.getBy(list{1, 4, 3, 2}, x => x > 3) /* Some(4) */ +```rescript +Belt.List.getBy(list{1, 4, 3, 2}, x => x > 3) /* Some(4) */ - Belt.List.getBy(list{1, 4, 3, 2}, x => x > 4) /* None */ - ``` +Belt.List.getBy(list{1, 4, 3, 2}, x => x > 4) /* None */ +``` */ let getBy: (t<'a>, 'a => bool) => option<'a> @@ -650,29 +738,33 @@ let getBy: (t<'a>, 'a => bool) => option<'a> let keepU: (t<'a>, (. 'a) => bool) => t<'a> /** - Returns a list of all elements in `someList` which satisfy the predicate function `pred`. +Returns a list of all elements in `someList` which satisfy the predicate function `pred`. + +## Examples - ```res example - let isEven = x => mod(x, 2) == 0 +```rescript +let isEven = x => mod(x, 2) == 0 - Belt.List.keep(list{1, 2, 3, 4}, isEven) /* list{2, 4} */ +Belt.List.keep(list{1, 2, 3, 4}, isEven) /* list{2, 4} */ - Belt.List.keep(list{None, Some(2), Some(3), None}, Belt.Option.isSome) /* list{Some(2), Some(3)} */ - ``` +Belt.List.keep(list{None, Some(2), Some(3), None}, Belt.Option.isSome) /* list{Some(2), Some(3)} */ +``` */ let keep: (t<'a>, 'a => bool) => t<'a> @deprecated("This function will soon be deprecated. Please, use `List.keep` instead.") /** - Returns a list of all elements in `someList` which satisfy the predicate function `pred`. +Returns a list of all elements in `someList` which satisfy the predicate function `pred`. + +## Examples - ```res example - let isEven = x => mod(x, 2) == 0 +```rescript +let isEven = x => mod(x, 2) == 0 - Belt.List.filter(list{1, 2, 3, 4}, isEven) /* list{2, 4} */ +Belt.List.filter(list{1, 2, 3, 4}, isEven) /* list{2, 4} */ - Belt.List.filter(list{None, Some(2), Some(3), None}, Belt.Option.isSome) /* list{Some(2), Some(3)} */ - ``` +Belt.List.filter(list{None, Some(2), Some(3), None}, Belt.Option.isSome) /* list{Some(2), Some(3)} */ +``` */ let filter: (t<'a>, 'a => bool) => t<'a> @@ -680,13 +772,15 @@ let filter: (t<'a>, 'a => bool) => t<'a> let keepWithIndexU: (t<'a>, (. 'a, int) => bool) => t<'a> /** - Returns a list of all elements in `someList` which satisfy the predicate function `pred`. +Returns a list of all elements in `someList` which satisfy the predicate function `pred`. - ```res example - let isEven = x => mod(x, 2) == 0 +## Examples - Belt.List.keepWithIndex(list{1, 2, 3, 4}, (_x, index) => isEven(index)) /* list{1, 3} */ - ``` +```rescript +let isEven = x => mod(x, 2) == 0 + +Belt.List.keepWithIndex(list{1, 2, 3, 4}, (_x, index) => isEven(index)) /* list{1, 3} */ +``` */ let keepWithIndex: (t<'a>, ('a, int) => bool) => t<'a> @@ -695,13 +789,15 @@ let keepWithIndex: (t<'a>, ('a, int) => bool) => t<'a> instead." ) /** - Returns a list of all elements in `someList` which satisfy the predicate function `pred`. +Returns a list of all elements in `someList` which satisfy the predicate function `pred`. - ```res example - let isEven = x => mod(x, 2) == 0 +## Examples - Belt.List.filterWithIndex(list{1, 2, 3, 4}, (_x, index) => isEven(index)) /* list{1, 3} */ - ``` +```rescript +let isEven = x => mod(x, 2) == 0 + +Belt.List.filterWithIndex(list{1, 2, 3, 4}, (_x, index) => isEven(index)) /* list{1, 3} */ +``` */ let filterWithIndex: (t<'a>, ('a, int) => bool) => t<'a> @@ -709,23 +805,25 @@ let filterWithIndex: (t<'a>, ('a, int) => bool) => t<'a> let keepMapU: (t<'a>, (. 'a) => option<'b>) => t<'b> /** - Applies `f` to each element of `someList`. If `f(x)` returns `Some(value)`, then `value` is _kept_ in the resulting list. - If `f(x)` returns `None`, the element is _not_ retained in the result. +Applies `f` to each element of `someList`. If `f(x)` returns `Some(value)`, then `value` is _kept_ in the resulting list. +If `f(x)` returns `None`, the element is _not_ retained in the result. - ```res example - let isEven = x => mod(x, 2) == 0 +## Examples - list{1, 2, 3, 4} - ->Belt.List.keepMap(x => - if (isEven(x)) { - Some(x) - } else { - None - } - ) /* list{2, 4} */ +```rescript +let isEven = x => mod(x, 2) == 0 - list{Some(1), Some(2), None}->Belt.List.keepMap(x => x) /* list{1, 2} */ - ``` +list{1, 2, 3, 4} +->Belt.List.keepMap(x => + if (isEven(x)) { + Some(x) + } else { + None + } + ) /* list{2, 4} */ + +list{Some(1), Some(2), None}->Belt.List.keepMap(x => x) /* list{1, 2} */ +``` */ let keepMap: (t<'a>, 'a => option<'b>) => t<'b> @@ -733,29 +831,33 @@ let keepMap: (t<'a>, 'a => option<'b>) => t<'b> let partitionU: (t<'a>, (. 'a) => bool) => (t<'a>, t<'a>) /** - Creates a pair of lists; the first list consists of all elements of `someList` that satisfy the predicate function `pred`; the second list consists of all elements of `someList` that _do not_ satisfy `pred. +Creates a pair of lists; the first list consists of all elements of `someList` that satisfy the predicate function `pred`; the second list consists of all elements of `someList` that _do not_ satisfy `pred. + +In other words: - In other words: +```rescript +(elementsThatSatisfies, elementsThatDoesNotSatisfy) +``` - ```res - (elementsThatSatisfies, elementsThatDoesNotSatisfy) - ``` +## Examples - ```res example - Belt.List.partition(list{1, 2, 3, 4}, x => x > 2) /* (list{3, 4}, list{1, 2}) */ - ``` +```rescript +Belt.List.partition(list{1, 2, 3, 4}, x => x > 2) /* (list{3, 4}, list{1, 2}) */ +``` */ let partition: (t<'a>, 'a => bool) => (t<'a>, t<'a>) /** - Takes a list of pairs and creates a pair of lists. The first list contains all the first items of the pairs; the second list contains all the second items. +Takes a list of pairs and creates a pair of lists. The first list contains all the first items of the pairs; the second list contains all the second items. - ```res example - Belt.List.unzip(list{(1, 2), (3, 4)}) /* (list{1, 3}, list{2, 4}) */ +## Examples - Belt.List.unzip(list{("H", "W"), ("e", "o"), ("l", "r"), ("l", "l"), ("o", "d"), (" ", "!")}) - /* (list{"H", "e", "l", "l", "o", " "}, list{"W", "o", "r", "l", "d", "!"}) */ - ``` +```rescript +Belt.List.unzip(list{(1, 2), (3, 4)}) /* (list{1, 3}, list{2, 4}) */ + +Belt.List.unzip(list{("H", "W"), ("e", "o"), ("l", "r"), ("l", "l"), ("o", "d"), (" ", "!")}) +/* (list{"H", "e", "l", "l", "o", " "}, list{"W", "o", "r", "l", "d", "!"}) */ +``` */ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) @@ -763,15 +865,17 @@ let unzip: t<('a, 'b)> => (t<'a>, t<'b>) let getAssocU: (t<('a, 'c)>, 'b, (. 'a, 'b) => bool) => option<'c> /** - Return the second element of a pair in `someList` where the first element equals `k` as per the predicate function `eqFunction`, or `None` if not found. +Return the second element of a pair in `someList` where the first element equals `k` as per the predicate function `eqFunction`, or `None` if not found. - ```res example - list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.getAssoc(3, (a, b) => a == b) /* Some("c") */ +## Examples - list{(9, "morning"), (15, "afternoon"), (22, "night")} - ->Belt.List.getAssoc(15, (k, item) => k /* 15 */ == item /* 9, 5, 22 */) - /* Some("afternoon") */ - ``` +```rescript +list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.getAssoc(3, (a, b) => a == b) /* Some("c") */ + +list{(9, "morning"), (15, "afternoon"), (22, "night")} +->Belt.List.getAssoc(15, (k, item) => k /* 15 */ == item /* 9, 5, 22 */) +/* Some("afternoon") */ +``` */ let getAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => option<'c> @@ -779,14 +883,16 @@ let getAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => option<'c> let hasAssocU: (t<('a, 'c)>, 'b, (. 'a, 'b) => bool) => bool /** - Returns `true` if there is a pair in `someList` where the first element equals `k` as per the predicate function `eqFunction`. +Returns `true` if there is a pair in `someList` where the first element equals `k` as per the predicate function `eqFunction`. + +## Examples - ```res example - list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.hasAssoc(1, (a, b) => a == b) /* true */ +```rescript +list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.hasAssoc(1, (a, b) => a == b) /* true */ - list{(9, "morning"), (15, "afternoon"), (22, "night")} - ->Belt.List.hasAssoc(25, (k, item) => k /* 25 */ == item /* 9, 5, 22 */) /* false */ - ``` +list{(9, "morning"), (15, "afternoon"), (22, "night")} +->Belt.List.hasAssoc(25, (k, item) => k /* 25 */ == item /* 9, 5, 22 */) /* false */ +``` */ let hasAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => bool @@ -794,15 +900,17 @@ let hasAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => bool let removeAssocU: (t<('a, 'c)>, 'b, (. 'a, 'b) => bool) => t<('a, 'c)> /** - Return a list after removing the first pair whose first value is `k` per the equality predicate `eqFunction`; if not found, return a new list identical to `someList`. +Return a list after removing the first pair whose first value is `k` per the equality predicate `eqFunction`; if not found, return a new list identical to `someList`. + +## Examples - ```res example - list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.removeAssoc(1, (a, b) => a == b) /* list{(2, "b"), (3, "c")} */ +```rescript +list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.removeAssoc(1, (a, b) => a == b) /* list{(2, "b"), (3, "c")} */ - list{(9, "morning"), (15, "afternoon"), (22, "night")} - ->Belt.List.removeAssoc(9, (k, item) => k /* 9 */ == item /* 9, 5, 22 */) - /* list{(15, "afternoon"), (22, "night")} */ - ``` +list{(9, "morning"), (15, "afternoon"), (22, "night")} +->Belt.List.removeAssoc(9, (k, item) => k /* 9 */ == item /* 9, 5, 22 */) +/* list{(15, "afternoon"), (22, "night")} */ +``` */ let removeAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => t<('a, 'c)> @@ -810,23 +918,25 @@ let removeAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => t<('a, 'c)> let setAssocU: (t<('a, 'c)>, 'a, 'c, (. 'a, 'a) => bool) => t<('a, 'c)> /** - If `k` exists in `someList` by satisfying the `eqFunction` predicate, return a new list with the key and value replaced by the new `k` and `v`; otherwise, return a new list with the pair `k`, `v` added to the head of `someList`. +If `k` exists in `someList` by satisfying the `eqFunction` predicate, return a new list with the key and value replaced by the new `k` and `v`; otherwise, return a new list with the pair `k`, `v` added to the head of `someList`. - ```res example - list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.setAssoc(2, "x", (a, b) => a == b) /* list{(1, "a"), (2, "x"), (3, "c")} */ +## Examples - list{(1, "a"), (3, "c")}->Belt.List.setAssoc(2, "b", (a, b) => a == b) /* list{(2, "b"), (1, "a"), (3, "c")} */ +```rescript +list{(1, "a"), (2, "b"), (3, "c")}->Belt.List.setAssoc(2, "x", (a, b) => a == b) /* list{(1, "a"), (2, "x"), (3, "c")} */ - list{(9, "morning"), (3, "morning?!"), (22, "night")} - ->Belt.List.setAssoc(15, "afternoon", (a, b) => mod(a, 12) == mod(b, 12)) - /* list{(9, "morning"), (15, "afternoon"), (22, "night")} */ - ``` +list{(1, "a"), (3, "c")}->Belt.List.setAssoc(2, "b", (a, b) => a == b) /* list{(2, "b"), (1, "a"), (3, "c")} */ - **Please note** +list{(9, "morning"), (3, "morning?!"), (22, "night")} +->Belt.List.setAssoc(15, "afternoon", (a, b) => mod(a, 12) == mod(b, 12)) +/* list{(9, "morning"), (15, "afternoon"), (22, "night")} */ +``` - In the last example, since: `15 mod 12` equals `3 mod 12` +**Please note** - Both the key _and_ the value are replaced in the list. +In the last example, since: `15 mod 12` equals `3 mod 12` + +Both the key _and_ the value are replaced in the list. */ let setAssoc: (t<('a, 'c)>, 'a, 'c, ('a, 'a) => bool) => t<('a, 'c)> @@ -834,10 +944,12 @@ let setAssoc: (t<('a, 'c)>, 'a, 'c, ('a, 'a) => bool) => t<('a, 'c)> let sortU: (t<'a>, (. 'a, 'a) => int) => t<'a> /** - Returns a sorted list. +Returns a sorted list. + +## Examples - ```res example - Belt.List.sort(list{5, 4, 9, 3, 7}, (a, b) => a - b) // list{3, 4, 5, 7, 9} - ``` +```rescript +Belt.List.sort(list{5, 4, 9, 3, 7}, (a, b) => a - b) // list{3, 4, 5, 7, 9} +``` */ let sort: (t<'a>, ('a, 'a) => int) => t<'a> diff --git a/jscomp/others/belt_Map.resi b/jscomp/others/belt_Map.resi index 837950e855..ae5638d82f 100644 --- a/jscomp/others/belt_Map.resi +++ b/jscomp/others/belt_Map.resi @@ -12,15 +12,20 @@ /* Adapted by authors of ReScript without using functors */ /* ********************************************************************* */ -/*** The top level provides generic immutable map operations. +/*** +The top level provides generic immutable map operations. - It also has three specialized inner modules `Belt.Map.Int`, - `Belt.Map.String` and `Belt.Map.Dict`. */ +It also has three specialized inner modules `Belt.Map.Int`, `Belt.Map.String` +and `Belt.Map.Dict`. +*/ + +/** +## Examples -/* ```res prelude - type t<'key, 'value, 'identity> - type id<'key, 'id> = Belt_Id.comparable<'key, 'id> - ``` +```rescript +type t<'key, 'value, 'identity> +type id<'key, 'id> = Belt_Id.comparable<'key, 'id> +``` */ module Int = Belt_MapInt @@ -29,226 +34,263 @@ module String = Belt_MapString module Dict = Belt_MapDict -/** `'key` is the field type +/** +`'key` is the field type - `'value` is the element type +`'value` is the element type - `'identity` the identity of the collection +`'identity` the identity of the collection */ type t<'key, 'value, 'identity> /** The identity needed for making an empty map. */ type id<'key, 'id> = Belt_Id.comparable<'key, 'id> -/** `make(~id)` creates a new map by taking in the comparator. +/** +`make(~id)` creates a new map by taking in the comparator. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - let m = Belt.Map.make(~id=module(IntCmp)) +let m = Belt.Map.make(~id=module(IntCmp)) - Belt.Map.set(m, 0, "a") - ``` +Belt.Map.set(m, 0, "a") +``` */ let make: (~id: id<'k, 'id>) => t<'k, 'v, 'id> -/** `isEmpty(m)` checks whether a map m is empty. +/** + +`isEmpty(m)` checks whether a map m is empty. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - Belt.Map.isEmpty(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp))) == false - ``` +Belt.Map.isEmpty(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp))) == false +``` */ let isEmpty: t<_> => bool -/** `has(m, k)` checks whether `m` has the key `k`. +/** +`has(m, k)` checks whether `m` has the key `k`. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +## Examples - Belt.Map.has(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp)), 1) == true - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) + +Belt.Map.has(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp)), 1) == true +``` */ let has: (t<'k, 'v, 'id>, 'k) => bool let cmpU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, (. 'v, 'v) => int) => int -/** `cmp(m0, m1, vcmp);` +/** +`cmp(m0, m1, vcmp);` - Total ordering of map given total ordering of value function. +Total ordering of map given total ordering of value function. - It will compare size first and each element following the order one by one. +It will compare size first and each element following the order one by one. */ let cmp: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ('v, 'v) => int) => int let eqU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, (. 'v, 'v) => bool) => bool -/** `eq(m1, m2, veq)` tests whether the maps `m1` and `m2` are equal, that is, - contain equal keys and associate them with equal data. `veq` is the - equality predicate used to compare the data associated with the keys. */ +/** +eq(m1, m2, veq)` tests whether the maps `m1` and `m2` are equal, that is, +contain equal keys and associate them with equal data. `veq` is the +equality predicate used to compare the data associated with the keys. +*/ let eq: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ('v, 'v) => bool) => bool let findFirstByU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => option<('k, 'v)> -/** `findFirstBy(m, p)` uses function `f` to find the first key value pair to - match predicate `p`. +/** ` +findFirstBy(m, p)` uses function `f` to find the first key value pair to match predicate `p`. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +## Examples - let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "")]) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - Belt.Map.findFirstBy(s0, (k, v) => k == 4) /* (4, "4") */ - ``` +let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "")]) + +Belt.Map.findFirstBy(s0, (k, v) => k == 4) /* (4, "4") */ +``` */ let findFirstBy: (t<'k, 'v, 'id>, ('k, 'v) => bool) => option<('k, 'v)> let forEachU: (t<'k, 'v, 'id>, (. 'k, 'v) => unit) => unit -/** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the - `'k` as first argument, and the associated value as second argument. The - bindings are passed to `f` in increasing order with respect to the ordering - over the type of the keys. +/** + `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the +`'k` as first argument, and the associated value as second argument. The +bindings are passed to `f` in increasing order with respect to the ordering +over the type of the keys. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "")]) +let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "")]) - let acc = ref(list{}) +let acc = ref(list{}) - Belt.Map.forEach(s0, (k, v) => acc := list{(k, v), ...acc.contents}) +Belt.Map.forEach(s0, (k, v) => acc := list{(k, v), ...acc.contents}) - acc.contents == list{(4, "4"), (3, "3"), (2, "2"), (1, "1")} - ``` +acc.contents == list{(4, "4"), (3, "3"), (2, "2"), (1, "1")} +``` */ let forEach: (t<'k, 'v, 'id>, ('k, 'v) => unit) => unit let reduceU: (t<'k, 'v, 'id>, 'acc, (. 'acc, 'k, 'v) => 'acc) => 'acc -/** `reduce(m, a, f)` computes `(f(kN, dN) ... (f(k1, d1, a))...)`, where `k1 - ... kN` are the keys of all bindings in m (in increasing order), and `d1 - ... dN` are the associated data. - - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) - - let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "3")]) - - Belt.Map.reduce(s0, list{}, (acc, k, v) => list{ - (k, v), - ...acc, - }) /* [(4, "4"), (3, "3"), (2, "2"), (1, "1"), 0] */ - ``` +/** + `reduce(m, a, f)` computes `(f(kN, dN) ... (f(k1, d1, a))...)`, where `k1 +... kN` are the keys of all bindings in m (in increasing order), and `d1 +... dN` are the associated data. + +## Examples + +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) + +let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "3")]) + +Belt.Map.reduce(s0, list{}, (acc, k, v) => list{ + (k, v), + ...acc, +}) /* [(4, "4"), (3, "3"), (2, "2"), (1, "1"), 0] */ +``` */ let reduce: (t<'k, 'v, 'id>, 'acc, ('acc, 'k, 'v) => 'acc) => 'acc let everyU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => bool -/** `every(m, p)` checks if all the bindings of the map satisfy the predicate - `p`. Order unspecified */ +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate +`p`. Order unspecified +*/ let every: (t<'k, 'v, 'id>, ('k, 'v) => bool) => bool let someU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => bool -/** `some(m, p)` checks if at least one binding of the map satisfy the - predicate `p`. Order unspecified */ +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate +`p`. Order unspecified */ let some: (t<'k, 'v, 'id>, ('k, 'v) => bool) => bool -/** `size(s)` +/** + `size(s)` - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +## Examples - Belt.Map.size(Belt.Map.fromArray([(2, "2"), (2, "1"), (3, "3")], ~id=module(IntCmp))) == 2 - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) + +Belt.Map.size(Belt.Map.fromArray([(2, "2"), (2, "1"), (3, "3")], ~id=module(IntCmp))) == 2 +``` */ let size: t<'k, 'v, 'id> => int -/** `toArray(s)` +/** + `toArray(s)` + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - Belt.Map.toArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [ - (1, "1"), - (2, "2"), - (3, "3"), - ] - ``` +Belt.Map.toArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [ + (1, "1"), + (2, "2"), + (3, "3"), + ] +``` */ let toArray: t<'k, 'v, 'id> => array<('k, 'v)> -/** In increasing order. - - See `Belt.Map.toArray` -*/ +/** In increasing order. See `Belt.Map.toArray`*/ let toList: t<'k, 'v, 'id> => list<('k, 'v)> -/** `fromArray(kvs, ~id);` +/** +`fromArray(kvs, ~id);` + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - Belt.Map.toArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [ - (1, "1"), - (2, "2"), - (3, "3"), - ] - ``` +Belt.Map.toArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [ + (1, "1"), + (2, "2"), + (3, "3"), + ] +``` */ let fromArray: (array<('k, 'v)>, ~id: id<'k, 'id>) => t<'k, 'v, 'id> -/** `keysToArray(s);` +/** +`keysToArray(s);` + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - Belt.Map.keysToArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [ - 1, - 2, - 3, - ] - ``` +Belt.Map.keysToArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [ + 1, + 2, + 3, + ] +``` */ let keysToArray: t<'k, 'v, 'id> => array<'k> -/** `valuesToArray(s);` +/** + `valuesToArray(s);` - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +## Examples - Belt.Map.valuesToArray( - Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), - ) == ["1", "2", "3"] - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) + +Belt.Map.valuesToArray( + Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), +) == ["1", "2", "3"] +``` */ let valuesToArray: t<'k, 'v, 'id> => array<'v> @@ -276,105 +318,117 @@ let maximum: t<'k, 'v, _> => option<('k, 'v)> /** See `Belt.Map.maximum` */ let maxUndefined: t<'k, 'v, _> => Js.undefined<('k, 'v)> -/** `get(s, k)` +/** + `get(s, k)` + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - Belt.Map.get(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), 2) == - Some("2") +Belt.Map.get(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), 2) == + Some("2") - Belt.Map.get(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), 2) == None - ``` +Belt.Map.get(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), 2) == None +``` */ let get: (t<'k, 'v, 'id>, 'k) => option<'v> -/** See `Belt.Map.get` - - Returns `undefined` when not found -*/ +/** See `Belt.Map.get`. Returns `undefined` when not found*/ let getUndefined: (t<'k, 'v, 'id>, 'k) => Js.undefined<'v> -/** `getWithDefault(s, k, default)` +/** +`getWithDefault(s, k, default)` - See `Belt.Map.get` +See `Belt.Map.get` - Returns default when `k` is not found. +Returns default when `k` is not found. */ let getWithDefault: (t<'k, 'v, 'id>, 'k, 'v) => 'v -/** `getExn(s, k)` +/** +`getExn(s, k)` - See `Belt.Map.getExn` +See `Belt.Map.getExn` - raise when `k` not exist +raise when `k` not exist */ let getExn: (t<'k, 'v, 'id>, 'k) => 'v /* ************************************************************************** */ -/** `remove(m, x)` when `x` is not in `m`, `m` is returned reference unchanged. +/** +`remove(m, x)` when `x` is not in `m`, `m` is returned reference unchanged. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)) +let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)) - let s1 = Belt.Map.remove(s0, 1) +let s1 = Belt.Map.remove(s0, 1) - let s2 = Belt.Map.remove(s1, 1) +let s2 = Belt.Map.remove(s1, 1) - s1 === s2 +s1 === s2 - Belt.Map.keysToArray(s1) == [2, 3] - ``` +Belt.Map.keysToArray(s1) == [2, 3] +``` */ let remove: (t<'k, 'v, 'id>, 'k) => t<'k, 'v, 'id> -/** `removeMany(s, xs)` +/** +`removeMany(s, xs)` - Removing each of `xs` to `s`, note unlike `Belt.Map.remove`, the reference - of return value might be changed even if none in `xs` exists `s`. +Removing each of `xs` to `s`, note unlike `Belt.Map.remove`, the reference +of return value might be changed even if none in `xs` exists `s`. */ let removeMany: (t<'k, 'v, 'id>, array<'k>) => t<'k, 'v, 'id> -/** `set(m, x, y)` returns a map containing the same bindings as `m`, with a - new binding of `x` to `y`. If `x` was already bound in `m`, its previous - binding disappears. +/** +`set(m, x, y)` returns a map containing the same bindings as `m`, with a +new binding of `x` to `y`. If `x` was already bound in `m`, its previous +binding disappears. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = (a, b) => Pervasives.compare(a, b) - }) +## Examples - let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) +}) - let s1 = Belt.Map.set(s0, 2, "3") +let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)) - Belt.Map.valuesToArray(s1) == ["1", "3", "3"] - ``` +let s1 = Belt.Map.set(s0, 2, "3") + +Belt.Map.valuesToArray(s1) == ["1", "3", "3"] +``` */ let set: (t<'k, 'v, 'id>, 'k, 'v) => t<'k, 'v, 'id> let updateU: (t<'k, 'v, 'id>, 'k, (. option<'v>) => option<'v>) => t<'k, 'v, 'id> -/** `update(m, x, f)` returns a map containing the same bindings as `m`, except - for the binding of `x`. Depending on the value of `y` where `y` is - `f(get(m, x))`, the binding of `x` is added, removed or updated. If `y` is - `None`, the binding is removed if it exists; otherwise, if `y` is `Some(z)` - then `x` is associated to `z` in the resulting map. */ +/** +`update(m, x, f)` returns a map containing the same bindings as `m`, except +for the binding of `x`. Depending on the value of `y` where `y` is +`f(get(m, x))`, the binding of `x` is added, removed or updated. If `y` is +`None`, the binding is removed if it exists; otherwise, if `y` is `Some(z)` +then `x` is associated to `z` in the resulting map. +*/ let update: (t<'k, 'v, 'id>, 'k, option<'v> => option<'v>) => t<'k, 'v, 'id> -/** `mergeMany(s, xs)` +/** + `mergeMany(s, xs)` - Adding each of `xs` to `s`, note unlike `add`, the reference of return - value might be changed even if all values in `xs` exist `s`. +Adding each of `xs` to `s`, note unlike `add`, the reference of return +value might be changed even if all values in `xs` exist `s`. */ let mergeMany: (t<'k, 'v, 'id>, array<('k, 'v)>) => t<'k, 'v, 'id> @@ -383,9 +437,11 @@ let mergeU: ( t<'k, 'v2, 'id>, (. 'k, option<'v>, option<'v2>) => option<'v3>, ) => t<'k, 'v3, 'id> -/** `merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` - and of `m2`. The presence of each such binding, and the corresponding - value, is determined with the function `f`. */ +/** +`merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` +and of `m2`. The presence of each such binding, and the corresponding +value, is determined with the function `f`. +*/ let merge: ( t<'k, 'v, 'id>, t<'k, 'v2, 'id>, @@ -393,62 +449,72 @@ let merge: ( ) => t<'k, 'v3, 'id> let keepU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => t<'k, 'v, 'id> -/** `keep(m, p)` returns the map with all the bindings in m that satisfy - predicate `p`. */ +/** +`keep(m, p)` returns the map with all the bindings in m that satisfy +predicate `p`. +*/ let keep: (t<'k, 'v, 'id>, ('k, 'v) => bool) => t<'k, 'v, 'id> let partitionU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => (t<'k, 'v, 'id>, t<'k, 'v, 'id>) -/** `partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains - all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map - with all the bindings of `s` that do not satisfy `p`. */ +/** +`partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains +all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map +with all the bindings of `s` that do not satisfy `p`. +*/ let partition: (t<'k, 'v, 'id>, ('k, 'v) => bool) => (t<'k, 'v, 'id>, t<'k, 'v, 'id>) -/** `split(x, m)` returns a tuple `(l, r)`, data, where `l` is the map with all - the bindings of `m` whose 'k is strictly less than `x`; `r` is the map with - all the bindings of m whose 'k is strictly greater than `x`; `data` is - `None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v` to - `x`. */ +/** +`split(x, m)` returns a tuple `(l, r)`, data, where `l` is the map with all +the bindings of `m` whose 'k is strictly less than `x`; `r` is the map with +all the bindings of m whose 'k is strictly greater than `x`; `data` is +`None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v` to +`x`. +*/ let split: (t<'k, 'v, 'id>, 'k) => ((t<'k, 'v, 'id>, t<'k, 'v, 'id>), option<'v>) let mapU: (t<'k, 'v, 'id>, (. 'v) => 'v2) => t<'k, 'v2, 'id> -/** `map(m, f) returns a map with same domain as`m`, where the associated - value`a`of all bindings of`m`has been replaced by the result of the - application of`f`to`a`. The bindings are passed to`f` in increasing order - with respect to the ordering over the type of the keys. */ +/** +`map(m, f) returns a map with same domain as`m`, where the associated +value`a`of all bindings of`m`has been replaced by the result of the +application of`f`to`a`. The bindings are passed to`f` in increasing order +with respect to the ordering over the type of the keys. +*/ let map: (t<'k, 'v, 'id>, 'v => 'v2) => t<'k, 'v2, 'id> let mapWithKeyU: (t<'k, 'v, 'id>, (. 'k, 'v) => 'v2) => t<'k, 'v2, 'id> -/** `mapWithKey(m, f)` +/** +`mapWithKey(m, f)` - The same as `Belt.Map.map` except that `f` is supplied with one more - argument: the key. +The same as `Belt.Map.map` except that `f` is supplied with one more +argument: the key. */ let mapWithKey: (t<'k, 'v, 'id>, ('k, 'v) => 'v2) => t<'k, 'v2, 'id> -/** `getData(s0)` +/** +`getData(s0)` - Advanced usage only +Advanced usage only - Returns the raw data (detached from comparator), but its type is still - manifested, so that user can pass identity directly without boxing. +Returns the raw data (detached from comparator), but its type is still +manifested, so that user can pass identity directly without boxing. */ let getData: t<'k, 'v, 'id> => Belt_MapDict.t<'k, 'v, 'id> -/** Advanced usage only - - Returns the identity of s0. +/** +Advanced usage only. Returns the identity of s0. */ let getId: t<'k, 'v, 'id> => id<'k, 'id> -/** `packIdData(~id, ~data)` +/** +`packIdData(~id, ~data)` - Advanced usage only +Advanced usage only - Returns the packed collection. +Returns the packed collection. */ let packIdData: (~id: id<'k, 'id>, ~data: Belt_MapDict.t<'k, 'v, 'id>) => t<'k, 'v, 'id> /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit diff --git a/jscomp/others/belt_MapDict.resi b/jscomp/others/belt_MapDict.resi index 62bab99f76..7dafef606f 100644 --- a/jscomp/others/belt_MapDict.resi +++ b/jscomp/others/belt_MapDict.resi @@ -22,17 +22,21 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** This module separates identity from data, it is a bit more verbose but - slightly more efficient due to the fact that there is no need to pack - identity and data back after each operation. +/*** +This module separates identity from data, it is a bit more verbose but +slightly more efficient due to the fact that there is no need to pack +identity and data back after each operation. - **_Advanced usage only_** +**_Advanced usage only_** */ -/* ```res prelude - type t<'key, 'value, 'id> - type cmp<'key, 'id> = Belt_Id.cmp<'key, 'id> - ``` +/* +## Examples + +```rescript +type t<'key, 'value, 'id> +type cmp<'key, 'id> = Belt_Id.cmp<'key, 'id> +``` */ type t<'key, 'value, 'id> @@ -49,49 +53,62 @@ let cmpU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ~kcmp: cmp<'k, 'id>, ~vcmp: (. 'v, 'v let cmp: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ~kcmp: cmp<'k, 'id>, ~vcmp: ('v, 'v) => int) => int let eqU: (t<'k, 'a, 'id>, t<'k, 'a, 'id>, ~kcmp: cmp<'k, 'id>, ~veq: (. 'a, 'a) => bool) => bool -/** `eq(m1, m2, cmp)` tests whether the maps `m1` and `m2` are equal, that is, - contain equal keys and associate them with equal data. `cmp` is the - equality predicate used to compare the data associated with the keys. */ +/** +`eq(m1, m2, cmp)` tests whether the maps `m1` and `m2` are equal, that is, +contain equal keys and associate them with equal data. `cmp` is the +equality predicate used to compare the data associated with the keys. +*/ let eq: (t<'k, 'a, 'id>, t<'k, 'a, 'id>, ~kcmp: cmp<'k, 'id>, ~veq: ('a, 'a) => bool) => bool let findFirstByU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => option<('k, 'v)> -/** `findFirstBy(m, p)` uses function `f` to find the first key value pair to - match predicate `p`. +/** +`findFirstBy(m, p)` uses function `f` to find the first key value pair to +match predicate `p`. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Map.Dict.fromArray([(4, "4"), (1, "1"), (2, "2"), (3, "3")], ~cmp=IntCmp.cmp) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - Belt.Map.Dict.findFirstBy(s0, (k, _) => k == 4) == Some((4, "4")) - ``` +let s0 = Belt.Map.Dict.fromArray([(4, "4"), (1, "1"), (2, "2"), (3, "3")], ~cmp=IntCmp.cmp) + +Belt.Map.Dict.findFirstBy(s0, (k, _) => k == 4) == Some((4, "4")) +``` */ let findFirstBy: (t<'k, 'v, 'id>, ('k, 'v) => bool) => option<('k, 'v)> let forEachU: (t<'k, 'a, 'id>, (. 'k, 'a) => unit) => unit -/** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the - key as first argument, and the associated value as second argument. The - bindings are passed to `f` in increasing order with respect to the ordering - over the type of the keys. */ +/** +`forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the +key as first argument, and the associated value as second argument. The +bindings are passed to `f` in increasing order with respect to the ordering +over the type of the keys. +*/ let forEach: (t<'k, 'a, 'id>, ('k, 'a) => unit) => unit let reduceU: (t<'k, 'a, 'id>, 'b, (. 'b, 'k, 'a) => 'b) => 'b -/** `reduce(m, a, f)` computes `f(kN, dN ... f(k1, d1, a)...)`, where `k1 ... - kN` are the keys of all bindings in `m` (in increasing order), and `d1 ... - dN` are the associated data. */ +/** +`reduce(m, a, f)` computes `f(kN, dN ... f(k1, d1, a)...)`, where `k1 ... kN` +are the keys of all bindings in `m` (in increasing order), and `d1 ... dN` +are the associated data. +*/ let reduce: (t<'k, 'a, 'id>, 'b, ('b, 'k, 'a) => 'b) => 'b let everyU: (t<'k, 'a, 'id>, (. 'k, 'a) => bool) => bool -/** `every(m, p)` checks if all the bindings of the map satisfy the predicate - `p`. Order unspecified */ +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate +`p`. Order unspecified +*/ let every: (t<'k, 'a, 'id>, ('k, 'a) => bool) => bool let someU: (t<'k, 'a, 'id>, (. 'k, 'a) => bool) => bool -/** `some(m, p)` checks if at least one binding of the map satisfy the - predicate `p`. Order unspecified */ +/** +`some(m, p)` checks if at least one binding of the map satisfy the +predicate `p`. Order unspecified +*/ let some: (t<'k, 'a, 'id>, ('k, 'a) => bool) => bool let size: t<'k, 'a, 'id> => int @@ -133,15 +150,19 @@ let getExn: (t<'k, 'a, 'id>, 'k, ~cmp: cmp<'k, 'id>) => 'a let checkInvariantInternal: t<_> => unit -/** `remove(m, x)` returns a map containing the same bindings as `m`, except - for `x` which is unbound in the returned map. */ +/** +`remove(m, x)` returns a map containing the same bindings as `m`, except +for `x` which is unbound in the returned map. +*/ let remove: (t<'a, 'b, 'id>, 'a, ~cmp: cmp<'a, 'id>) => t<'a, 'b, 'id> let removeMany: (t<'a, 'b, 'id>, array<'a>, ~cmp: cmp<'a, 'id>) => t<'a, 'b, 'id> -/** `set(m, x, y)` returns a map containing the same bindings as `m`, plus a - binding of `x` to `y`. If `x` was already bound in `m`, its previous - binding disappears. */ +/** +`set(m, x, y)` returns a map containing the same bindings as `m`, plus a +binding of `x` to `y`. If `x` was already bound in `m`, its previous +binding disappears. +*/ let set: (t<'a, 'b, 'id>, 'a, 'b, ~cmp: cmp<'a, 'id>) => t<'a, 'b, 'id> let updateU: ( @@ -158,9 +179,11 @@ let mergeU: ( (. 'a, option<'b>, option<'c>) => option<'d>, ~cmp: cmp<'a, 'id>, ) => t<'a, 'd, 'id> -/** `merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` - and of `m2`. The presence of each such binding, and the corresponding - value, is determined with the function `f`. */ +/** +`merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` +and of `m2`. The presence of each such binding, and the corresponding +value, is determined with the function `f`. +*/ let merge: ( t<'a, 'b, 'id>, t<'a, 'c, 'id>, @@ -171,21 +194,27 @@ let merge: ( let mergeMany: (t<'a, 'b, 'id>, array<('a, 'b)>, ~cmp: cmp<'a, 'id>) => t<'a, 'b, 'id> let keepU: (t<'k, 'a, 'id>, (. 'k, 'a) => bool) => t<'k, 'a, 'id> -/** `keep(m, p)` returns the map with all the bindings in `m` that satisfy - predicate `p`. */ +/** +`keep(m, p)` returns the map with all the bindings in `m` that satisfy +predicate `p`. +*/ let keep: (t<'k, 'a, 'id>, ('k, 'a) => bool) => t<'k, 'a, 'id> let partitionU: (t<'k, 'a, 'id>, (. 'k, 'a) => bool) => (t<'k, 'a, 'id>, t<'k, 'a, 'id>) -/** `partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains - all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map - with all the bindings of `s` that do not satisfy `p`. */ +/** +`partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains +all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map +with all the bindings of `s` that do not satisfy `p`. +*/ let partition: (t<'k, 'a, 'id>, ('k, 'a) => bool) => (t<'k, 'a, 'id>, t<'k, 'a, 'id>) -/** `split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with - all the bindings of `m` whose key is strictly less than `x`; `r` is the map - with all the bindings of `m` whose key is strictly greater than `x`; `data` - is `None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v` - to `x`. */ +/** +`split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with +all the bindings of `m` whose key is strictly less than `x`; `r` is the map +with all the bindings of `m` whose key is strictly greater than `x`; `data` +is `None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v` +to `x`. +*/ let split: ( t<'a, 'b, 'id>, 'a, @@ -193,10 +222,12 @@ let split: ( ) => ((t<'a, 'b, 'id>, t<'a, 'b, 'id>), option<'b>) let mapU: (t<'k, 'a, 'id>, (. 'a) => 'b) => t<'k, 'b, 'id> -/** `map(m, f)` returns a map with same domain as `m`, where the associated - value `a` of all bindings of `m` has been replaced by the result of the - application of `f` to `a`. The bindings are passed to `f` in increasing - order with respect to the ordering over the type of the keys. */ +/** +`map(m, f)` returns a map with same domain as `m`, where the associated +value `a` of all bindings of `m` has been replaced by the result of the +application of `f` to `a`. The bindings are passed to `f` in increasing +order with respect to the ordering over the type of the keys. +*/ let map: (t<'k, 'a, 'id>, 'a => 'b) => t<'k, 'b, 'id> let mapWithKeyU: (t<'k, 'a, 'id>, (. 'k, 'a) => 'b) => t<'k, 'b, 'id> diff --git a/jscomp/others/belt_MapInt.resi b/jscomp/others/belt_MapInt.resi index 9c5da4f930..a4c1f608d6 100644 --- a/jscomp/others/belt_MapInt.resi +++ b/jscomp/others/belt_MapInt.resi @@ -15,54 +15,56 @@ let cmp: (t<'v>, t<'v>, ('v, 'v) => int) => int let eqU: (t<'v>, t<'v>, (. 'v, 'v) => bool) => bool /** - `eq m1 m2` tests whether the maps `m1` and `m2` are - equal, that is, contain equal keys and associate them with - equal data. +`eq(m1, m2)` tests whether the maps `m1` and `m2` are +equal, that is, contain equal keys and associate them with +equal data. */ let eq: (t<'v>, t<'v>, ('v, 'v) => bool) => bool let findFirstByU: (t<'v>, (. key, 'v) => bool) => option<(key, 'v)> /** - `findFirstBy m p` uses funcion `f` to find the first key value pair - to match predicate `p`. +`findFirstBy(m, p)` uses funcion `f` to find the first key value pair +to match predicate `p`. - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");; - ``` +```rescript +let s0 = fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2,"(3, ""))]) +findFirstBy(s0, (k, v) => k == 4) == option((4, "4")) +``` */ let findFirstBy: (t<'v>, (key, 'v) => bool) => option<(key, 'v)> let forEachU: (t<'v>, (. key, 'v) => unit) => unit /** - `forEach m f` applies `f` to all bindings in map `m`. - `f` receives the key as first argument, and the associated value - as second argument. The bindings are passed to `f` in increasing - order with respect to the ordering over the type of the keys. +`forEach(m, f)` applies `f` to all bindings in map `m`. +`f` receives the key as first argument, and the associated value +as second argument. The bindings are passed to `f` in increasing +order with respect to the ordering over the type of the keys. */ let forEach: (t<'v>, (key, 'v) => unit) => unit let reduceU: (t<'v>, 'v2, (. 'v2, key, 'v) => 'v2) => 'v2 /** - `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`, - where `k1 ... kN` are the keys of all bindings in `m` - (in increasing order), and `d1 ... dN` are the associated data. +`reduce(m, a, f)` computes `(f kN dN ... (f k1 d1 a)...)`, +where `k1 ... kN` are the keys of all bindings in `m` +(in increasing order), and `d1 ... dN` are the associated data. */ let reduce: (t<'v>, 'v2, ('v2, key, 'v) => 'v2) => 'v2 let everyU: (t<'v>, (. key, 'v) => bool) => bool -/** `every m p` checks if all the bindings of the map - satisfy the predicate `p`. Order unspecified */ +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +Order unspecified */ let every: (t<'v>, (key, 'v) => bool) => bool let someU: (t<'v>, (. key, 'v) => bool) => bool -/** `some m p` checks if at least one binding of the map - satisfy the predicate `p`. Order unspecified */ +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate +`p`. Order unspecified */ let some: (t<'v>, (key, 'v) => bool) => bool let size: t<'v> => int @@ -103,7 +105,7 @@ let getWithDefault: (t<'v>, key, 'v) => 'v let getExn: (t<'v>, key) => 'v /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit @@ -114,9 +116,9 @@ let remove: (t<'v>, key) => t<'v> let removeMany: (t<'v>, array) => t<'v> /** - `set m x y` returns a map containing the same bindings as - `m`, plus a binding of `x` to `y`. If `x` was already bound - in `m`, its previous binding disappears. +`set(m, x, y)` returns a map containing the same bindings as +`m`, plus a binding of `x` to `y`. If `x` was already bound +in `m`, its previous binding disappears. */ let set: (t<'v>, key, 'v) => t<'v> @@ -126,9 +128,9 @@ let update: (t<'v>, key, option<'v> => option<'v>) => t<'v> let mergeU: (t<'v>, t<'v2>, (. key, option<'v>, option<'v2>) => option<'c>) => t<'c> /** - `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1` - and of `m2`. The presence of each such binding, and the corresponding - value, is determined with the function `f`. +`merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` +and of `m2`. The presence of each such binding, and the corresponding +value, is determined with the function `f`. */ let merge: (t<'v>, t<'v2>, (key, option<'v>, option<'v2>) => option<'c>) => t<'c> @@ -136,39 +138,36 @@ let mergeMany: (t<'v>, array<(key, 'v)>) => t<'v> let keepU: (t<'v>, (. key, 'v) => bool) => t<'v> -/** `keep m p` returns the map with all the bindings in `m` - that satisfy predicate `p`. */ +/** +`keep(m, p)` returns the map with all the bindings in `m` that satisfy predicate +`p`. +*/ let keep: (t<'v>, (key, 'v) => bool) => t<'v> let partitionU: (t<'v>, (. key, 'v) => bool) => (t<'v>, t<'v>) /** - `partition m p` returns a pair of maps `(m1, m2)`, where - `m1` contains all the bindings of `s` that satisfy the - predicate `p`, and `m2` is the map with all the bindings of - `s` that do not satisfy `p`. +`partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains all the +bindings of `s` that satisfy the predicate `p`, and `m2` is the map with all the +bindings of `s` that do not satisfy `p`. */ let partition: (t<'v>, (key, 'v) => bool) => (t<'v>, t<'v>) /** - `split x m` returns a triple `(l, data, r)`, where - `l` is the map with all the bindings of `m` whose key - is strictly less than `x`; - `r` is the map with all the bindings of `m` whose key - is strictly greater than `x`; - `data` is `None` if `m` contains no binding for `x`, - or `Some v` if `m` binds `v` to `x`. +`split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with all the +bindings of `m` whose key is strictly less than `x`; `r` is the map with all the +bindings of `m` whose key is strictly greater than `x`; `data` is `None` if `m` +contains no binding for `x`, or `Some(v)` if `m` binds `v` to `x`. */ let split: (key, t<'v>) => (t<'v>, option<'v>, t<'v>) let mapU: (t<'v>, (. 'v) => 'v2) => t<'v2> /** - `map m f` returns a map with same domain as `m`, where the - associated value `a` of all bindings of `m` has been - replaced by the result of the application of `f` to `a`. - The bindings are passed to `f` in increasing order - with respect to the ordering over the type of the keys. +`map(m, f)` returns a map with same domain as `m`, where the associated value `a` +of all bindings of `m` has been replaced by the result of the application of `f` +to `a`. The bindings are passed to `f` in increasing order with respect to the +ordering over the type of the keys. */ let map: (t<'v>, 'v => 'v2) => t<'v2> diff --git a/jscomp/others/belt_MapString.resi b/jscomp/others/belt_MapString.resi index b31f1318ec..5cd87922bc 100644 --- a/jscomp/others/belt_MapString.resi +++ b/jscomp/others/belt_MapString.resi @@ -15,54 +15,56 @@ let cmp: (t<'v>, t<'v>, ('v, 'v) => int) => int let eqU: (t<'v>, t<'v>, (. 'v, 'v) => bool) => bool /** - `eq m1 m2` tests whether the maps `m1` and `m2` are - equal, that is, contain equal keys and associate them with - equal data. +`eq(m1, m2)` tests whether the maps `m1` and `m2` are +equal, that is, contain equal keys and associate them with +equal data. */ let eq: (t<'v>, t<'v>, ('v, 'v) => bool) => bool let findFirstByU: (t<'v>, (. key, 'v) => bool) => option<(key, 'v)> /** - `findFirstBy m p` uses funcion `f` to find the first key value pair - to match predicate `p`. +`findFirstBy(m, p)` uses funcion `f` to find the first key value pair +to match predicate `p`. - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");; - ``` +```rescript +let s0 = fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2,"(3, ""))]) +findFirstBy(s0, (k, v) => k == 4) == option((4, "4")) +``` */ let findFirstBy: (t<'v>, (key, 'v) => bool) => option<(key, 'v)> let forEachU: (t<'v>, (. key, 'v) => unit) => unit /** - `forEach m f` applies `f` to all bindings in map `m`. - `f` receives the key as first argument, and the associated value - as second argument. The bindings are passed to `f` in increasing - order with respect to the ordering over the type of the keys. +`forEach(m, f)` applies `f` to all bindings in map `m`. +`f` receives the key as first argument, and the associated value +as second argument. The bindings are passed to `f` in increasing +order with respect to the ordering over the type of the keys. */ let forEach: (t<'v>, (key, 'v) => unit) => unit let reduceU: (t<'v>, 'v2, (. 'v2, key, 'v) => 'v2) => 'v2 /** - `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`, - where `k1 ... kN` are the keys of all bindings in `m` - (in increasing order), and `d1 ... dN` are the associated data. +`reduce(m, a, f)` computes `(f kN dN ... (f k1 d1 a)...)`, +where `k1 ... kN` are the keys of all bindings in `m` +(in increasing order), and `d1 ... dN` are the associated data. */ let reduce: (t<'v>, 'v2, ('v2, key, 'v) => 'v2) => 'v2 let everyU: (t<'v>, (. key, 'v) => bool) => bool -/** `every m p` checks if all the bindings of the map - satisfy the predicate `p`. Order unspecified */ +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +Order unspecified */ let every: (t<'v>, (key, 'v) => bool) => bool let someU: (t<'v>, (. key, 'v) => bool) => bool -/** `some m p` checks if at least one binding of the map - satisfy the predicate `p`. Order unspecified */ +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate +`p`. Order unspecified */ let some: (t<'v>, (key, 'v) => bool) => bool let size: t<'v> => int @@ -103,7 +105,7 @@ let getWithDefault: (t<'v>, key, 'v) => 'v let getExn: (t<'v>, key) => 'v /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit @@ -114,9 +116,9 @@ let remove: (t<'v>, key) => t<'v> let removeMany: (t<'v>, array) => t<'v> /** - `set m x y` returns a map containing the same bindings as - `m`, plus a binding of `x` to `y`. If `x` was already bound - in `m`, its previous binding disappears. +`set(m, x, y)` returns a map containing the same bindings as +`m`, plus a binding of `x` to `y`. If `x` was already bound +in `m`, its previous binding disappears. */ let set: (t<'v>, key, 'v) => t<'v> @@ -126,9 +128,9 @@ let update: (t<'v>, key, option<'v> => option<'v>) => t<'v> let mergeU: (t<'v>, t<'v2>, (. key, option<'v>, option<'v2>) => option<'c>) => t<'c> /** - `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1` - and of `m2`. The presence of each such binding, and the corresponding - value, is determined with the function `f`. +`merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` +and of `m2`. The presence of each such binding, and the corresponding +value, is determined with the function `f`. */ let merge: (t<'v>, t<'v2>, (key, option<'v>, option<'v2>) => option<'c>) => t<'c> @@ -136,39 +138,36 @@ let mergeMany: (t<'v>, array<(key, 'v)>) => t<'v> let keepU: (t<'v>, (. key, 'v) => bool) => t<'v> -/** `keep m p` returns the map with all the bindings in `m` - that satisfy predicate `p`. */ +/** +`keep(m, p)` returns the map with all the bindings in `m` that satisfy predicate +`p`. +*/ let keep: (t<'v>, (key, 'v) => bool) => t<'v> let partitionU: (t<'v>, (. key, 'v) => bool) => (t<'v>, t<'v>) /** - `partition m p` returns a pair of maps `(m1, m2)`, where - `m1` contains all the bindings of `s` that satisfy the - predicate `p`, and `m2` is the map with all the bindings of - `s` that do not satisfy `p`. +`partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains all the +bindings of `s` that satisfy the predicate `p`, and `m2` is the map with all the +bindings of `s` that do not satisfy `p`. */ let partition: (t<'v>, (key, 'v) => bool) => (t<'v>, t<'v>) /** - `split x m` returns a triple `(l, data, r)`, where - `l` is the map with all the bindings of `m` whose key - is strictly less than `x`; - `r` is the map with all the bindings of `m` whose key - is strictly greater than `x`; - `data` is `None` if `m` contains no binding for `x`, - or `Some v` if `m` binds `v` to `x`. +`split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with all the +bindings of `m` whose key is strictly less than `x`; `r` is the map with all the +bindings of `m` whose key is strictly greater than `x`; `data` is `None` if `m` +contains no binding for `x`, or `Some(v)` if `m` binds `v` to `x`. */ let split: (key, t<'v>) => (t<'v>, option<'v>, t<'v>) let mapU: (t<'v>, (. 'v) => 'v2) => t<'v2> /** - `map m f` returns a map with same domain as `m`, where the - associated value `a` of all bindings of `m` has been - replaced by the result of the application of `f` to `a`. - The bindings are passed to `f` in increasing order - with respect to the ordering over the type of the keys. +`map(m, f)` returns a map with same domain as `m`, where the associated value `a` +of all bindings of `m` has been replaced by the result of the application of `f` +to `a`. The bindings are passed to `f` in increasing order with respect to the +ordering over the type of the keys. */ let map: (t<'v>, 'v => 'v2) => t<'v2> diff --git a/jscomp/others/belt_MutableMap.resi b/jscomp/others/belt_MutableMap.resi index a65ace4206..5451272de0 100644 --- a/jscomp/others/belt_MutableMap.resi +++ b/jscomp/others/belt_MutableMap.resi @@ -26,15 +26,19 @@ module Int = Belt_MutableMapInt module String = Belt_MutableMapString -/*** A mutable sorted map module which allows customize compare behavior. +/*** +A mutable sorted map module which allows customize compare behavior. - Same as `Belt.Map`, but mutable. +Same as `Belt.Map`, but mutable. */ -/* ```res prelude - type t<'k, 'v, 'id> - type id<'key, 'id> = Belt_Id.comparable<'key, 'id> - ``` +/* +## Examples + +```rescript +type t<'k, 'v, 'id> +type id<'key, 'id> = Belt_Id.comparable<'key, 'id> +``` */ type t<'k, 'v, 'id> @@ -46,37 +50,47 @@ let isEmpty: t<_> => bool let has: (t<'k, _, _>, 'k) => bool let cmpU: (t<'k, 'a, 'id>, t<'k, 'a, 'id>, (. 'a, 'a) => int) => int -/** `cmp(m1, m2, cmp)` First compare by size, if size is the same, compare by - key, value pair. */ +/** +`cmp(m1, m2, cmp)` First compare by size, if size is the same, compare by +key, value pair. +*/ let cmp: (t<'k, 'a, 'id>, t<'k, 'a, 'id>, ('a, 'a) => int) => int let eqU: (t<'k, 'a, 'id>, t<'k, 'a, 'id>, (. 'a, 'a) => bool) => bool -/** `eq(m1, m2, eqf)` tests whether the maps `m1` and `m2` are equal, that is, - contain equal keys and associate them with equal data. `eqf` is the - equality predicate used to compare the data associated with the keys. */ +/** +`eq(m1, m2, eqf)` tests whether the maps `m1` and `m2` are equal, that is, +contain equal keys and associate them with equal data. `eqf` is the +equality predicate used to compare the data associated with the keys. +*/ let eq: (t<'k, 'a, 'id>, t<'k, 'a, 'id>, ('a, 'a) => bool) => bool let forEachU: (t<'k, 'a, 'id>, (. 'k, 'a) => unit) => unit -/** `forEach(m, f)` applies f to all bindings in map `m`. `f` receives the `'k` - as first argument, and the associated value as second argument. The - bindings are passed to `f` in increasing order with respect to the ordering - over the type of the keys. */ +/** +`forEach(m, f)` applies f to all bindings in map `m`. `f` receives the `'k` +as first argument, and the associated value as second argument. The +bindings are passed to `f` in increasing order with respect to the ordering +over the type of the keys. +*/ let forEach: (t<'k, 'a, 'id>, ('k, 'a) => unit) => unit let reduceU: (t<'k, 'a, 'id>, 'b, (. 'b, 'k, 'a) => 'b) => 'b -/** `reduce(m, a, f), computes`(f(kN, dN) ... (f(k1, d1, a))...)`, where`k1 ... - kN`are the keys of all bindings in`m`(in increasing order), and`d1 ... dN` - are the associated data. */ +/** +`reduce(m, a, f), computes`(f(kN, dN) ... (f(k1, d1, a))...)`, where`k1 ... +kN`are the keys of all bindings in`m`(in increasing order), and`d1 ... dN` +are the associated data. +*/ let reduce: (t<'k, 'a, 'id>, 'b, ('b, 'k, 'a) => 'b) => 'b let everyU: (t<'k, 'a, 'id>, (. 'k, 'a) => bool) => bool -/** `every(m, p)` checks if all the bindings of the map satisfy the predicate - `p`. */ +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +*/ let every: (t<'k, 'a, 'id>, ('k, 'a) => bool) => bool let someU: (t<'k, 'a, 'id>, (. 'k, 'a) => bool) => bool -/** `some(m, p)` checks if at least one binding of the map satisfy the - predicate `p`. */ +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate `p`. +*/ let some: (t<'k, 'a, 'id>, ('k, 'a) => bool) => bool let size: t<'k, 'a, 'id> => int @@ -122,10 +136,12 @@ let update: (t<'k, 'a, 'id>, 'k, option<'a> => option<'a>) => unit let mergeMany: (t<'k, 'a, 'id>, array<('k, 'a)>) => unit let mapU: (t<'k, 'a, 'id>, (. 'a) => 'b) => t<'k, 'b, 'id> -/** `map(m, f)` returns a map with same domain as `m`, where the associated - value a of all bindings of `m` has been replaced by the result of the - application of `f` to `a`. The bindings are passed to `f` in increasing - order with respect to the ordering over the type of the keys. */ +/** +`map(m, f)` returns a map with same domain as `m`, where the associated +value a of all bindings of `m` has been replaced by the result of the +application of `f` to `a`. The bindings are passed to `f` in increasing +order with respect to the ordering over the type of the keys. +*/ let map: (t<'k, 'a, 'id>, 'a => 'b) => t<'k, 'b, 'id> let mapWithKeyU: (t<'k, 'a, 'id>, (. 'k, 'a) => 'b) => t<'k, 'b, 'id> diff --git a/jscomp/others/belt_MutableMapInt.resi b/jscomp/others/belt_MutableMapInt.resi index be9fea48d5..6f1b66a97a 100644 --- a/jscomp/others/belt_MutableMapInt.resi +++ b/jscomp/others/belt_MutableMapInt.resi @@ -34,45 +34,46 @@ let has: (t<'a>, key) => bool let cmpU: (t<'a>, t<'a>, (. 'a, 'a) => int) => int -/** `cmp m1 m2 cmp` - First compare by size, if size is the same, - compare by key, value pair +/** +`cmp(m1, m2, cmp)`. First compare by size, if size is the same, compare by key, +value pair */ let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => int let eqU: (t<'a>, t<'a>, (. 'a, 'a) => bool) => bool -/** `eq m1 m2 cmp` */ +/** `eq(m1, m2, cmp)` */ let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => bool let forEachU: (t<'a>, (. key, 'a) => unit) => unit -/** `forEach m f` applies `f` to all bindings in map `m`. - `f` receives the key as first argument, and the associated value - as second argument. - The application order of `f` is in increasing order. */ +/** +`forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the key as +first argument, and the associated value as second argument. The application +order of `f` is in increasing order. */ let forEach: (t<'a>, (key, 'a) => unit) => unit let reduceU: (t<'a>, 'b, (. 'b, key, 'a) => 'b) => 'b -/** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`, - where `k1 ... kN` are the keys of all bindings in `m` - (in increasing order), and `d1 ... dN` are the associated data. */ +/** +`reduce(m, a, f)` computes `(f kN dN ... (f k1 d1 a)...)`, where `k1 ... kN` are +the keys of all bindings in `m` (in increasing order), and `d1 ... dN` are the +associated data. */ let reduce: (t<'a>, 'b, ('b, key, 'a) => 'b) => 'b let everyU: (t<'a>, (. key, 'a) => bool) => bool -/** `every m p` checks if all the bindings of the map - satisfy the predicate `p`. - The application order of `p` is unspecified. +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +The application order of `p` is unspecified. */ let every: (t<'a>, (key, 'a) => bool) => bool let someU: (t<'a>, (. key, 'a) => bool) => bool -/** `some m p` checks if at least one binding of the map - satisfy the predicate `p`. - The application order of `p` is unspecified. +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate `p`. +The application order of `p` is unspecified. */ let some: (t<'a>, (key, 'a) => bool) => bool @@ -109,14 +110,15 @@ let checkInvariantInternal: t<_> => unit /* TODO: add functional `merge, partition, keep, split` */ -/** `remove m x` do the in-place modification */ +/** `remove(m, x)` do the in-place modification */ let remove: (t<'a>, key) => unit let removeMany: (t<'a>, array) => unit -/** `set m x y` do the in-place modification, return - `m` for chaining. If `x` was already bound - in `m`, its previous binding disappears. */ +/** +`set(m, x, y)` do the in-place modification, return `m` for chaining. If `x` was +already bound in `m`, its previous binding disappears. +*/ let set: (t<'a>, key, 'a) => unit let updateU: (t<'a>, key, (. option<'a>) => option<'a>) => unit @@ -124,11 +126,11 @@ let update: (t<'a>, key, option<'a> => option<'a>) => unit let mapU: (t<'a>, (. 'a) => 'b) => t<'b> -/** `map m f` returns a map with same domain as `m`, where the - associated value `a` of all bindings of `m` has been - replaced by the result of the application of `f` to `a`. - The bindings are passed to `f` in increasing order - with respect to the ordering over the type of the keys. */ +/** +`map(m, f)` returns a map with same domain as `m`, where the associated value `a` +of all bindings of `m` has been replaced by the result of the application of `f` +to `a`. The bindings are passed to `f` in increasing order with respect to the +ordering over the type of the keys. */ let map: (t<'a>, 'a => 'b) => t<'b> let mapWithKeyU: (t<'a>, (. key, 'a) => 'b) => t<'b> diff --git a/jscomp/others/belt_MutableMapString.resi b/jscomp/others/belt_MutableMapString.resi index d0ec4f6379..fc4fcb321c 100644 --- a/jscomp/others/belt_MutableMapString.resi +++ b/jscomp/others/belt_MutableMapString.resi @@ -34,45 +34,46 @@ let has: (t<'a>, key) => bool let cmpU: (t<'a>, t<'a>, (. 'a, 'a) => int) => int -/** `cmp m1 m2 cmp` - First compare by size, if size is the same, - compare by key, value pair +/** +`cmp(m1, m2, cmp)`. First compare by size, if size is the same, compare by key, +value pair */ let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => int let eqU: (t<'a>, t<'a>, (. 'a, 'a) => bool) => bool -/** `eq m1 m2 cmp` */ +/** `eq(m1, m2, cmp)` */ let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => bool let forEachU: (t<'a>, (. key, 'a) => unit) => unit -/** `forEach m f` applies `f` to all bindings in map `m`. - `f` receives the key as first argument, and the associated value - as second argument. - The application order of `f` is in increasing order. */ +/** +`forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the key as +first argument, and the associated value as second argument. The application +order of `f` is in increasing order. */ let forEach: (t<'a>, (key, 'a) => unit) => unit let reduceU: (t<'a>, 'b, (. 'b, key, 'a) => 'b) => 'b -/** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`, - where `k1 ... kN` are the keys of all bindings in `m` - (in increasing order), and `d1 ... dN` are the associated data. */ +/** +`reduce(m, a, f)` computes `(f kN dN ... (f k1 d1 a)...)`, where `k1 ... kN` are +the keys of all bindings in `m` (in increasing order), and `d1 ... dN` are the +associated data. */ let reduce: (t<'a>, 'b, ('b, key, 'a) => 'b) => 'b let everyU: (t<'a>, (. key, 'a) => bool) => bool -/** `every m p` checks if all the bindings of the map - satisfy the predicate `p`. - The application order of `p` is unspecified. +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +The application order of `p` is unspecified. */ let every: (t<'a>, (key, 'a) => bool) => bool let someU: (t<'a>, (. key, 'a) => bool) => bool -/** `some m p` checks if at least one binding of the map - satisfy the predicate `p`. - The application order of `p` is unspecified. +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate `p`. +The application order of `p` is unspecified. */ let some: (t<'a>, (key, 'a) => bool) => bool @@ -109,14 +110,15 @@ let checkInvariantInternal: t<_> => unit /* TODO: add functional `merge, partition, keep, split` */ -/** `remove m x` do the in-place modification */ +/** `remove(m, x)` do the in-place modification */ let remove: (t<'a>, key) => unit let removeMany: (t<'a>, array) => unit -/** `set m x y` do the in-place modification, return - `m` for chaining. If `x` was already bound - in `m`, its previous binding disappears. */ +/** +`set(m, x, y)` do the in-place modification, return `m` for chaining. If `x` was +already bound in `m`, its previous binding disappears. +*/ let set: (t<'a>, key, 'a) => unit let updateU: (t<'a>, key, (. option<'a>) => option<'a>) => unit @@ -124,11 +126,11 @@ let update: (t<'a>, key, option<'a> => option<'a>) => unit let mapU: (t<'a>, (. 'a) => 'b) => t<'b> -/** `map m f` returns a map with same domain as `m`, where the - associated value `a` of all bindings of `m` has been - replaced by the result of the application of `f` to `a`. - The bindings are passed to `f` in increasing order - with respect to the ordering over the type of the keys. */ +/** +`map(m, f)` returns a map with same domain as `m`, where the associated value `a` +of all bindings of `m` has been replaced by the result of the application of `f` +to `a`. The bindings are passed to `f` in increasing order with respect to the +ordering over the type of the keys. */ let map: (t<'a>, 'a => 'b) => t<'b> let mapWithKeyU: (t<'a>, (. key, 'a) => 'b) => t<'b> diff --git a/jscomp/others/belt_MutableQueue.resi b/jscomp/others/belt_MutableQueue.resi index 04f08604ab..1bc2f8c4dc 100644 --- a/jscomp/others/belt_MutableQueue.resi +++ b/jscomp/others/belt_MutableQueue.resi @@ -15,76 +15,77 @@ /* Adapted significantly by ReScript Authors */ /*** - A FIFO (first in first out) queue data structure. +A FIFO (first in first out) queue data structure. */ /** - The type of queues containing elements of `type('a)`. +The type of queues containing elements of `type('a)`. */ type t<'a> /** - Returns a new queue, initially empty. +Returns a new queue, initially empty. */ let make: unit => t<'a> /** - Discard all elements from the queue. +Discard all elements from the queue. */ let clear: t<'a> => unit /** - Returns `true` if the given queue is empty, `false` otherwise. +Returns `true` if the given queue is empty, `false` otherwise. */ let isEmpty: t<'a> => bool /** - `fromArray` a is equivalent to `Array.forEach(a, add(q, a));` +`fromArray` a is equivalent to `Array.forEach(a, add(q, a));` */ let fromArray: array<'a> => t<'a> /** - `add(q, x)` adds the element `x` at the end of the queue `q`. +`add(q, x)` adds the element `x` at the end of the queue `q`. */ let add: (t<'a>, 'a) => unit /** - `peekOpt(q)` returns the first element in queue `q`, without removing it from the queue. +`peekOpt(q)` returns the first element in queue `q`, without removing it from the queue. */ let peek: t<'a> => option<'a> /** - `peekUndefined(q)` returns `undefined` if not found. +`peekUndefined(q)` returns `undefined` if not found. */ let peekUndefined: t<'a> => Js.undefined<'a> /** - raise an exception if `q` is empty +raise an exception if `q` is empty */ let peekExn: t<'a> => 'a /** - `pop(q)` removes and returns the first element in queue `q`. +`pop(q)` removes and returns the first element in queue `q`. */ let pop: t<'a> => option<'a> /** - `popUndefined(q)` removes and returns the first element in queue `q`. it will return `undefined` if it is already empty. +`popUndefined(q)` removes and returns the first element in queue `q`. it will +return `undefined` if it is already empty. */ let popUndefined: t<'a> => Js.undefined<'a> /** - `popExn(q)` raise an exception if q is empty. +`popExn(q)` raise an exception if q is empty. */ let popExn: t<'a> => 'a /** - `copy(q)` returns a fresh queue. +`copy(q)` returns a fresh queue. */ let copy: t<'a> => t<'a> /** - Returns the number of elements in a queue. +Returns the number of elements in a queue. */ let size: t<'a> => int @@ -93,24 +94,27 @@ let map: (t<'a>, 'a => 'b) => t<'b> let forEachU: (t<'a>, (. 'a) => unit) => unit /** - `forEach(q, f) applies`f`in turn to all elements of`q`, from the least - recently entered to the most recently entered. The queue itself is unchanged. +`forEach(q, f) applies`f`in turn to all elements of`q`, from the least +recently entered to the most recently entered. The queue itself is unchanged. */ let forEach: (t<'a>, 'a => unit) => unit let reduceU: (t<'a>, 'b, (. 'b, 'a) => 'b) => 'b /** - `reduce(q, accu, f)` is equivalent to `List.reduce(l, accu, f)`, where `l` is the list of `q`'s elements. The queue remains unchanged. +`reduce(q, accu, f)` is equivalent to `List.reduce(l, accu, f)`, where `l` is the +list of `q`'s elements. The queue remains unchanged. */ let reduce: (t<'a>, 'b, ('b, 'a) => 'b) => 'b /** - `transfer(q1, q2)` adds all of `q1`'s elements at the end of the queue `q2`, then clears `q1`. It is equivalent to the sequence `forEach((x) => add(x, q2), q1);`; clear `q1`, but runs in constant time. +`transfer(q1, q2)` adds all of `q1`'s elements at the end of the queue `q2`, +then clears `q1`. It is equivalent to the sequence `forEach((x) => add(x, q2), q1)`; +clear `q1`, but runs in constant time. */ let transfer: (t<'a>, t<'a>) => unit /** - First added will be in the beginning of the array. +First added will be in the beginning of the array. */ let toArray: t<'a> => array<'a> diff --git a/jscomp/others/belt_MutableSet.resi b/jscomp/others/belt_MutableSet.resi index 7741ba9639..8a52652025 100644 --- a/jscomp/others/belt_MutableSet.resi +++ b/jscomp/others/belt_MutableSet.resi @@ -23,179 +23,192 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - A **mutable** sorted set module which allows customized compare behavior. - The implementation uses balanced binary trees, and therefore searching and insertion take time logarithmic in the size of the map. +A **mutable** sorted set module which allows customized compare behavior. +The implementation uses balanced binary trees, and therefore searching and insertion take time logarithmic in the size of the map. - It also has two specialized inner modules [Belt.MutableSet.Int](mutable-set-int) and [Belt.MutableSet.String](mutable-set-string) - This module separates data from function which is more verbose but slightly more efficient +It also has two specialized inner modules [Belt.MutableSet.Int](mutable-set-int) and [Belt.MutableSet.String](mutable-set-string) - This module separates data from function which is more verbose but slightly more efficient - ```res example - module PairComparator = Belt.Id.MakeComparable({ - type t = (int, int) - let cmp = ((a0, a1), (b0, b1)) => - switch Pervasives.compare(a0, b0) { - | 0 => Pervasives.compare(a1, b1) - | c => c - } - }) +## Examples - let mySet = Belt.MutableSet.make(~id=module(PairComparator)) - mySet->Belt.MutableSet.add((1, 2)) - ``` -*/ +```rescript +module PairComparator = Belt.Id.MakeComparable({ + type t = (int, int) + let cmp = ((a0, a1), (b0, b1)) => + switch Pervasives.compare(a0, b0) { + | 0 => Pervasives.compare(a1, b1) + | c => c + } +}) -/** Specialized when key type is `int`, more efficient - than the generic type +let mySet = Belt.MutableSet.make(~id=module(PairComparator)) +mySet->Belt.MutableSet.add((1, 2)) +``` */ + +/** Specialized when key type is `int`, more efficient than the generic type */ module Int = Belt_MutableSetInt -/** Specialized when key type is `string`, more efficient - than the generic type */ +/** Specialized when key type is `string`, more efficient than the generic type */ module String = Belt_MutableSetString /** - `'value` is the element type +`'value` is the element type - `'identity` the identity of the collection +`'identity` the identity of the collection */ type t<'value, 'identity> /** - The identity needed for making a set from scratch +The identity needed for making a set from scratch */ type id<'value, 'id> = Belt_Id.comparable<'value, 'id> /** - Creates a new set by taking in the comparator +Creates a new set by taking in the comparator */ let make: (~id: id<'value, 'id>) => t<'value, 'id> /** - Creates new set from array of elements. +Creates new set from array of elements. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.toArray /* [1, 2, 3, 4] */ - ``` +let s0 = Belt.MutableSet.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) + +s0->Belt.MutableSet.toArray /* [1, 2, 3, 4] */ +``` */ let fromArray: (array<'value>, ~id: id<'value, 'id>) => t<'value, 'id> /** - The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. */ let fromSortedArrayUnsafe: (array<'value>, ~id: id<'value, 'id>) => t<'value, 'id> /** - Returns copy of a set. +Returns copy of a set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) - let copied = s0->Belt.MutableSet.copy - copied->Belt.MutableSet.toArray /* [1, 2, 3, 4] */ - ``` +let copied = s0->Belt.MutableSet.copy +copied->Belt.MutableSet.toArray /* [1, 2, 3, 4] */ +``` */ let copy: t<'value, 'id> => t<'value, 'id> /** - Checks if set is empty. +Checks if set is empty. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let empty = Belt.MutableSet.fromArray([], ~id=module(IntCmp)) - let notEmpty = Belt.MutableSet.fromArray([1], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - Belt.MutableSet.isEmpty(empty) /* true */ - Belt.MutableSet.isEmpty(notEmpty) /* false */ - ``` +let empty = Belt.MutableSet.fromArray([], ~id=module(IntCmp)) +let notEmpty = Belt.MutableSet.fromArray([1], ~id=module(IntCmp)) + +Belt.MutableSet.isEmpty(empty) /* true */ +Belt.MutableSet.isEmpty(notEmpty) /* false */ +``` */ let isEmpty: t<_> => bool /** - Checks if element exists in set. +Checks if element exists in set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let set = Belt.MutableSet.fromArray([1, 4, 2, 5], ~id=module(IntCmp)) +let set = Belt.MutableSet.fromArray([1, 4, 2, 5], ~id=module(IntCmp)) - set->Belt.MutableSet.has(3) /* false */ - set->Belt.MutableSet.has(1) /* true */ - ``` +set->Belt.MutableSet.has(3) /* false */ +set->Belt.MutableSet.has(1) /* true */ +``` */ let has: (t<'value, 'id>, 'value) => bool /** - Adds element to set. If element existed in set, value is unchanged. +Adds element to set. If element existed in set, value is unchanged. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.make(~id=module(IntCmp)) - s0->Belt.MutableSet.add(1) - s0->Belt.MutableSet.add(2) - s0->Belt.MutableSet.add(2) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.toArray /* [1, 2] */ - ``` +let s0 = Belt.MutableSet.make(~id=module(IntCmp)) +s0->Belt.MutableSet.add(1) +s0->Belt.MutableSet.add(2) +s0->Belt.MutableSet.add(2) + +s0->Belt.MutableSet.toArray /* [1, 2] */ +``` */ let add: (t<'value, 'id>, 'value) => unit let addCheck: (t<'value, 'id>, 'value) => bool /** - Adds each element of array to set. +Adds each element of array to set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let set = Belt.MutableSet.make(~id=module(IntCmp)) +let set = Belt.MutableSet.make(~id=module(IntCmp)) - set->Belt.MutableSet.mergeMany([5, 4, 3, 2, 1]) - set->Belt.MutableSet.toArray /* [1, 2, 3, 4, 5] */ - ``` +set->Belt.MutableSet.mergeMany([5, 4, 3, 2, 1]) +set->Belt.MutableSet.toArray /* [1, 2, 3, 4, 5] */ +``` */ let mergeMany: (t<'value, 'id>, array<'value>) => unit /** - Removes element from set. If element did not exist in set, value is unchanged. +Removes element from set. If element did not exist in set, value is unchanged. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([2, 3, 1, 4, 5], ~id=module(IntCmp)) - s0->Belt.MutableSet.remove(1) - s0->Belt.MutableSet.remove(3) - s0->Belt.MutableSet.remove(3) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.toArray /* [2,4,5] */ - ``` +let s0 = Belt.MutableSet.fromArray([2, 3, 1, 4, 5], ~id=module(IntCmp)) +s0->Belt.MutableSet.remove(1) +s0->Belt.MutableSet.remove(3) +s0->Belt.MutableSet.remove(3) + +s0->Belt.MutableSet.toArray /* [2,4,5] */ +``` */ let remove: (t<'value, 'id>, 'value) => unit @@ -203,401 +216,444 @@ let removeCheck: (t<'value, 'id>, 'value) => bool /* `b = removeCheck s e` `b` is true means one element removed */ /** - Removes each element of array from set. +Removes each element of array from set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let set = Belt.MutableSet.fromArray([1, 2, 3, 4], ~id=module(IntCmp)) +let set = Belt.MutableSet.fromArray([1, 2, 3, 4], ~id=module(IntCmp)) - set->Belt.MutableSet.removeMany([5, 4, 3, 2, 1]) - set->Belt.MutableSet.toArray /* [] */ - ``` +set->Belt.MutableSet.removeMany([5, 4, 3, 2, 1]) +set->Belt.MutableSet.toArray /* [] */ +``` */ let removeMany: (t<'value, 'id>, array<'value>) => unit /** - Returns union of two sets. +Returns union of two sets. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) - let union = Belt.MutableSet.union(s0, s1) - union->Belt.MutableSet.toArray /* [1,2,3,4,5,6] */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) +let union = Belt.MutableSet.union(s0, s1) +union->Belt.MutableSet.toArray /* [1,2,3,4,5,6] */ +``` */ let union: (t<'value, 'id>, t<'value, 'id>) => t<'value, 'id> /** - Returns intersection of two sets. +Returns intersection of two sets. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) - let intersect = Belt.MutableSet.intersect(s0, s1) - intersect->Belt.MutableSet.toArray /* [2,3,5] */ - ``` +let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) +let intersect = Belt.MutableSet.intersect(s0, s1) +intersect->Belt.MutableSet.toArray /* [2,3,5] */ +``` */ let intersect: (t<'value, 'id>, t<'value, 'id>) => t<'value, 'id> /** - Returns elements from first set, not existing in second set. +Returns elements from first set, not existing in second set. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) - Belt.MutableSet.toArray(Belt.MutableSet.diff(s0, s1)) /* [6] */ - Belt.MutableSet.toArray(Belt.MutableSet.diff(s1, s0)) /* [1,4] */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) +Belt.MutableSet.toArray(Belt.MutableSet.diff(s0, s1)) /* [6] */ +Belt.MutableSet.toArray(Belt.MutableSet.diff(s1, s0)) /* [1,4] */ +``` */ let diff: (t<'value, 'id>, t<'value, 'id>) => t<'value, 'id> /** - Checks if second set is subset of first set. +Checks if second set is subset of first set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) - let s2 = Belt.MutableSet.intersect(s0, s1) - Belt.MutableSet.subset(s2, s0) /* true */ - Belt.MutableSet.subset(s2, s1) /* true */ - Belt.MutableSet.subset(s1, s0) /* false */ - ``` +let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([5, 2, 3, 1, 5, 4], ~id=module(IntCmp)) +let s2 = Belt.MutableSet.intersect(s0, s1) +Belt.MutableSet.subset(s2, s0) /* true */ +Belt.MutableSet.subset(s2, s1) /* true */ +Belt.MutableSet.subset(s1, s0) /* false */ +``` */ let subset: (t<'value, 'id>, t<'value, 'id>) => bool /** - Total ordering between sets. Can be used as the ordering function for doing sets of sets. It compares size first and then iterates over each element following the order of elements. +Total ordering between sets. Can be used as the ordering function for doing sets of sets. +It compares size first and then iterates over each element following the order of elements. */ let cmp: (t<'value, 'id>, t<'value, 'id>) => int /** - Checks if two sets are equal. +Checks if two sets are equal. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([5, 2, 3], ~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([3, 2, 5], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.fromArray([5, 2, 3], ~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([3, 2, 5], ~id=module(IntCmp)) - Belt.MutableSet.eq(s0, s1) /* true */ - ``` +Belt.MutableSet.eq(s0, s1) /* true */ +``` */ let eq: (t<'value, 'id>, t<'value, 'id>) => bool /** - Same as [forEach](##forEach) but takes uncurried functon. + Same as `Belt.MutableSet.forEach` but takes uncurried functon. */ let forEachU: (t<'value, 'id>, (. 'value) => unit) => unit /** - Applies function `f` in turn to all elements of set in increasing order. +Applies function `f` in turn to all elements of set in increasing order. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) - let acc = ref(list{}) - s0->Belt.MutableSet.forEach(x => acc := Belt.List.add(acc.contents, x)) - acc /* [6,5,3,2] */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) +let acc = ref(list{}) +s0->Belt.MutableSet.forEach(x => acc := Belt.List.add(acc.contents, x)) +acc /* [6,5,3,2] */ +``` */ let forEach: (t<'value, 'id>, 'value => unit) => unit let reduceU: (t<'value, 'id>, 'a, (. 'a, 'value) => 'a) => 'a /** - Applies function `f` to each element of set in increasing order. Function `f` has two parameters: the item from the set and an “accumulator”, which starts with a value of `initialValue`. `reduce` returns the final value of the accumulator. +Applies function `f` to each element of set in increasing order. Function `f` has two parameters: the item from the set and an “accumulator”, which starts with a value of `initialValue`. `reduce` returns the final value of the accumulator. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) - s0->Belt.MutableSet.reduce(list{}, (acc, element) => acc->Belt.List.add(element)) /* [6,5,3,2] */ - ``` +let s0 = Belt.MutableSet.fromArray([5, 2, 3, 5, 6], ~id=module(IntCmp)) +s0->Belt.MutableSet.reduce(list{}, (acc, element) => acc->Belt.List.add(element)) /* [6,5,3,2] */ +``` */ let reduce: (t<'value, 'id>, 'a, ('a, 'value) => 'a) => 'a let everyU: (t<'value, 'id>, (. 'value) => bool) => bool /** - Checks if all elements of the set satisfy the predicate. Order unspecified. +Checks if all elements of the set satisfy the predicate. Order unspecified. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let isEven = x => mod(x, 2) == 0 +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([2, 4, 6, 8], ~id=module(IntCmp)) - s0->Belt.MutableSet.every(isEven) /* true */ - ``` +let isEven = x => mod(x, 2) == 0 + +let s0 = Belt.MutableSet.fromArray([2, 4, 6, 8], ~id=module(IntCmp)) +s0->Belt.MutableSet.every(isEven) /* true */ +``` */ let every: (t<'value, 'id>, 'value => bool) => bool let someU: (t<'value, 'id>, (. 'value) => bool) => bool /** - Checks if at least one element of the set satisfies the predicate. +Checks if at least one element of the set satisfies the predicate. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let isOdd = x => mod(x, 2) != 0 +let isOdd = x => mod(x, 2) != 0 - let s0 = Belt.MutableSet.fromArray([1, 2, 4, 6, 8], ~id=module(IntCmp)) - s0->Belt.MutableSet.some(isOdd) /* true */ - ``` +let s0 = Belt.MutableSet.fromArray([1, 2, 4, 6, 8], ~id=module(IntCmp)) +s0->Belt.MutableSet.some(isOdd) /* true */ +``` */ let some: (t<'value, 'id>, 'value => bool) => bool let keepU: (t<'value, 'id>, (. 'value) => bool) => t<'value, 'id> /** - Returns the set of all elements that satisfy the predicate. +Returns the set of all elements that satisfy the predicate. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let isEven = x => mod(x, 2) == 0 +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) - let s1 = s0->Belt.MutableSet.keep(isEven) +let isEven = x => mod(x, 2) == 0 - s1->Belt.MutableSet.toArray /* [2, 4] */ - ``` +let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) +let s1 = s0->Belt.MutableSet.keep(isEven) + +s1->Belt.MutableSet.toArray /* [2, 4] */ +``` */ let keep: (t<'value, 'id>, 'value => bool) => t<'value, 'id> let partitionU: (t<'value, 'id>, (. 'value) => bool) => (t<'value, 'id>, t<'value, 'id>) /** - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples + +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let isOdd = x => mod(x, 2) != 0 +let isOdd = x => mod(x, 2) != 0 - let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) - let (s1, s2) = s0->Belt.MutableSet.partition(isOdd) +let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) +let (s1, s2) = s0->Belt.MutableSet.partition(isOdd) - s1->Belt.MutableSet.toArray /* [1,3,5] */ - s2->Belt.MutableSet.toArray /* [2,4] */ - ``` +s1->Belt.MutableSet.toArray /* [1,3,5] */ +s2->Belt.MutableSet.toArray /* [2,4] */ +``` */ let partition: (t<'value, 'id>, 'value => bool) => (t<'value, 'id>, t<'value, 'id>) /** - Returns size of the set. +Returns size of the set. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.size /* 4 */ - ``` +let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4], ~id=module(IntCmp)) + +s0->Belt.MutableSet.size /* 4 */ +``` */ let size: t<'value, 'id> => int /** - Returns list of ordered set elements. +Returns list of ordered set elements. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) - s0->Belt.MutableSet.toList /* [1,2,3,5] */ - ``` +s0->Belt.MutableSet.toList /* [1,2,3,5] */ +``` */ let toList: t<'value, 'id> => list<'value> /** - Returns array of ordered set elements. +Returns array of ordered set elements. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.toArray /* [1,2,3,5] */ - ``` +let s0 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) + +s0->Belt.MutableSet.toArray /* [1,2,3,5] */ +``` */ let toArray: t<'value, 'id> => array<'value> /** - Returns minimum value of the collection. `None` if collection is empty. +Returns minimum value of the collection. `None` if collection is empty. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.make(~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.make(~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) - s0->Belt.MutableSet.minimum /* None */ - s1->Belt.MutableSet.minimum /* Some(1) */ - ``` +s0->Belt.MutableSet.minimum /* None */ +s1->Belt.MutableSet.minimum /* Some(1) */ +``` */ let minimum: t<'value, 'id> => option<'value> /** - Returns minimum value of the collection. `undefined` if collection is empty. +Returns minimum value of the collection. `undefined` if collection is empty. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.make(~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.minUndefined /* undefined */ - s1->Belt.MutableSet.minUndefined /* 1 */ - ``` +let s0 = Belt.MutableSet.make(~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) + +s0->Belt.MutableSet.minUndefined /* undefined */ +s1->Belt.MutableSet.minUndefined /* 1 */ +``` */ let minUndefined: t<'value, 'id> => Js.undefined<'value> /** - Returns maximum value of the collection. `None` if collection is empty. +Returns maximum value of the collection. `None` if collection is empty. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.make(~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.make(~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) - s0->Belt.MutableSet.maximum /* None */ - s1->Belt.MutableSet.maximum /* Some(5) */ - ``` +s0->Belt.MutableSet.maximum /* None */ +s1->Belt.MutableSet.maximum /* Some(5) */ +``` */ let maximum: t<'value, 'id> => option<'value> /** - Returns maximum value of the collection. `undefined` if collection is empty. +Returns maximum value of the collection. `undefined` if collection is empty. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.MutableSet.make(~id=module(IntCmp)) - let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.MutableSet.maxUndefined /* undefined */ - s1->Belt.MutableSet.maxUndefined /* 5 */ - ``` +let s0 = Belt.MutableSet.make(~id=module(IntCmp)) +let s1 = Belt.MutableSet.fromArray([3, 2, 1, 5], ~id=module(IntCmp)) + +s0->Belt.MutableSet.maxUndefined /* undefined */ +s1->Belt.MutableSet.maxUndefined /* 5 */ +``` */ let maxUndefined: t<'value, 'id> => Js.undefined<'value> /** - Returns the reference of the value which is equivalent to value using the comparator specifiecd by this collection. Returns `None` if element does not exist. +Returns the reference of the value which is equivalent to value using the comparator specifiecd by this collection. Returns `None` if element does not exist. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) - s0->Belt.MutableSet.get(3) /* Some(3) */ - s0->Belt.MutableSet.get(20) /* None */ - ``` +s0->Belt.MutableSet.get(3) /* Some(3) */ +s0->Belt.MutableSet.get(20) /* None */ +``` */ let get: (t<'value, 'id>, 'value) => option<'value> /** - Same as [get](#get) but returns `undefined` when element does not exist. +Same as `Belt.MutableSet.get` but returns `undefined` when element does not exist. */ let getUndefined: (t<'value, 'id>, 'value) => Js.undefined<'value> /** - Same as [get](#get) but raise when element does not exist. +Same as `Belt.MutableSet.get` but raise when element does not exist. */ let getExn: (t<'value, 'id>, 'value) => 'value /** - Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. +Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) +let s0 = Belt.MutableSet.fromArray([1, 2, 3, 4, 5], ~id=module(IntCmp)) - let ((smaller, larger), present) = s0->Belt.MutableSet.split(3) +let ((smaller, larger), present) = s0->Belt.MutableSet.split(3) - present /* true */ - smaller->Belt.MutableSet.toArray /* [1,2] */ - larger->Belt.MutableSet.toArray /* [4,5] */ - ``` +present /* true */ +smaller->Belt.MutableSet.toArray /* [1,2] */ +larger->Belt.MutableSet.toArray /* [4,5] */ +``` */ let split: (t<'value, 'id>, 'value) => ((t<'value, 'id>, t<'value, 'id>), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit diff --git a/jscomp/others/belt_MutableSetInt.resi b/jscomp/others/belt_MutableSetInt.resi index 12a2f485de..e7dc512685 100644 --- a/jscomp/others/belt_MutableSetInt.resi +++ b/jscomp/others/belt_MutableSetInt.resi @@ -23,12 +23,12 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type. +This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, - and identity is not needed(using the built-in one) +It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.MutableSet`]() +**See** [`Belt.MutableSet`]() */ /** The type of the set elements. */ @@ -73,28 +73,34 @@ let reduce: (t, 'a, ('a, value) => 'a) => 'a let everyU: (t, (. value) => bool) => bool -/** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. */ +/** +`every(p, s)` checks if all elements of the set satisfy the predicate `p`. +Order unspecified. */ let every: (t, value => bool) => bool let someU: (t, (. value) => bool) => bool -/** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. */ +/** +`some(p, s)` checks if at least one element of the set satisfies the predicate +`p`. Oder unspecified. +*/ let some: (t, value => bool) => bool let keepU: (t, (. value) => bool) => t -/** `keep s p` returns a fresh copy of the set of all elements in `s` - that satisfy predicate `p`. */ +/** +`keep(s, p)` returns a fresh copy of the set of all elements in `s` that satisfy +predicate `p`. +*/ let keep: (t, value => bool) => t let partitionU: (t, (. value) => bool) => (t, t) -/** `partition s p` returns a fresh copy pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. */ +/** +`partition(s, p)` returns a fresh copy pair of sets `(s1, s2)`, where `s1` is +the set of all the elements of `s` that satisfy the predicate `p`, and `s2` is +the set of all the elements of `s` that do not satisfy `p`. +*/ let partition: (t, value => bool) => (t, t) let size: t => int @@ -115,11 +121,11 @@ let getUndefined: (t, value) => Js.undefined let getExn: (t, value) => value /** - `split s key` return a fresh copy of each +`split(s, key)` return a fresh copy of each */ let split: (t, value) => ((t, t), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t => unit diff --git a/jscomp/others/belt_MutableSetString.resi b/jscomp/others/belt_MutableSetString.resi index 7c39aed2ce..72aa9bebe6 100644 --- a/jscomp/others/belt_MutableSetString.resi +++ b/jscomp/others/belt_MutableSetString.resi @@ -23,12 +23,12 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type. +This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, - and identity is not needed(using the built-in one) +It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.MutableSet`]() +**See** [`Belt.MutableSet`]() */ /** The type of the set elements. */ @@ -73,28 +73,34 @@ let reduce: (t, 'a, ('a, value) => 'a) => 'a let everyU: (t, (. value) => bool) => bool -/** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. */ +/** +`every(p, s)` checks if all elements of the set satisfy the predicate `p`. +Order unspecified. */ let every: (t, value => bool) => bool let someU: (t, (. value) => bool) => bool -/** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. */ +/** +`some(p, s)` checks if at least one element of the set satisfies the predicate +`p`. Oder unspecified. +*/ let some: (t, value => bool) => bool let keepU: (t, (. value) => bool) => t -/** `keep s p` returns a fresh copy of the set of all elements in `s` - that satisfy predicate `p`. */ +/** +`keep(s, p)` returns a fresh copy of the set of all elements in `s` that satisfy +predicate `p`. +*/ let keep: (t, value => bool) => t let partitionU: (t, (. value) => bool) => (t, t) -/** `partition s p` returns a fresh copy pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. */ +/** +`partition(s, p)` returns a fresh copy pair of sets `(s1, s2)`, where `s1` is +the set of all the elements of `s` that satisfy the predicate `p`, and `s2` is +the set of all the elements of `s` that do not satisfy `p`. +*/ let partition: (t, value => bool) => (t, t) let size: t => int @@ -115,11 +121,11 @@ let getUndefined: (t, value) => Js.undefined let getExn: (t, value) => value /** - `split s key` return a fresh copy of each +`split(s, key)` return a fresh copy of each */ let split: (t, value) => ((t, t), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t => unit diff --git a/jscomp/others/belt_MutableStack.resi b/jscomp/others/belt_MutableStack.resi index 8bddbe67dc..cb11d4afe4 100644 --- a/jscomp/others/belt_MutableStack.resi +++ b/jscomp/others/belt_MutableStack.resi @@ -30,17 +30,17 @@ modification. type t<'a> /** - Returns a new stack, initially empty. +Returns a new stack, initially empty. */ let make: unit => t<'a> /** - Discard all elements from the stack. +Discard all elements from the stack. */ let clear: t<'a> => unit /** - `copy(x)` O(1) operation, return a new stack. +`copy(x)` O(1) operation, return a new stack. */ let copy: t<'a> => t<'a> @@ -56,8 +56,8 @@ let forEach: (t<'a>, 'a => unit) => unit let dynamicPopIterU: (t<'a>, (. 'a) => unit) => unit /** - `dynamicPopIter(s, f)` apply `f` to each element of `s`. The item is poped - before applying `f`, `s` will be empty after this opeartion. This function is - useful for worklist algorithm. +`dynamicPopIter(s, f)` apply `f` to each element of `s`. The item is poped +before applying `f`, `s` will be empty after this opeartion. This function is +useful for worklist algorithm. */ let dynamicPopIter: (t<'a>, 'a => unit) => unit diff --git a/jscomp/others/belt_Option.resi b/jscomp/others/belt_Option.resi index 95c79b52ff..5764811e60 100644 --- a/jscomp/others/belt_Option.resi +++ b/jscomp/others/belt_Option.resi @@ -23,32 +23,36 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - In Belt we represent the existence and nonexistence of a value by wrapping it - with the `option` type. In order to make it a bit more convenient to work with - option-types, Belt provides utility-functions for it. +In Belt we represent the existence and nonexistence of a value by wrapping it +with the `option` type. In order to make it a bit more convenient to work with +option-types, Belt provides utility-functions for it. - The `option` type is a part of the ReScript standard library which is defined like this: +The `option` type is a part of the ReScript standard library which is defined like this: - ```res sig - type option<'a> = None | Some('a) - ``` +## Examples - ```res example - let someString: option = Some("hello") - ``` +```rescript +type option<'a> = None | Some('a) +``` + +```rescript +let someString: option = Some("hello") +``` */ /** Uncurried version of `keep` */ let keepU: (option<'a>, (. 'a) => bool) => option<'a> /** - If `optionValue` is `Some(value)` and `p(value) = true`, it returns `Some(value)`; otherwise returns `None` +If `optionValue` is `Some(value)` and `p(value) = true`, it returns `Some(value)`; otherwise returns `None` + +## Examples - ```res example - Belt.Option.keep(Some(10), x => x > 5) /* returns `Some(10)` */ - Belt.Option.keep(Some(4), x => x > 5) /* returns `None` */ - Belt.Option.keep(None, x => x > 5) /* returns `None` */ - ``` +```rescript +Belt.Option.keep(Some(10), x => x > 5) /* returns `Some(10)` */ +Belt.Option.keep(Some(4), x => x > 5) /* returns `None` */ +Belt.Option.keep(None, x => x > 5) /* returns `None` */ +``` */ let keep: (option<'a>, 'a => bool) => option<'a> @@ -56,31 +60,35 @@ let keep: (option<'a>, 'a => bool) => option<'a> let forEachU: (option<'a>, (. 'a) => unit) => unit /** - If `optionValue` is `Some(value`), it calls `f(value)`; otherwise returns `()` +If `optionValue` is `Some(value`), it calls `f(value)`; otherwise returns `()` - ```res example - Belt.Option.forEach(Some("thing"), x => Js.log(x)) /* logs "thing" */ - Belt.Option.forEach(None, x => Js.log(x)) /* returns () */ - ``` +## Examples + +```rescript +Belt.Option.forEach(Some("thing"), x => Js.log(x)) /* logs "thing" */ +Belt.Option.forEach(None, x => Js.log(x)) /* returns () */ +``` */ let forEach: (option<'a>, 'a => unit) => unit /** - Raises an Error in case `None` is provided. Use with care. +Raises an Error in case `None` is provided. Use with care. + +## Examples - ```res example - Belt.Option.getExn(Some(3)) /* 3 */ +```rescript +Belt.Option.getExn(Some(3)) /* 3 */ - Belt.Option.getExn(None) /* Raises an Error */ - ``` +Belt.Option.getExn(None) /* Raises an Error */ +``` */ let getExn: option<'a> => 'a /** - `getUnsafe(x)` returns `x` +`getUnsafe(x)` returns `x` - This is an unsafe operation, it assumes `x` is neither `None` - nor `Some(None(...)))` +This is an unsafe operation, it assumes `x` is neither `None` +nor `Some(None(...)))` */ external getUnsafe: option<'a> => 'a = "%identity" @@ -88,18 +96,20 @@ external getUnsafe: option<'a> => 'a = "%identity" let mapWithDefaultU: (option<'a>, 'b, (. 'a) => 'b) => 'b /** - If `optionValue` is of `Some(value)`, - this function returns that value applied with `f`, in other words `f(value)`. +If `optionValue` is of `Some(value)`, +this function returns that value applied with `f`, in other words `f(value)`. - If `optionValue` is `None`, the default is returned. +If `optionValue` is `None`, the default is returned. - ```res example - let someValue = Some(3) - someValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 8 */ +## Examples - let noneValue = None - noneValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 0 */ - ``` +```rescript +let someValue = Some(3) +someValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 8 */ + +let noneValue = None +noneValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 0 */ +``` */ let mapWithDefault: (option<'a>, 'b, 'a => 'b) => 'b @@ -107,13 +117,15 @@ let mapWithDefault: (option<'a>, 'b, 'a => 'b) => 'b let mapU: (option<'a>, (. 'a) => 'b) => option<'b> /** - If `optionValue` is `Some(value)` this returns `f(value)`, otherwise it returns `None`. +If `optionValue` is `Some(value)` this returns `f(value)`, otherwise it returns `None`. + +## Examples - ```res example - Belt.Option.map(Some(3), x => x * x) /* Some(9) */ +```rescript +Belt.Option.map(Some(3), x => x * x) /* Some(9) */ - Belt.Option.map(None, x => x * x) /* None */ - ``` +Belt.Option.map(None, x => x * x) /* None */ +``` */ let map: (option<'a>, 'a => 'b) => option<'b> @@ -121,148 +133,163 @@ let map: (option<'a>, 'a => 'b) => option<'b> let flatMapU: (option<'a>, (. 'a) => option<'b>) => option<'b> /** - If `optionValue` is `Some(value)`, returns `f(value)`, otherwise returns - `None`.
- The function `f` must have a return type of `option<'b>`. +If `optionValue` is `Some(value)`, returns `f(value)`, otherwise returns +`None`.
+The function `f` must have a return type of `option<'b>`. + +## Examples - ```res example - let addIfAboveOne = value => - if (value > 1) { - Some(value + 1) - } else { - None - } +```rescript +let addIfAboveOne = value => + if (value > 1) { + Some(value + 1) + } else { + None + } - Belt.Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */ +Belt.Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */ - Belt.Option.flatMap(Some(-4), addIfAboveOne) /* None */ +Belt.Option.flatMap(Some(-4), addIfAboveOne) /* None */ - Belt.Option.flatMap(None, addIfAboveOne) /* None */ - ``` +Belt.Option.flatMap(None, addIfAboveOne) /* None */ +``` */ let flatMap: (option<'a>, 'a => option<'b>) => option<'b> /** - If `optionalValue` is `Some(value)`, returns `value`, otherwise default. +If `optionalValue` is `Some(value)`, returns `value`, otherwise default. - ```res example - Belt.Option.getWithDefault(None, "Banana") /* Banana */ +## Examples - Belt.Option.getWithDefault(Some("Apple"), "Banana") /* Apple */ - ``` +```rescript +Belt.Option.getWithDefault(None, "Banana") /* Banana */ - ```res example - let greet = (firstName: option) => - "Greetings " ++ firstName->Belt.Option.getWithDefault("Anonymous") +Belt.Option.getWithDefault(Some("Apple"), "Banana") /* Apple */ +``` - Some("Jane")->greet /* "Greetings Jane" */ +```rescript +let greet = (firstName: option) => + "Greetings " ++ firstName->Belt.Option.getWithDefault("Anonymous") - None->greet /* "Greetings Anonymous" */ - ``` +Some("Jane")->greet /* "Greetings Jane" */ + +None->greet /* "Greetings Anonymous" */ +``` */ let getWithDefault: (option<'a>, 'a) => 'a /** - `orElse optionalValue otherOptional` +`orElse(optionalValue, otherOptional)` if `optionalValue` is `Some(value)`, +returns `Some(value)`, otherwise `otherOptional` - If `optionalValue` is `Some value`, returns `Some value`, otherwise `otherOptional` +## Examples - ``` - orElse (Some 1812) (Some 1066) = Some 1812;; - orElse None (Some 1066) = Some 1066;; - orElse None None = None;; - ``` +```rescript +Belt.Option.orElse(Some(1812), Some(1066)) == Some(1812) +Belt.Option.orElse(None, Some(1066)) == Some(1066) +Belt.Option.orElse(None, None) == None +``` */ let orElse: (option<'a>, option<'a>) => option<'a> /** - Returns `true` if the argument is `Some(value)`, `false` otherwise. +Returns `true` if the argument is `Some(value)`, `false` otherwise. + +## Examples - ```res example - Belt.Option.isSome(None) /* false */ +```rescript +Belt.Option.isSome(None) /* false */ - Belt.Option.isSome(Some(1)) /* true */ - ``` +Belt.Option.isSome(Some(1)) /* true */ +``` */ let isSome: option<'a> => bool /** - Returns `true` if the argument is `None`, `false` otherwise. +Returns `true` if the argument is `None`, `false` otherwise. - ```res example - Belt.Option.isNone(None) /* true */ +## Examples - Belt.Option.isNone(Some(1)) /* false */ - ``` +```rescript +Belt.Option.isNone(None) /* true */ + +Belt.Option.isNone(Some(1)) /* false */ +``` */ let isNone: option<'a> => bool /** - Uncurried version of `eq` +Uncurried version of `eq` */ let eqU: (option<'a>, option<'b>, (. 'a, 'b) => bool) => bool /** - Evaluates two optional values for equality with respect to a predicate - function. If both `optValue1` and `optValue2` are `None`, returns `true`. - If one of the arguments is `Some(value)` and the other is `None`, returns - `false`. +Evaluates two optional values for equality with respect to a predicate +function. If both `optValue1` and `optValue2` are `None`, returns `true`. +If one of the arguments is `Some(value)` and the other is `None`, returns +`false`. + +If arguments are `Some(value1)` and `Some(value2)`, returns the result of +`predicate(value1, value2)`; the predicate function must return a bool. - If arguments are `Some(value1)` and `Some(value2)`, returns the result of - `predicate(value1, value2)`; the predicate function must return a bool. +## Examples - ```res example - let clockEqual = (a, b) => mod(a, 12) == mod(b, 12) +```rescript +let clockEqual = (a, b) => mod(a, 12) == mod(b, 12) - open Belt.Option +open Belt.Option - eq(Some(3), Some(15), clockEqual) /* true */ +eq(Some(3), Some(15), clockEqual) /* true */ - eq(Some(3), None, clockEqual) /* false */ +eq(Some(3), None, clockEqual) /* false */ - eq(None, Some(3), clockEqual) /* false */ +eq(None, Some(3), clockEqual) /* false */ - eq(None, None, clockEqual) /* true */ - ``` +eq(None, None, clockEqual) /* true */ +``` */ let eq: (option<'a>, option<'b>, ('a, 'b) => bool) => bool -/** Uncurried version of `cmp` */ +/** +Uncurried version of `cmp` +*/ let cmpU: (option<'a>, option<'b>, (. 'a, 'b) => int) => int /** - `cmp(optValue1, optValue2, comparisonFunction)` compares two optional values - with respect to given `comparisonFunction`. +`cmp(optValue1, optValue2, comparisonFunction)` compares two optional values +with respect to given `comparisonFunction`. + +If both `optValue1` and `optValue2` are `None`, it returns `0`. - If both `optValue1` and `optValue2` are `None`, it returns `0`. +If the first argument is `Some(value1)` and the second is `None`, returns `1` +(something is greater than nothing). - If the first argument is `Some(value1)` and the second is `None`, returns `1` - (something is greater than nothing). +If the first argument is `None` and the second is `Some(value2)`, returns `-1` +(nothing is less than something). - If the first argument is `None` and the second is `Some(value2)`, returns `-1` - (nothing is less than something). +If the arguments are `Some(value1)` and `Some(value2)`, returns the result of +`comparisonFunction(value1, value2)`; comparisonFunction takes two arguments +and returns `-1` if the first argument is less than the second, `0` if the +arguments are equal, and `1` if the first argument is greater than the second. - If the arguments are `Some(value1)` and `Some(value2)`, returns the result of - `comparisonFunction(value1, value2)`; comparisonFunction takes two arguments - and returns `-1` if the first argument is less than the second, `0` if the - arguments are equal, and `1` if the first argument is greater than the second. +## Examples - ```res example - let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12)) +```rescript +let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12)) - open Belt.Option +open Belt.Option - cmp(Some(3), Some(15), clockCompare) /* 0 */ +cmp(Some(3), Some(15), clockCompare) /* 0 */ - cmp(Some(3), Some(14), clockCompare) /* 1 */ +cmp(Some(3), Some(14), clockCompare) /* 1 */ - cmp(Some(2), Some(15), clockCompare) /* (-1) */ +cmp(Some(2), Some(15), clockCompare) /* (-1) */ - cmp(None, Some(15), clockCompare) /* (-1) */ +cmp(None, Some(15), clockCompare) /* (-1) */ - cmp(Some(14), None, clockCompare) /* 1 */ +cmp(Some(14), None, clockCompare) /* 1 */ - cmp(None, None, clockCompare) /* 0 */ - ``` +cmp(None, None, clockCompare) /* 0 */ +``` */ let cmp: (option<'a>, option<'b>, ('a, 'b) => int) => int diff --git a/jscomp/others/belt_Range.resi b/jscomp/others/belt_Range.resi index b14e68000f..b0ad2f2050 100644 --- a/jscomp/others/belt_Range.resi +++ b/jscomp/others/belt_Range.resi @@ -23,92 +23,87 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - A small utility module to provide inclusive range operations for `[start, - finish]`. Internally it is relying on loops instead of creating new arrays, - which makes it pretty performant and memory friendly. +A small utility module to provide inclusive range operations for `[start, finish]`. +Internally it is relying on loops instead of creating new arrays, which makes it +pretty performant and memory friendly. */ let forEachU: (int, int, (. int) => unit) => unit /** - `forEach(start, finish, action)` - - equivalent to `Belt.Array.(forEach(range(start, finish), action))` - - ```res example - Belt.Range.forEach(0, 4, (i) => Js.log(i)) - - /** - * prints: - * 0 - * 1 - * 2 - * 3 - * 4 - */ - ``` +`forEach(start, finish, action)` equivalent to `Belt.Array.forEach(Belt.Array.range(start, finish), action))` + +## Examples + +```rescript +Belt.Range.forEach(0, 4, (i) => Js.log(i)) + +// Prints: +// 0 +// 1 +// 2 +// 3 +// 4 +``` */ let forEach: (int, int, int => unit) => unit let everyU: (int, int, (. int) => bool) => bool /** - `every(start, finish, p)` +`every(start, finish, p)` equivalent to `Belt.Array.every(Belt.Array.range(start, finish), p)` +## Examples - equivalent to `Belt.Array.(every(range(start, finish), p))` +```rescript +Belt.Range.every(0, 4, (i) => i < 5) /* true */ - ```res example - Belt.Range.every(0, 4, (i) => i < 5) /* true */ - - Belt.Range.every(0, 4, (i) => i < 4) /* false */ - ``` +Belt.Range.every(0, 4, (i) => i < 4) /* false */ +``` */ let every: (int, int, int => bool) => bool let everyByU: (int, int, ~step: int, (. int) => bool) => bool /** - `everyBy(start, finish, ~step, p)` - - See `Belt_Array.rangeBy` +`everyBy(start, finish, ~step, p)`. See `Belt.Array.rangeBy`, equivalent to +`Belt.Array.every(Belt.Array.rangeBy(start, finish, ~step), p)` - equivalent to `Belt.Array.(every(rangeBy(start, finish, ~step), p))` +## Examples - ```res example - Belt.Range.everyBy(0, 4, ~step=1, (i) => mod(i, 2) === 0) /* false */ +```rescript +Belt.Range.everyBy(0, 4, ~step=1, (i) => mod(i, 2) === 0) /* false */ - Belt.Range.everyBy(0, 4, ~step=2, (i) => mod(i, 2) === 0) /* true */ - ``` +Belt.Range.everyBy(0, 4, ~step=2, (i) => mod(i, 2) === 0) /* true */ +``` */ let everyBy: (int, int, ~step: int, int => bool) => bool let someU: (int, int, (. int) => bool) => bool /** - `some(start, finish, p)` +`some(start, finish, p)` equivalent to `Belt.Array.some(Belt.Array.range(start, finish), p)` - equivalent to `Belt.Array.(some(range(start, finish), p))` +## Examples - ```res example - Belt.Range.some(0, 4, (i) => i > 5) /* false */ +```rescript +Belt.Range.some(0, 4, (i) => i > 5) /* false */ - Belt.Range.some(0, 4, (i) => i > 2) /* true */ - ``` +Belt.Range.some(0, 4, (i) => i > 2) /* true */ +``` */ let some: (int, int, int => bool) => bool let someByU: (int, int, ~step: int, (. int) => bool) => bool /** - `someBy(start, finish, ~step, p)` - - See `Belt_Array.rangeBy` +`someBy(start, finish, ~step, p)` See `Belt.Array.rangeBy`, equivalent to +`Belt.Array.some(Belt.Array.rangeBy(start, finish, ~step), p)` - equivalent to `Belt.Array.(some(rangeBy(start, finish, ~step), p))` +## Examples - ```res example - Belt.Range.someBy(1, 5, ~step=2, (i) => mod(i, 2) === 0) /* false */ - Belt.Range.someBy(0, 4, ~step=2, (i) => mod(i, 2) === 0) /* true */ - ``` +```rescript +Belt.Range.someBy(1, 5, ~step=2, (i) => mod(i, 2) === 0) /* false */ +Belt.Range.someBy(0, 4, ~step=2, (i) => mod(i, 2) === 0) /* true */ +``` */ let someBy: (int, int, ~step: int, int => bool) => bool diff --git a/jscomp/others/belt_Result.resi b/jscomp/others/belt_Result.resi index 4e47d11c66..91e1f66c2b 100644 --- a/jscomp/others/belt_Result.resi +++ b/jscomp/others/belt_Result.resi @@ -23,10 +23,10 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Result types are really useful to describe the result of a certain operation - without relying on exceptions or `option` types. +Result types are really useful to describe the result of a certain operation +without relying on exceptions or `option` types. - This module gives you useful utilities to create and combine `Result` data. +This module gives you useful utilities to create and combine `Result` data. */ type t<'a, 'b> = result<'a, 'b> = @@ -34,157 +34,171 @@ type t<'a, 'b> = result<'a, 'b> = | Error('b) /** - `getExn(res)`: when `res` is `Ok(n)`, returns `n` when `res` is `Error(m)`, raise an exception +`getExn(res)`: when `res` is `Ok(n)`, returns `n` when `res` is `Error(m)`, raise an exception - ```res example - Belt.Result.getExn(Belt.Result.Ok(42)) == 42 +## Examples - Belt.Result.getExn(Belt.Result.Error("Invalid data")) /* raises exception */ - ``` +```rescript +Belt.Result.getExn(Belt.Result.Ok(42)) == 42 + +Belt.Result.getExn(Belt.Result.Error("Invalid data")) /* raises exception */ +``` */ let getExn: t<'a, 'b> => 'a let mapWithDefaultU: (t<'a, 'c>, 'b, (. 'a) => 'b) => 'b /** - `mapWithDefault(res, default, f)`: When res is `Ok(n)`, returns `f(n)`, - otherwise `default`. +`mapWithDefault(res, default, f)`: When res is `Ok(n)`, returns `f(n)`, +otherwise `default`. + +## Examples - ```res example - let ok = Belt.Result.Ok(42) - Belt.Result.mapWithDefault(ok, 0, (x) => x / 2) == 21 +```rescript +let ok = Belt.Result.Ok(42) +Belt.Result.mapWithDefault(ok, 0, (x) => x / 2) == 21 - let error = Belt.Result.Error("Invalid data") - Belt.Result.mapWithDefault(error, 0, (x) => x / 2) == 0 - ``` +let error = Belt.Result.Error("Invalid data") +Belt.Result.mapWithDefault(error, 0, (x) => x / 2) == 0 +``` */ let mapWithDefault: (t<'a, 'c>, 'b, 'a => 'b) => 'b let mapU: (t<'a, 'c>, (. 'a) => 'b) => t<'b, 'c> /** - `map(res, f)`: When res is `Ok(n)`, returns `Ok(f(n))`. Otherwise returns res - unchanged. Function `f` takes a value of the same type as `n` and returns an - ordinary value. +`map(res, f)`: When res is `Ok(n)`, returns `Ok(f(n))`. Otherwise returns res +unchanged. Function `f` takes a value of the same type as `n` and returns an +ordinary value. - ```res example - let f = (x) => sqrt(Belt.Int.toFloat(x)) +## Examples - Belt.Result.map(Ok(64), f) == Ok(8.0) +```rescript +let f = (x) => sqrt(Belt.Int.toFloat(x)) - Belt.Result.map(Error("Invalid data"), f) == Error("Invalid data") - ``` +Belt.Result.map(Ok(64), f) == Ok(8.0) + +Belt.Result.map(Error("Invalid data"), f) == Error("Invalid data") +``` */ let map: (t<'a, 'c>, 'a => 'b) => t<'b, 'c> let flatMapU: (t<'a, 'c>, (. 'a) => t<'b, 'c>) => t<'b, 'c> /** - `flatMap(res, f)`: When res is `Ok(n)`, returns `f(n)`. Otherwise, returns res - unchanged. Function `f` takes a value of the same type as `n` and returns a - `Belt.Result`. +`flatMap(res, f)`: When res is `Ok(n)`, returns `f(n)`. Otherwise, returns res +unchanged. Function `f` takes a value of the same type as `n` and returns a +`Belt.Result`. + +## Examples - ```res example - let recip = (x) => - if (x !== 0.0) { - Belt.Result.Ok(1.0 /. x) - } else { - Belt.Result.Error("Divide by zero") - } +```rescript +let recip = (x) => + if (x !== 0.0) { + Belt.Result.Ok(1.0 /. x) + } else { + Belt.Result.Error("Divide by zero") + } - Belt.Result.flatMap(Ok(2.0), recip) == Ok(0.5) +Belt.Result.flatMap(Ok(2.0), recip) == Ok(0.5) - Belt.Result.flatMap(Ok(0.0), recip) == Error("Divide by zero") +Belt.Result.flatMap(Ok(0.0), recip) == Error("Divide by zero") - Belt.Result.flatMap(Error("Already bad"), recip) == Error("Already bad") - ``` +Belt.Result.flatMap(Error("Already bad"), recip) == Error("Already bad") +``` */ let flatMap: (t<'a, 'c>, 'a => t<'b, 'c>) => t<'b, 'c> /** - `getWithDefault(res, defaultValue)`: If `res` is `Ok(n)`, returns `n`, - otherwise `default` +`getWithDefault(res, defaultValue)`: If `res` is `Ok(n)`, returns `n`, +otherwise `default` - ```res example - Belt.Result.getWithDefault(Ok(42), 0) == 42 +## Examples - Belt.Result.getWithDefault(Error("Invalid Data"), 0) == 0 - ``` +```rescript +Belt.Result.getWithDefault(Ok(42), 0) == 42 + +Belt.Result.getWithDefault(Error("Invalid Data"), 0) == 0 +``` */ let getWithDefault: (t<'a, 'b>, 'a) => 'a /** - `isOk(res)`: Returns `true` if `res` is of the form `Ok(n)`, `false` if it is - the `Error(e)` variant. +`isOk(res)`: Returns `true` if `res` is of the form `Ok(n)`, `false` if it is +the `Error(e)` variant. */ let isOk: t<'a, 'b> => bool /** - `isError(res)`: Returns `true` if `res` is of the form `Error(e)`, `false` if - it is the `Ok(n)` variant. +`isError(res)`: Returns `true` if `res` is of the form `Error(e)`, `false` if +it is the `Ok(n)` variant. */ let isError: t<'a, 'b> => bool let eqU: (t<'a, 'c>, t<'b, 'd>, (. 'a, 'b) => bool) => bool /** - `eq(res1, res2, f)`: Determine if two `Belt.Result` variables are equal with - respect to an equality function. If `res1` and `res2` are of the form `Ok(n)` - and `Ok(m)`, return the result of `f(n, m)`. If one of `res1` and `res2` are of - the form `Error(e)`, return false If both `res1` and `res2` are of the form - `Error(e)`, return true +`eq(res1, res2, f)`: Determine if two `Belt.Result` variables are equal with +respect to an equality function. If `res1` and `res2` are of the form `Ok(n)` +and `Ok(m)`, return the result of `f(n, m)`. If one of `res1` and `res2` are of +the form `Error(e)`, return false If both `res1` and `res2` are of the form +`Error(e)`, return true + +## Examples - ```res example - let good1 = Belt.Result.Ok(42) +```rescript +let good1 = Belt.Result.Ok(42) - let good2 = Belt.Result.Ok(32) +let good2 = Belt.Result.Ok(32) - let bad1 = Belt.Result.Error("invalid") +let bad1 = Belt.Result.Error("invalid") - let bad2 = Belt.Result.Error("really invalid") +let bad2 = Belt.Result.Error("really invalid") - let mod10equal = (a, b) => mod(a, 10) === mod(b, 10) +let mod10equal = (a, b) => mod(a, 10) === mod(b, 10) - Belt.Result.eq(good1, good2, mod10equal) == true +Belt.Result.eq(good1, good2, mod10equal) == true - Belt.Result.eq(good1, bad1, mod10equal) == false +Belt.Result.eq(good1, bad1, mod10equal) == false - Belt.Result.eq(bad2, good2, mod10equal) == false +Belt.Result.eq(bad2, good2, mod10equal) == false - Belt.Result.eq(bad1, bad2, mod10equal) == true - ``` +Belt.Result.eq(bad1, bad2, mod10equal) == true +``` */ let eq: (t<'a, 'c>, t<'b, 'd>, ('a, 'b) => bool) => bool let cmpU: (t<'a, 'c>, t<'b, 'd>, (. 'a, 'b) => int) => int /** - `cmp(res1, res2, f)`: Compare two `Belt.Result` variables with respect to a - comparison function. The comparison function returns -1 if the first variable - is "less than" the second, 0 if the two variables are equal, and 1 if the first - is "greater than" the second. +`cmp(res1, res2, f)`: Compare two `Belt.Result` variables with respect to a +comparison function. The comparison function returns -1 if the first variable +is "less than" the second, 0 if the two variables are equal, and 1 if the first +is "greater than" the second. + +If `res1` and `res2` are of the form `Ok(n)` and `Ok(m)`, return the result of +`f(n, m)`. If `res1` is of the form `Error(e)` and `res2` of the form `Ok(n)`, +return -1 (nothing is less than something) If `res1` is of the form `Ok(n)` and +`res2` of the form `Error(e)`, return 1 (something is greater than nothing) If +both `res1` and `res2` are of the form `Error(e)`, return 0 (equal) - If `res1` and `res2` are of the form `Ok(n)` and `Ok(m)`, return the result of - `f(n, m)`. If `res1` is of the form `Error(e)` and `res2` of the form `Ok(n)`, - return -1 (nothing is less than something) If `res1` is of the form `Ok(n)` and - `res2` of the form `Error(e)`, return 1 (something is greater than nothing) If - both `res1` and `res2` are of the form `Error(e)`, return 0 (equal) +## Examples - ```res example - let good1 = Belt.Result.Ok(59) +```rescript +let good1 = Belt.Result.Ok(59) - let good2 = Belt.Result.Ok(37) +let good2 = Belt.Result.Ok(37) - let bad1 = Belt.Result.Error("invalid") +let bad1 = Belt.Result.Error("invalid") - let bad2 = Belt.Result.Error("really invalid") +let bad2 = Belt.Result.Error("really invalid") - let mod10cmp = (a, b) => Pervasives.compare(mod(a, 10), mod(b, 10)) +let mod10cmp = (a, b) => Pervasives.compare(mod(a, 10), mod(b, 10)) - Belt.Result.cmp(Ok(39), Ok(57), mod10cmp) == 1 +Belt.Result.cmp(Ok(39), Ok(57), mod10cmp) == 1 - Belt.Result.cmp(Ok(57), Ok(39), mod10cmp) == (-1) +Belt.Result.cmp(Ok(57), Ok(39), mod10cmp) == (-1) - Belt.Result.cmp(Ok(39), Error("y"), mod10cmp) == 1 +Belt.Result.cmp(Ok(39), Error("y"), mod10cmp) == 1 - Belt.Result.cmp(Error("x"), Ok(57), mod10cmp) == (-1) +Belt.Result.cmp(Error("x"), Ok(57), mod10cmp) == (-1) - Belt.Result.cmp(Error("x"), Error("y"), mod10cmp) == 0 - ``` +Belt.Result.cmp(Error("x"), Error("y"), mod10cmp) == 0 +``` */ let cmp: (t<'a, 'c>, t<'b, 'd>, ('a, 'b) => int) => int diff --git a/jscomp/others/belt_Set.cppo.resi b/jscomp/others/belt_Set.cppo.resi index 2d249225a3..60703e4cf6 100644 --- a/jscomp/others/belt_Set.cppo.resi +++ b/jscomp/others/belt_Set.cppo.resi @@ -53,12 +53,16 @@ let isEmpty: t => bool let has: (t, value) => bool -/** `add s x` If `x` was already in `s`, `s` is returned unchanged. */ +/** +`add(s, x)` If `x` was already in `s`, `s` is returned unchanged. +*/ let add: (t, value) => t let mergeMany: (t, array) => t -/** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. */ +/** +`remove(m, x)` If `x` was not in `m`, `m` is returned reference unchanged. +*/ let remove: (t, value) => t let removeMany: (t, array) => t @@ -69,22 +73,28 @@ let intersect: (t, t) => t let diff: (t, t) => t -/** `subset s1 s2` tests whether the set `s1` is a subset of - the set `s2`. */ +/** +`subset(s1, s20` tests whether the set `s1` is a subset of the set `s2`. +*/ let subset: (t, t) => bool -/** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. */ +/** +Total ordering between sets. Can be used as the ordering function for doing sets +of sets. +*/ let cmp: (t, t) => int -/** `eq s1 s2` tests whether the sets `s1` and `s2` are - equal, that is, contain equal elements. */ +/** +`eq(s1, s2)` tests whether the sets `s1` and `s2` are equal, that is, contain +equal elements. +*/ let eq: (t, t) => bool let forEachU: (t, (. value) => unit) => unit -/** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order */ +/** +`forEach(s, f)` applies `f` in turn to all elements of `s`. In increasing order +*/ let forEach: (t, value => unit) => unit let reduceU: (t, 'a, (. 'a, value) => 'a) => 'a @@ -94,29 +104,33 @@ let reduce: (t, 'a, ('a, value) => 'a) => 'a let everyU: (t, (. value) => bool) => bool -/** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. */ +/** +`every(p, s)` checks if all elements of the set satisfy the predicate `p`. Order +unspecified. +*/ let every: (t, value => bool) => bool let someU: (t, (. value) => bool) => bool -/** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. */ +/** +`some(p, s)` checks if at least one element of the set satisfies the predicate +`p`. Oder unspecified. +*/ let some: (t, value => bool) => bool let keepU: (t, (. value) => bool) => t -/** `keep p s` returns the set of all elements in `s` - that satisfy predicate `p`. */ +/** +`keep(p, s)` returns the set of all elements in `s` that satisfy predicate `p`. +*/ let keep: (t, value => bool) => t let partitionU: (t, (. value) => bool) => (t, t) /** - `partition p s` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. +`partition(p, s)` returns a pair of sets `(s1, s2)`, where `s1` is the set of +all the elements of `s` that satisfy the predicate `p`, and `s2` is the set of +all the elements of `s` that do not satisfy `p`. */ let partition: (t, value => bool) => (t, t) @@ -142,17 +156,14 @@ let getUndefined: (t, value) => Js.undefined let getExn: (t, value) => value /** - `split x s` returns a triple `(l, present, r)`, where - `l` is the set of elements of `s` that are - strictly less than `x`; - `r` is the set of elements of `s` that are - strictly greater than `x`; - `present` is `false` if `s` contains no element equal to `x`, - or `true` if `s` contains an element equal to `x`. +`split(x, s)` returns a triple `(l, present, r)`, where `l` is the set of +elements of `s` that are strictly less than `x`;`r` is the set of elements of +`s` that are strictly greater than `x`; `present` is `false` if `s` contains no +element equal to `x`, or `true` if `s` contains an element equal to `x`. */ let split: (t, value) => ((t, t), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t => unit diff --git a/jscomp/others/belt_Set.resi b/jscomp/others/belt_Set.resi index 49970308f9..a7b8e00731 100644 --- a/jscomp/others/belt_Set.resi +++ b/jscomp/others/belt_Set.resi @@ -22,464 +22,527 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** An _immutable_ sorted set module which allows customized _compare_ behavior. - - The implementation uses balanced binary trees, and therefore searching - and insertion take time logarithmic in the size of the map. - - For more info on this module's usage of identity, `make` and others, please see - the top level documentation of Belt, **A special encoding for collection safety**. - - Example usage: - - ```res example - module PairComparator = - Belt.Id.MakeComparable({ - type t = (int, int) - let cmp = ((a0, a1), (b0, b1)) => - switch (Pervasives.compare(a0, b0)) { - | 0 => Pervasives.compare(a1, b1) - | c => c - } - }) +/*** +An _immutable_ sorted set module which allows customized _compare_ behavior. + +The implementation uses balanced binary trees, and therefore searching +and insertion take time logarithmic in the size of the map. + +For more info on this module's usage of identity, `make` and others, please see +the top level documentation of Belt, **A special encoding for collection safety**. + +## Examples + +```rescript +module PairComparator = + Belt.Id.MakeComparable({ + type t = (int, int) + let cmp = ((a0, a1), (b0, b1)) => + switch (Pervasives.compare(a0, b0)) { + | 0 => Pervasives.compare(a1, b1) + | c => c + } + }) - let mySet = Belt.Set.make(~id=module(PairComparator)) - let mySet2 = Belt.Set.add(mySet, (1, 2)) - ``` +let mySet = Belt.Set.make(~id=module(PairComparator)) +let mySet2 = Belt.Set.add(mySet, (1, 2)) +``` - **Note:** This module's examples will assume a predeclared module for integers - called `IntCmp`. It is declared like this: +**Note:** This module's examples will assume a predeclared module for integers +called `IntCmp`. It is declared like this: - ```res example - module IntCmp = - Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) - ``` +```rescript +module IntCmp = + Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) +``` */ -/** Specialized when value type is `int`, more efficient - than the generic type, its compare behavior is fixed using the built-in comparison +/** +Specialized when value type is `int`, more efficient than the generic type, its +compare behavior is fixed using the built-in comparison */ module Int = Belt_SetInt -/** Specialized when value type is `string`, more efficient - than the generic type, its compare behavior is fixed using the built-in comparison +/** +Specialized when value type is `string`, more efficient than the generic type, +its compare behavior is fixed using the built-in comparison */ module String = Belt_SetString -/** This module separates identity from data, it is a bit more verbose but slightly - more efficient due to the fact that there is no need to pack identity and data back - after each operation +/** +This module separates identity from data, it is a bit more verbose but slightly +more efficient due to the fact that there is no need to pack identity and data back +after each operation */ module Dict = Belt_SetDict /** - `'value` is the element type +`'value` is the element type - `'identity` the identity of the collection +`'identity` the identity of the collection */ type t<'value, 'identity> /** - The identity needed for making a set from scratch +The identity needed for making a set from scratch */ type id<'value, 'id> = Belt_Id.comparable<'value, 'id> /** - Creates a new set by taking in the comparator +Creates a new set by taking in the comparator - ```res example - let set = Belt.Set.make(~id=module(IntCmp)) - ``` +## Examples + +```rescript +let set = Belt.Set.make(~id=module(IntCmp)) +``` */ let make: (~id: id<'value, 'id>) => t<'value, 'id> /** - Creates new set from array of elements. +Creates new set from array of elements. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.fromArray([1, 3, 2, 4], ~id=module(IntCmp)) - s0->Belt.Set.toArray /* [1, 2, 3, 4] */ - ``` +s0->Belt.Set.toArray /* [1, 2, 3, 4] */ +``` */ let fromArray: (array<'value>, ~id: id<'value, 'id>) => t<'value, 'id> /** - The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +The same as [fromArray][#fromarray] except it is after assuming the input array +is already sorted. */ let fromSortedArrayUnsafe: (array<'value>, ~id: id<'value, 'id>) => t<'value, 'id> /** - Checks if set is empty. +Checks if set is empty. - ```res example - let empty = Belt.Set.fromArray([], ~id=module(IntCmp)) - let notEmpty = Belt.Set.fromArray([1],~id=module(IntCmp)) +## Examples - Belt.Set.isEmpty(empty) /* true */ - Belt.Set.isEmpty(notEmpty) /* false */ - ``` +```rescript +let empty = Belt.Set.fromArray([], ~id=module(IntCmp)) +let notEmpty = Belt.Set.fromArray([1],~id=module(IntCmp)) + +Belt.Set.isEmpty(empty) /* true */ +Belt.Set.isEmpty(notEmpty) /* false */ +``` */ let isEmpty: t<_> => bool /** - Checks if element exists in set. +Checks if element exists in set. + +## Examples - ```res example - let set = Belt.Set.fromArray([1, 4, 2, 5], ~id=module(IntCmp)) +```rescript +let set = Belt.Set.fromArray([1, 4, 2, 5], ~id=module(IntCmp)) - set->Belt.Set.has(3) /* false */ - set->Belt.Set.has(1) /* true */ - ``` +set->Belt.Set.has(3) /* false */ +set->Belt.Set.has(1) /* true */ +``` */ let has: (t<'value, 'id>, 'value) => bool /** - Adds element to set. If element existed in set, value is unchanged. +Adds element to set. If element existed in set, value is unchanged. + +## Examples - ```res example - let s0 = Belt.Set.make(~id=module(IntCmp)) - let s1 = s0->Belt.Set.add(1) - let s2 = s1->Belt.Set.add(2) - let s3 = s2->Belt.Set.add(2) - s0->Belt.Set.toArray /* [] */ - s1->Belt.Set.toArray /* [1] */ - s2->Belt.Set.toArray /* [1, 2] */ - s3->Belt.Set.toArray /* [1,2 ] */ - s2 == s3 /* true */ - ``` +```rescript +let s0 = Belt.Set.make(~id=module(IntCmp)) +let s1 = s0->Belt.Set.add(1) +let s2 = s1->Belt.Set.add(2) +let s3 = s2->Belt.Set.add(2) +s0->Belt.Set.toArray /* [] */ +s1->Belt.Set.toArray /* [1] */ +s2->Belt.Set.toArray /* [1, 2] */ +s3->Belt.Set.toArray /* [1,2 ] */ +s2 == s3 /* true */ +``` */ let add: (t<'value, 'id>, 'value) => t<'value, 'id> /** - Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set +Adds each element of array to set. Unlike `Belt.Set.add`](#add), the reference of return value might be changed even if all values in array already exist in set - ```res example - let set = Belt.Set.make(~id=module(IntCmp)) +## Examples - let newSet = set->Belt.Set.mergeMany([5, 4, 3, 2, 1]) - newSet->Belt.Set.toArray /* [1, 2, 3, 4, 5] */ - ``` +```rescript +let set = Belt.Set.make(~id=module(IntCmp)) + +let newSet = set->Belt.Set.mergeMany([5, 4, 3, 2, 1]) +newSet->Belt.Set.toArray /* [1, 2, 3, 4, 5] */ +``` */ let mergeMany: (t<'value, 'id>, array<'value>) => t<'value, 'id> /** - Removes element from set. If element did not exist in set, value is unchanged. +Removes element from set. If element did not exist in set, value is unchanged. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([2,3,1,4,5], ~id=module(IntCmp)) - let s1 = s0->Belt.Set.remove(1) - let s2 = s1->Belt.Set.remove(3) - let s3 = s2->Belt.Set.remove(3) +```rescript +let s0 = Belt.Set.fromArray([2,3,1,4,5], ~id=module(IntCmp)) +let s1 = s0->Belt.Set.remove(1) +let s2 = s1->Belt.Set.remove(3) +let s3 = s2->Belt.Set.remove(3) - s1->Belt.Set.toArray /* [2,3,4,5] */ - s2->Belt.Set.toArray /* [2,4,5] */ - s2 == s3 /* true */ - ``` +s1->Belt.Set.toArray /* [2,3,4,5] */ +s2->Belt.Set.toArray /* [2,4,5] */ +s2 == s3 /* true */ +``` */ let remove: (t<'value, 'id>, 'value) => t<'value, 'id> /** - Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if none of values in array existed in set. +Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if none of values in array existed in set. - ```res example - let set = Belt.Set.fromArray([1, 2, 3, 4],~id=module(IntCmp)) +## Examples - let newSet = set->Belt.Set.removeMany([5, 4, 3, 2, 1]) - newSet->Belt.Set.toArray /* [] */ - ``` +```rescript +let set = Belt.Set.fromArray([1, 2, 3, 4],~id=module(IntCmp)) + +let newSet = set->Belt.Set.removeMany([5, 4, 3, 2, 1]) +newSet->Belt.Set.toArray /* [] */ +``` */ let removeMany: (t<'value, 'id>, array<'value>) => t<'value, 'id> /** - Returns union of two sets. + Returns union of two sets. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) - let union = Belt.Set.union(s0, s1) - union->Belt.Set.toArray /* [1,2,3,4,5,6] */ - ``` +```rescript +let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) +let union = Belt.Set.union(s0, s1) +union->Belt.Set.toArray /* [1,2,3,4,5,6] */ +``` */ let union: (t<'value, 'id>, t<'value, 'id>) => t<'value, 'id> /** - Returns intersection of two sets. +Returns intersection of two sets. - ```res example - let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) - let intersect = Belt.Set.intersect(s0, s1) - intersect->Belt.Set.toArray /* [2,3,5] */ - ``` +## Examples + +```rescript +let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) +let intersect = Belt.Set.intersect(s0, s1) +intersect->Belt.Set.toArray /* [2,3,5] */ +``` */ let intersect: (t<'value, 'id>, t<'value, 'id>) => t<'value, 'id> /** - Returns elements from first set, not existing in second set. +Returns elements from first set, not existing in second set. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) - Belt.Set.toArray(Belt.Set.diff(s0, s1)) /* [6] */ - Belt.Set.toArray(Belt.Set.diff(s1,s0)) /* [1,4] */ - ``` +```rescript +let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) +Belt.Set.toArray(Belt.Set.diff(s0, s1)) /* [6] */ +Belt.Set.toArray(Belt.Set.diff(s1,s0)) /* [1,4] */ +``` */ let diff: (t<'value, 'id>, t<'value, 'id>) => t<'value, 'id> /** - Checks if second set is subset of first set. +Checks if second set is subset of first set. - ```res example - let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) - let s2 = Belt.Set.intersect(s0, s1) - Belt.Set.subset(s2, s0) /* true */ - Belt.Set.subset(s2, s1) /* true */ - Belt.Set.subset(s1, s0) /* false */ - ``` +## Examples + +```rescript +let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([5,2,3,1,5,4], ~id=module(IntCmp)) +let s2 = Belt.Set.intersect(s0, s1) +Belt.Set.subset(s2, s0) /* true */ +Belt.Set.subset(s2, s1) /* true */ +Belt.Set.subset(s1, s0) /* false */ +``` */ let subset: (t<'value, 'id>, t<'value, 'id>) => bool /** - Total ordering between sets. Can be used as the ordering function for doing sets of sets. It compares size first and then iterates over each element following the order of elements. +Total ordering between sets. Can be used as the ordering function for doing sets +of sets. It compares size first and then iterates over each element following +the order of elements. */ let cmp: (t<'value, 'id>, t<'value, 'id>) => int /** - Checks if two sets are equal. +Checks if two sets are equal. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([5,2,3], ~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([3,2,5], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.fromArray([5,2,3], ~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([3,2,5], ~id=module(IntCmp)) - Belt.Set.eq(s0, s1) /* true */ - ``` +Belt.Set.eq(s0, s1) /* true */ +``` */ let eq: (t<'value, 'id>, t<'value, 'id>) => bool /** - Same as [forEach](##forEach) but takes uncurried functon. +Same as [forEach](#forEach) but takes uncurried functon. */ let forEachU: (t<'value, 'id>, (. 'value) => unit) => unit /** - Applies function `f` in turn to all elements of set in increasing order. +Applies function `f` in turn to all elements of set in increasing order. - ```res example - let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) - let acc = ref(list{}) - s0->Belt.Set.forEach(x => { - acc := Belt.List.add(acc.contents, x) - }) - acc /* [6,5,3,2] */ - ``` +## Examples + +```rescript +let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) +let acc = ref(list{}) +s0->Belt.Set.forEach(x => { + acc := Belt.List.add(acc.contents, x) +}) +acc /* [6,5,3,2] */ +``` */ let forEach: (t<'value, 'id>, 'value => unit) => unit let reduceU: (t<'value, 'id>, 'a, (. 'a, 'value) => 'a) => 'a /** - Applies function `f` to each element of set in increasing order. Function `f` has two parameters: the item from the set and an “accumulator”, which starts with a value of `initialValue`. `reduce` returns the final value of the accumulator. +Applies function `f` to each element of set in increasing order. Function `f` has two parameters: the item from the set and an “accumulator”, which starts with a value of `initialValue`. `reduce` returns the final value of the accumulator. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) - s0->Belt.Set.reduce(list{}, (acc, element) => - acc->Belt.List.add(element) - ) /* [6,5,3,2] */ - ``` +```rescript +let s0 = Belt.Set.fromArray([5,2,3,5,6], ~id=module(IntCmp)) +s0->Belt.Set.reduce(list{}, (acc, element) => + acc->Belt.List.add(element) +) /* [6,5,3,2] */ +``` */ let reduce: (t<'value, 'id>, 'a, ('a, 'value) => 'a) => 'a let everyU: (t<'value, 'id>, (. 'value) => bool) => bool /** - Checks if all elements of the set satisfy the predicate. Order unspecified. +Checks if all elements of the set satisfy the predicate. Order unspecified. - ```res example - let isEven = x => mod(x, 2) == 0 +## Examples - let s0 = Belt.Set.fromArray([2,4,6,8], ~id=module(IntCmp)) - s0->Belt.Set.every(isEven) /* true */ - ``` +```rescript +let isEven = x => mod(x, 2) == 0 + +let s0 = Belt.Set.fromArray([2,4,6,8], ~id=module(IntCmp)) +s0->Belt.Set.every(isEven) /* true */ +``` */ let every: (t<'value, 'id>, 'value => bool) => bool let someU: (t<'value, 'id>, (. 'value) => bool) => bool /** - Checks if at least one element of the set satisfies the predicate. +Checks if at least one element of the set satisfies the predicate. + +## Examples - ```res example - let isOdd = x => mod(x, 2) != 0 +```rescript +let isOdd = x => mod(x, 2) != 0 - let s0 = Belt.Set.fromArray([1,2,4,6,8], ~id=module(IntCmp)) - s0->Belt.Set.some(isOdd) /* true */ - ``` +let s0 = Belt.Set.fromArray([1,2,4,6,8], ~id=module(IntCmp)) +s0->Belt.Set.some(isOdd) /* true */ +``` */ let some: (t<'value, 'id>, 'value => bool) => bool let keepU: (t<'value, 'id>, (. 'value) => bool) => t<'value, 'id> /** - Returns the set of all elements that satisfy the predicate. +Returns the set of all elements that satisfy the predicate. - ```res example - let isEven = x => mod(x, 2) == 0 +## Examples - let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) - let s1 = s0->Belt.Set.keep(isEven) +```rescript +let isEven = x => mod(x, 2) == 0 - s1->Belt.Set.toArray /* [2,4] */ - ``` +let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) +let s1 = s0->Belt.Set.keep(isEven) + +s1->Belt.Set.toArray /* [2,4] */ +``` */ let keep: (t<'value, 'id>, 'value => bool) => t<'value, 'id> let partitionU: (t<'value, 'id>, (. 'value) => bool) => (t<'value, 'id>, t<'value, 'id>) /** - Returns a pair of sets, where first is the set of all the elements of set that satisfy the predicate, and second is the set of all the elements of set that do not satisfy the predicate. +Returns a pair of sets, where first is the set of all the elements of set that satisfy the predicate, and second is the set of all the elements of set that do not satisfy the predicate. + +## Examples - ```res example - let isOdd = x => mod(x, 2) != 0 +```rescript +let isOdd = x => mod(x, 2) != 0 - let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) - let (s1, s2) = s0->Belt.Set.partition(isOdd) +let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) +let (s1, s2) = s0->Belt.Set.partition(isOdd) - s1->Belt.Set.toArray /* [1,3,5] */ - s2->Belt.Set.toArray /* [2,4] */ - ``` +s1->Belt.Set.toArray /* [1,3,5] */ +s2->Belt.Set.toArray /* [2,4] */ +``` */ let partition: (t<'value, 'id>, 'value => bool) => (t<'value, 'id>, t<'value, 'id>) /** - Returns size of the set. +Returns size of the set. - ```res example - let s0 = Belt.Set.fromArray([1,2,3,4], ~id=module(IntCmp)) +## Examples - s0->Belt.Set.size /* 4 */ - ``` +```rescript +let s0 = Belt.Set.fromArray([1,2,3,4], ~id=module(IntCmp)) + +s0->Belt.Set.size /* 4 */ +``` */ let size: t<'value, 'id> => int /** - Returns array of ordered set elements. +Returns array of ordered set elements. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - s0->Belt.Set.toArray /* [1,2,3,5] */ - ``` +s0->Belt.Set.toArray /* [1,2,3,5] */ +``` */ let toArray: t<'value, 'id> => array<'value> /** - Returns list of ordered set elements. +Returns list of ordered set elements. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - s0->Belt.Set.toList /* [1,2,3,5] */ - ``` +s0->Belt.Set.toList /* [1,2,3,5] */ +``` */ let toList: t<'value, 'id> => list<'value> /** - Returns minimum value of the collection. `None` if collection is empty. +Returns minimum value of the collection. `None` if collection is empty. - ```res example - let s0 = Belt.Set.make(~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) +## Examples - s0->Belt.Set.minimum /* None */ - s1->Belt.Set.minimum /* Some(1) */ - ``` +```rescript +let s0 = Belt.Set.make(~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) + +s0->Belt.Set.minimum /* None */ +s1->Belt.Set.minimum /* Some(1) */ +``` */ let minimum: t<'value, 'id> => option<'value> /** - Returns minimum value of the collection. `undefined` if collection is empty. +Returns minimum value of the collection. `undefined` if collection is empty. + +## Examples - ```res example - let s0 = Belt.Set.make(~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.make(~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - s0->Belt.Set.minUndefined /* undefined */ - s1->Belt.Set.minUndefined /* 1 */ - ``` +s0->Belt.Set.minUndefined /* undefined */ +s1->Belt.Set.minUndefined /* 1 */ +``` */ let minUndefined: t<'value, 'id> => Js.undefined<'value> /** - Returns maximum value of the collection. `None` if collection is empty. +Returns maximum value of the collection. `None` if collection is empty. - ```res example - let s0 = Belt.Set.make(~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) +## Examples - s0->Belt.Set.maximum /* None */ - s1->Belt.Set.maximum /* Some(5) */ - ``` +```rescript +let s0 = Belt.Set.make(~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) + +s0->Belt.Set.maximum /* None */ +s1->Belt.Set.maximum /* Some(5) */ +``` */ let maximum: t<'value, 'id> => option<'value> /** - Returns maximum value of the collection. `undefined` if collection is empty. +Returns maximum value of the collection. `undefined` if collection is empty. + +## Examples - ```res example - let s0 = Belt.Set.make(~id=module(IntCmp)) - let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.make(~id=module(IntCmp)) +let s1 = Belt.Set.fromArray([3,2,1,5], ~id=module(IntCmp)) - s0->Belt.Set.maxUndefined /* undefined */ - s1->Belt.Set.maxUndefined /* 5 */ - ``` +s0->Belt.Set.maxUndefined /* undefined */ +s1->Belt.Set.maxUndefined /* 5 */ +``` */ let maxUndefined: t<'value, 'id> => Js.undefined<'value> /** - Returns the reference of the value which is equivalent to value using the comparator specifiecd by this collection. Returns `None` if element does not exist. +Returns the reference of the value which is equivalent to value using the comparator specifiecd by this collection. Returns `None` if element does not exist. - ```res example - let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) +## Examples - s0->Belt.Set.get(3) /* Some(3) */ - s0->Belt.Set.get(20) /* None */ - ``` +```rescript +let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) + +s0->Belt.Set.get(3) /* Some(3) */ +s0->Belt.Set.get(20) /* None */ +``` */ let get: (t<'value, 'id>, 'value) => option<'value> /** - Same as [get](#get) but returns `undefined` when element does not exist. +Same as [get](#get) but returns `undefined` when element does not exist. */ let getUndefined: (t<'value, 'id>, 'value) => Js.undefined<'value> /** - Same as [get](#get) but raise when element does not exist. +Same as [get](#get) but raise when element does not exist. */ let getExn: (t<'value, 'id>, 'value) => 'value /** - Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. +Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. + +## Examples - ```res example - let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) +```rescript +let s0 = Belt.Set.fromArray([1,2,3,4,5], ~id=module(IntCmp)) - let ((smaller, larger), present) = s0->Belt.Set.split(3) +let ((smaller, larger), present) = s0->Belt.Set.split(3) - present /* true */ - smaller->Belt.Set.toArray /* [1,2] */ - larger->Belt.Set.toArray /* [4,5] */ +present /* true */ +smaller->Belt.Set.toArray /* [1,2] */ +larger->Belt.Set.toArray /* [4,5] */ - ``` +``` */ let split: (t<'value, 'id>, 'value) => ((t<'value, 'id>, t<'value, 'id>), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit @@ -490,22 +553,23 @@ let checkInvariantInternal: t<_> => unit */ /** - **Advanced usage only** +**Advanced usage only** - Returns the raw data (detached from comparator), but its type is still manifested, so that user can pass identity directly without boxing. +Returns the raw data (detached from comparator), but its type is still manifested, +so that user can pass identity directly without boxing. */ let getData: t<'value, 'id> => Belt_SetDict.t<'value, 'id> /** - **Advanced usage only** +**Advanced usage only** - Returns the identity of set. +Returns the identity of set. */ let getId: t<'value, 'id> => id<'value, 'id> /** - **Advanced usage only** +**Advanced usage only** - Returns the packed collection. +Returns the packed collection. */ let packIdData: (~id: id<'value, 'id>, ~data: Belt_SetDict.t<'value, 'id>) => t<'value, 'id> diff --git a/jscomp/others/belt_SetDict.resi b/jscomp/others/belt_SetDict.resi index 0d87ca00bc..4f740a63f4 100644 --- a/jscomp/others/belt_SetDict.resi +++ b/jscomp/others/belt_SetDict.resi @@ -23,541 +23,603 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module separates identity from data. It is a bit more verbose but slightly more efficient due to the fact that there is no need to pack identity and data back after each operation. +This module separates identity from data. It is a bit more verbose but slightly +more efficient due to the fact that there is no need to pack identity and data +back after each operation. */ /** - `'value` is the element type +`'value` is the element type - `'identity` the identity of the collection +`'identity` the identity of the collection */ type t<'value, 'identity> /** - Type of compare function. +Type of compare function. */ type cmp<'value, 'id> = Belt_Id.cmp<'value, 'id> /** - ```res example - let s0 = Belt.Set.Dict.empty - ``` +## Examples + +```rescript +let s0 = Belt.Set.Dict.empty +``` */ let empty: t<'value, 'id> /** - Creates new set from array of elements. +Creates new set from array of elements. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([1, 3, 2, 4], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([1, 3, 2, 4], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.toArray /* [1, 2, 3, 4] */ - ``` +s0->Belt.Set.Dict.toArray /* [1, 2, 3, 4] */ +``` */ let fromArray: (array<'value>, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - The same as [fromArray][#fromarray] except it is after assuming the input array is already sorted. +The same as [fromArray][#fromarray] except it is after assuming the input array +is already sorted. */ let fromSortedArrayUnsafe: array<'value> => t<'value, 'id> /** - Checks if set is empty. +Checks if set is empty. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let empty = Belt.Set.Dict.fromArray([], ~cmp=IntCmp.cmp) - let notEmpty = Belt.Set.Dict.fromArray([1], ~cmp=IntCmp.cmp) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - Belt.Set.Dict.isEmpty(empty) /* true */ - Belt.Set.Dict.isEmpty(notEmpty) /* false */ - ``` +let empty = Belt.Set.Dict.fromArray([], ~cmp=IntCmp.cmp) +let notEmpty = Belt.Set.Dict.fromArray([1], ~cmp=IntCmp.cmp) + +Belt.Set.Dict.isEmpty(empty) /* true */ +Belt.Set.Dict.isEmpty(notEmpty) /* false */ +``` */ let isEmpty: t<_> => bool /** - Checks if an element exists in the set. +Checks if an element exists in the set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let set = Belt.Set.Dict.fromArray([1, 4, 2, 5], ~cmp=IntCmp.cmp) +let set = Belt.Set.Dict.fromArray([1, 4, 2, 5], ~cmp=IntCmp.cmp) - set->Belt.Set.Dict.has(3, ~cmp=IntCmp.cmp) /* false */ - set->Belt.Set.Dict.has(1, ~cmp=IntCmp.cmp) /* true */ - ``` +set->Belt.Set.Dict.has(3, ~cmp=IntCmp.cmp) /* false */ +set->Belt.Set.Dict.has(1, ~cmp=IntCmp.cmp) /* true */ +``` */ let has: (t<'value, 'id>, 'value, ~cmp: cmp<'value, 'id>) => bool /** - Adds element to set. If element existed in set, value is unchanged. +Adds element to set. If element existed in set, value is unchanged. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.empty - let s1 = s0->Belt.Set.Dict.add(1, ~cmp=IntCmp.cmp) - let s2 = s1->Belt.Set.Dict.add(2, ~cmp=IntCmp.cmp) - let s3 = s2->Belt.Set.Dict.add(2, ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.toArray /* [] */ - s1->Belt.Set.Dict.toArray /* [1] */ - s2->Belt.Set.Dict.toArray /* [1, 2] */ - s3->Belt.Set.Dict.toArray /* [1,2 ] */ - s2 == s3 /* true */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.Set.Dict.empty +let s1 = s0->Belt.Set.Dict.add(1, ~cmp=IntCmp.cmp) +let s2 = s1->Belt.Set.Dict.add(2, ~cmp=IntCmp.cmp) +let s3 = s2->Belt.Set.Dict.add(2, ~cmp=IntCmp.cmp) +s0->Belt.Set.Dict.toArray /* [] */ +s1->Belt.Set.Dict.toArray /* [1] */ +s2->Belt.Set.Dict.toArray /* [1, 2] */ +s3->Belt.Set.Dict.toArray /* [1,2 ] */ +s2 == s3 /* true */ +``` */ let add: (t<'value, 'id>, 'value, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set +Adds each element of array to set. Unlike [add](#add), the reference of return value might be changed even if all values in array already exist in set + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let set = Belt.Set.Dict.empty +let set = Belt.Set.Dict.empty - let newSet = set->Belt.Set.Dict.mergeMany([5, 4, 3, 2, 1], ~cmp=IntCmp.cmp) - newSet->Belt.Set.Dict.toArray /* [1, 2, 3, 4, 5] */ - ``` +let newSet = set->Belt.Set.Dict.mergeMany([5, 4, 3, 2, 1], ~cmp=IntCmp.cmp) +newSet->Belt.Set.Dict.toArray /* [1, 2, 3, 4, 5] */ +``` */ let mergeMany: (t<'value, 'id>, array<'value>, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Removes element from set. If element did not exist in set, value is unchanged. +Removes element from set. If element did not exist in set, value is unchanged. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([2, 3, 1, 4, 5], ~cmp=IntCmp.cmp) - let s1 = s0->Belt.Set.Dict.remove(1, ~cmp=IntCmp.cmp) - let s2 = s1->Belt.Set.Dict.remove(3, ~cmp=IntCmp.cmp) - let s3 = s2->Belt.Set.Dict.remove(3, ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([2, 3, 1, 4, 5], ~cmp=IntCmp.cmp) +let s1 = s0->Belt.Set.Dict.remove(1, ~cmp=IntCmp.cmp) +let s2 = s1->Belt.Set.Dict.remove(3, ~cmp=IntCmp.cmp) +let s3 = s2->Belt.Set.Dict.remove(3, ~cmp=IntCmp.cmp) - s1->Belt.Set.Dict.toArray /* [2,3,4,5] */ - s2->Belt.Set.Dict.toArray /* [2,4,5] */ - s2 == s3 /* true */ - ``` +s1->Belt.Set.Dict.toArray /* [2,3,4,5] */ +s2->Belt.Set.Dict.toArray /* [2,4,5] */ +s2 == s3 /* true */ +``` */ let remove: (t<'value, 'id>, 'value, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if any values in array not existed in set. +Removes each element of array from set. Unlike [remove](#remove), the reference of return value might be changed even if any values in array not existed in set. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let set = Belt.Set.Dict.fromArray([1, 2, 3, 4], ~cmp=IntCmp.cmp) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let newSet = set->Belt.Set.Dict.removeMany([5, 4, 3, 2, 1], ~cmp=IntCmp.cmp) - newSet->Belt.Set.Dict.toArray /* [] */ - ``` +let set = Belt.Set.Dict.fromArray([1, 2, 3, 4], ~cmp=IntCmp.cmp) + +let newSet = set->Belt.Set.Dict.removeMany([5, 4, 3, 2, 1], ~cmp=IntCmp.cmp) +newSet->Belt.Set.Dict.toArray /* [] */ +``` */ let removeMany: (t<'value, 'id>, array<'value>, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Returns union of two sets. +Returns union of two sets. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) - let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) - let union = Belt.Set.Dict.union(s0, s1, ~cmp=IntCmp.cmp) - union->Belt.Set.Dict.toArray /* [1,2,3,4,5,6] */ - ``` +let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) +let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) +let union = Belt.Set.Dict.union(s0, s1, ~cmp=IntCmp.cmp) +union->Belt.Set.Dict.toArray /* [1,2,3,4,5,6] */ +``` */ let union: (t<'value, 'id>, t<'value, 'id>, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Returns intersection of two sets. +Returns intersection of two sets. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) - let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) - let intersect = Belt.Set.Dict.intersect(s0, s1, ~cmp=IntCmp.cmp) - intersect->Belt.Set.Dict.toArray /* [2,3,5] */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) +let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) +let intersect = Belt.Set.Dict.intersect(s0, s1, ~cmp=IntCmp.cmp) +intersect->Belt.Set.Dict.toArray /* [2,3,5] */ +``` */ let intersect: (t<'value, 'id>, t<'value, 'id>, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Returns elements from first set, not existing in second set. +Returns elements from first set, not existing in second set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) - let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) +let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) - let diff1 = Belt.Set.Dict.diff(s0, s1, ~cmp=IntCmp.cmp) - let diff2 = Belt.Set.Dict.diff(s1, s0, ~cmp=IntCmp.cmp) +let diff1 = Belt.Set.Dict.diff(s0, s1, ~cmp=IntCmp.cmp) +let diff2 = Belt.Set.Dict.diff(s1, s0, ~cmp=IntCmp.cmp) - diff1->Belt.Set.Dict.toArray /* [6] */ - diff2->Belt.Set.Dict.toArray /* [1,4] */ - ``` +diff1->Belt.Set.Dict.toArray /* [6] */ +diff2->Belt.Set.Dict.toArray /* [1,4] */ +``` */ let diff: (t<'value, 'id>, t<'value, 'id>, ~cmp: cmp<'value, 'id>) => t<'value, 'id> /** - Checks if second set is subset of first set. +Checks if second set is subset of first set. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) - let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) - let s2 = Belt.Set.Dict.intersect(s0, s1, ~cmp=IntCmp.cmp) - Belt.Set.Dict.subset(s2, s0, ~cmp=IntCmp.cmp) /* true */ - Belt.Set.Dict.subset(s2, s1, ~cmp=IntCmp.cmp) /* true */ - Belt.Set.Dict.subset(s1, s0, ~cmp=IntCmp.cmp) /* false */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) +let s1 = Belt.Set.Dict.fromArray([5, 2, 3, 1, 5, 4], ~cmp=IntCmp.cmp) +let s2 = Belt.Set.Dict.intersect(s0, s1, ~cmp=IntCmp.cmp) +Belt.Set.Dict.subset(s2, s0, ~cmp=IntCmp.cmp) /* true */ +Belt.Set.Dict.subset(s2, s1, ~cmp=IntCmp.cmp) /* true */ +Belt.Set.Dict.subset(s1, s0, ~cmp=IntCmp.cmp) /* false */ +``` */ let subset: (t<'value, 'id>, t<'value, 'id>, ~cmp: cmp<'value, 'id>) => bool /** - Total ordering between sets. Can be used as the ordering function for doing sets of sets. It compares size first and then iterates over each element following the order of elements. +Total ordering between sets. Can be used as the ordering function for doing sets +of sets. It compares size first and then iterates over each element following the +order of elements. */ let cmp: (t<'value, 'id>, t<'value, 'id>, ~cmp: cmp<'value, 'id>) => int /** - Checks if two sets are equal. +Checks if two sets are equal. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([5, 2, 3], ~cmp=IntCmp.cmp) - let s1 = Belt.Set.Dict.fromArray([3, 2, 5], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([5, 2, 3], ~cmp=IntCmp.cmp) +let s1 = Belt.Set.Dict.fromArray([3, 2, 5], ~cmp=IntCmp.cmp) - Belt.Set.Dict.eq(s0, s1, ~cmp=IntCmp.cmp) /* true */ - ``` +Belt.Set.Dict.eq(s0, s1, ~cmp=IntCmp.cmp) /* true */ +``` */ let eq: (t<'value, 'id>, t<'value, 'id>, ~cmp: cmp<'value, 'id>) => bool /** - Same as [forEach](##forEach) but takes uncurried functon. +Same as [forEach](##forEach) but takes uncurried functon. */ let forEachU: (t<'value, 'id>, (. 'value) => unit) => unit /** - Applies function `f` in turn to all elements of set in increasing order. +Applies function `f` in turn to all elements of set in increasing order. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) - let acc = ref(list{}) - s0->Belt.Set.Dict.forEach(x => acc := Belt.List.add(acc.contents, x)) - acc /* [6,5,3,2] */ - ``` +let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) +let acc = ref(list{}) +s0->Belt.Set.Dict.forEach(x => acc := Belt.List.add(acc.contents, x)) +acc /* [6,5,3,2] */ +``` */ let forEach: (t<'value, 'id>, 'value => unit) => unit let reduceU: (t<'value, 'id>, 'a, (. 'a, 'value) => 'a) => 'a /** - Applies function `f` to each element of set in increasing order. Function `f` has two parameters: the item from the set and an “accumulator”, which starts with a value of `initialValue`. `reduce` returns the final value of the accumulator. +Applies function `f` to each element of set in increasing order. Function `f` has two parameters: the item from the set and an “accumulator”, which starts with a value of `initialValue`. `reduce` returns the final value of the accumulator. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.reduce(list{}, (acc, element) => acc->Belt.List.add(element)) /* [6,5,3,2] */ - ``` +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) + +let s0 = Belt.Set.Dict.fromArray([5, 2, 3, 5, 6], ~cmp=IntCmp.cmp) +s0->Belt.Set.Dict.reduce(list{}, (acc, element) => acc->Belt.List.add(element)) /* [6,5,3,2] */ +``` */ let reduce: (t<'value, 'id>, 'a, ('a, 'value) => 'a) => 'a let everyU: (t<'value, 'id>, (. 'value) => bool) => bool /** - Checks if all elements of the set satisfy the predicate. Order unspecified. +Checks if all elements of the set satisfy the predicate. Order unspecified. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let isEven = x => mod(x, 2) == 0 +let isEven = x => mod(x, 2) == 0 - let s0 = Belt.Set.Dict.fromArray([2, 4, 6, 8], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.every(isEven) /* true */ - ``` +let s0 = Belt.Set.Dict.fromArray([2, 4, 6, 8], ~cmp=IntCmp.cmp) +s0->Belt.Set.Dict.every(isEven) /* true */ +``` */ let every: (t<'value, 'id>, 'value => bool) => bool let someU: (t<'value, 'id>, (. 'value) => bool) => bool /** - Checks if at least one element of the set satisfies the predicate. +Checks if at least one element of the set satisfies the predicate. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let isOdd = x => mod(x, 2) != 0 +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([1, 2, 4, 6, 8], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.some(isOdd) /* true */ - ``` +let isOdd = x => mod(x, 2) != 0 + +let s0 = Belt.Set.Dict.fromArray([1, 2, 4, 6, 8], ~cmp=IntCmp.cmp) +s0->Belt.Set.Dict.some(isOdd) /* true */ +``` */ let some: (t<'value, 'id>, 'value => bool) => bool let keepU: (t<'value, 'id>, (. 'value) => bool) => t<'value, 'id> /** - Returns the set of all elements that satisfy the predicate. +Returns the set of all elements that satisfy the predicate. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let isEven = x => mod(x, 2) == 0 +let isEven = x => mod(x, 2) == 0 - let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) - let s1 = s0->Belt.Set.Dict.keep(isEven) +let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) +let s1 = s0->Belt.Set.Dict.keep(isEven) - s1->Belt.Set.Dict.toArray /* [2,4] */ - ``` +s1->Belt.Set.Dict.toArray /* [2,4] */ +``` */ let keep: (t<'value, 'id>, 'value => bool) => t<'value, 'id> let partitionU: (t<'value, 'id>, (. 'value) => bool) => (t<'value, 'id>, t<'value, 'id>) /** - Returns a pair of sets, where first is the set of all the elements of set that satisfy the predicate, and second is the set of all the elements of set that do not satisfy the predicate. +Returns a pair of sets, where first is the set of all the elements of set that satisfy the predicate, and second is the set of all the elements of set that do not satisfy the predicate. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let isOdd = x => mod(x, 2) != 0 +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) - let (s1, s2) = s0->Belt.Set.Dict.partition(isOdd) +let isOdd = x => mod(x, 2) != 0 - s1->Belt.Set.Dict.toArray /* [1,3,5] */ - s2->Belt.Set.Dict.toArray /* [2,4] */ - ``` +let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) +let (s1, s2) = s0->Belt.Set.Dict.partition(isOdd) + +s1->Belt.Set.Dict.toArray /* [1,3,5] */ +s2->Belt.Set.Dict.toArray /* [2,4] */ +``` */ let partition: (t<'value, 'id>, 'value => bool) => (t<'value, 'id>, t<'value, 'id>) /** - Returns size of the set. +Returns size of the set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.size /* 4 */ - ``` +s0->Belt.Set.Dict.size /* 4 */ +``` */ let size: t<'value, 'id> => int /** - Returns list of ordered set elements. +Returns list of ordered set elements. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.toList /* [1,2,3,5] */ - ``` +s0->Belt.Set.Dict.toList /* [1,2,3,5] */ +``` */ let toList: t<'value, 'id> => list<'value> /** - Returns array of ordered set elements. +Returns array of ordered set elements. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.Set.Dict.toArray /* [1,2,3,5] */ - ``` +let s0 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + +s0->Belt.Set.Dict.toArray /* [1,2,3,5] */ +``` */ let toArray: t<'value, 'id> => array<'value> /** - Returns minimum value of the collection. `None` if collection is empty. +Returns minimum value of the collection. `None` if collection is empty. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.empty - let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.empty +let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.minimum /* None */ - s1->Belt.Set.Dict.minimum /* Some(1) */ - ``` +s0->Belt.Set.Dict.minimum /* None */ +s1->Belt.Set.Dict.minimum /* Some(1) */ +``` */ let minimum: t<'value, 'id> => option<'value> /** - Returns minimum value of the collection. `undefined` if collection is empty. +Returns minimum value of the collection. `undefined` if collection is empty. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.empty - let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.Set.Dict.minUndefined /* undefined */ - s1->Belt.Set.Dict.minUndefined /* 1 */ - ``` +let s0 = Belt.Set.Dict.empty +let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + +s0->Belt.Set.Dict.minUndefined /* undefined */ +s1->Belt.Set.Dict.minUndefined /* 1 */ +``` */ let minUndefined: t<'value, 'id> => Js.undefined<'value> /** - Returns maximum value of the collection. `None` if collection is empty. +Returns maximum value of the collection. `None` if collection is empty. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.empty - let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.empty +let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.maximum /* None */ - s1->Belt.Set.Dict.maximum /* Some(5) */ - ``` +s0->Belt.Set.Dict.maximum /* None */ +s1->Belt.Set.Dict.maximum /* Some(5) */ +``` */ let maximum: t<'value, 'id> => option<'value> /** - Returns maximum value of the collection. `undefined` if collection is empty. +Returns maximum value of the collection. `undefined` if collection is empty. - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +## Examples - let s0 = Belt.Set.Dict.empty - let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - s0->Belt.Set.Dict.maxUndefined /* undefined */ - s1->Belt.Set.Dict.maxUndefined /* 5 */ - ``` +let s0 = Belt.Set.Dict.empty +let s1 = Belt.Set.Dict.fromArray([3, 2, 1, 5], ~cmp=IntCmp.cmp) + +s0->Belt.Set.Dict.maxUndefined /* undefined */ +s1->Belt.Set.Dict.maxUndefined /* 5 */ +``` */ let maxUndefined: t<'value, 'id> => Js.undefined<'value> /** - Returns the reference of the value which is equivalent to value using the comparator specifiecd by this collection. Returns `None` if element does not exist. +Returns the reference of the value which is equivalent to value using the comparator +specifiecd by this collection. Returns `None` if element does not exist. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) - s0->Belt.Set.Dict.get(3, ~cmp=IntCmp.cmp) /* Some(3) */ - s0->Belt.Set.Dict.get(20, ~cmp=IntCmp.cmp) /* None */ - ``` +s0->Belt.Set.Dict.get(3, ~cmp=IntCmp.cmp) /* Some(3) */ +s0->Belt.Set.Dict.get(20, ~cmp=IntCmp.cmp) /* None */ +``` */ let get: (t<'value, 'id>, 'value, ~cmp: cmp<'value, 'id>) => option<'value> /** - Same as [get](#get) but returns `undefined` when element does not exist. +Same as [get](#get) but returns `undefined` when element does not exist. */ let getUndefined: (t<'value, 'id>, 'value, ~cmp: cmp<'value, 'id>) => Js.undefined<'value> /** - Same as [get](#get) but raise when element does not exist. +Same as [get](#get) but raise when element does not exist. */ let getExn: (t<'value, 'id>, 'value, ~cmp: cmp<'value, 'id>) => 'value /** - Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. +Returns a tuple `((smaller, larger), present)`, `present` is true when element exist in set. + +## Examples - ```res example - module IntCmp = Belt.Id.MakeComparable({ - type t = int - let cmp = Pervasives.compare - }) +```rescript +module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare +}) - let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) +let s0 = Belt.Set.Dict.fromArray([1, 2, 3, 4, 5], ~cmp=IntCmp.cmp) - let ((smaller, larger), present) = s0->Belt.Set.Dict.split(3, ~cmp=IntCmp.cmp) +let ((smaller, larger), present) = s0->Belt.Set.Dict.split(3, ~cmp=IntCmp.cmp) - present /* true */ - smaller->Belt.Set.Dict.toArray /* [1,2] */ - larger->Belt.Set.Dict.toArray /* [4,5] */ - ``` +present /* true */ +smaller->Belt.Set.Dict.toArray /* [1,2] */ +larger->Belt.Set.Dict.toArray /* [4,5] */ +``` */ let split: ( t<'value, 'id>, @@ -566,6 +628,6 @@ let split: ( ) => ((t<'value, 'id>, t<'value, 'id>), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit diff --git a/jscomp/others/belt_SetInt.resi b/jscomp/others/belt_SetInt.resi index 8b67d2a0b2..2c5a60636d 100644 --- a/jscomp/others/belt_SetInt.resi +++ b/jscomp/others/belt_SetInt.resi @@ -23,11 +23,11 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.Set`]() specialized with value type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed, - and identity is not needed(using the built-in one) +This module is [`Belt.Set`]() specialized with value type to be a primitive type. +It is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.Set`]() +**See** [`Belt.Set`]() */ /** The type of the set elements. */ @@ -46,12 +46,16 @@ let isEmpty: t => bool let has: (t, value) => bool -/** `add s x` If `x` was already in `s`, `s` is returned unchanged. */ +/** +`add(s, x)` if `x` was already in `s`, `s` is returned unchanged. +*/ let add: (t, value) => t let mergeMany: (t, array) => t -/** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. */ +/** +`remove(m, x)` if `x` was not in `m`, `m` is returned reference unchanged. +*/ let remove: (t, value) => t let removeMany: (t, array) => t @@ -62,22 +66,28 @@ let intersect: (t, t) => t let diff: (t, t) => t -/** `subset s1 s2` tests whether the set `s1` is a subset of - the set `s2`. */ +/** +`subset(s1, s2)` tests whether the set `s1` is a subset of the set `s2`. +*/ let subset: (t, t) => bool -/** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. */ +/** +Total ordering between sets. Can be used as the ordering function for doing sets +of sets. +*/ let cmp: (t, t) => int -/** `eq s1 s2` tests whether the sets `s1` and `s2` are - equal, that is, contain equal elements. */ +/** +`eq(s1, s2)` tests whether the sets `s1` and `s2` are equal, that is, contain +equal elements. +*/ let eq: (t, t) => bool let forEachU: (t, (. value) => unit) => unit -/** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order */ +/** +`forEach(s, f)` applies `f` in turn to all elements of `s`. In increasing order +*/ let forEach: (t, value => unit) => unit let reduceU: (t, 'a, (. 'a, value) => 'a) => 'a @@ -87,29 +97,33 @@ let reduce: (t, 'a, ('a, value) => 'a) => 'a let everyU: (t, (. value) => bool) => bool -/** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. */ +/** +`every(p, s)` checks if all elements of the set satisfy the predicate `p`. Order +unspecified. +*/ let every: (t, value => bool) => bool let someU: (t, (. value) => bool) => bool -/** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. */ +/** +`some(p, s)` checks if at least one element of the set satisfies the predicate +`p`. Oder unspecified. +*/ let some: (t, value => bool) => bool let keepU: (t, (. value) => bool) => t -/** `keep p s` returns the set of all elements in `s` - that satisfy predicate `p`. */ +/** +`keep(p, s)` returns the set of all elements in `s` that satisfy predicate `p`. +*/ let keep: (t, value => bool) => t let partitionU: (t, (. value) => bool) => (t, t) /** - `partition p s` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. +`partition(p, s)` returns a pair of sets `(s1, s2)`, where `s1` is the set of +all the elements of `s` that satisfy the predicate `p`, and `s2` is the set of +all the elements of `s` that do not satisfy `p`. */ let partition: (t, value => bool) => (t, t) @@ -135,17 +149,17 @@ let getUndefined: (t, value) => Js.undefined let getExn: (t, value) => value /** - `split x s` returns a triple `(l, present, r)`, where - `l` is the set of elements of `s` that are - strictly less than `x`; - `r` is the set of elements of `s` that are - strictly greater than `x`; - `present` is `false` if `s` contains no element equal to `x`, - or `true` if `s` contains an element equal to `x`. +`split(x, s)` returns a triple `(l, present, r)`, where +`l` is the set of elements of `s` that are +strictly less than `x`; +`r` is the set of elements of `s` that are +strictly greater than `x`; +`present` is `false` if `s` contains no element equal to `x`, +or `true` if `s` contains an element equal to `x`. */ let split: (t, value) => ((t, t), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t => unit diff --git a/jscomp/others/belt_SetString.resi b/jscomp/others/belt_SetString.resi index 26dfddc043..c8d1843a57 100644 --- a/jscomp/others/belt_SetString.resi +++ b/jscomp/others/belt_SetString.resi @@ -23,11 +23,11 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.Set`]() specialized with value type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed, - and identity is not needed(using the built-in one) +This module is [`Belt.Set`]() specialized with value type to be a primitive type. +It is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.Set`]() +**See** [`Belt.Set`]() */ /** The type of the set elements. */ @@ -46,12 +46,16 @@ let isEmpty: t => bool let has: (t, value) => bool -/** `add s x` If `x` was already in `s`, `s` is returned unchanged. */ +/** +`add(s, x)` If `x` was already in `s`, `s` is returned unchanged. +*/ let add: (t, value) => t let mergeMany: (t, array) => t -/** `remove m x` If `x` was not in `m`, `m` is returned reference unchanged. */ +/** +`remove(m, x)` If `x` was not in `m`, `m` is returned reference unchanged. +*/ let remove: (t, value) => t let removeMany: (t, array) => t @@ -62,22 +66,28 @@ let intersect: (t, t) => t let diff: (t, t) => t -/** `subset s1 s2` tests whether the set `s1` is a subset of - the set `s2`. */ +/** +`subset(s1, s2)` tests whether the set `s1` is a subset of the set `s2`. +*/ let subset: (t, t) => bool -/** Total ordering between sets. Can be used as the ordering function - for doing sets of sets. */ +/** +Total ordering between sets. Can be used as the ordering function for doing sets +of sets. +*/ let cmp: (t, t) => int -/** `eq s1 s2` tests whether the sets `s1` and `s2` are - equal, that is, contain equal elements. */ +/** +`eq(s1, s2)` tests whether the sets `s1` and `s2` are equal, that is, contain +equal elements. +*/ let eq: (t, t) => bool let forEachU: (t, (. value) => unit) => unit -/** `forEach s f` applies `f` in turn to all elements of `s`. - In increasing order */ +/** +`forEach(s, f)` applies `f` in turn to all elements of `s`. In increasing order +*/ let forEach: (t, value => unit) => unit let reduceU: (t, 'a, (. 'a, value) => 'a) => 'a @@ -87,29 +97,34 @@ let reduce: (t, 'a, ('a, value) => 'a) => 'a let everyU: (t, (. value) => bool) => bool -/** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. */ +/** +`every(p, s)` checks if all elements of the set satisfy the predicate `p`. +Order unspecified. +*/ let every: (t, value => bool) => bool let someU: (t, (. value) => bool) => bool -/** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. */ +/** +`some(p, s)` checks if at least one element of the set satisfies the predicate +`p`. Oder unspecified. +*/ let some: (t, value => bool) => bool let keepU: (t, (. value) => bool) => t -/** `keep p s` returns the set of all elements in `s` - that satisfy predicate `p`. */ +/** +`keep(p, s)` returns the set of all elements in `s` that satisfy predicate `p`. +*/ let keep: (t, value => bool) => t let partitionU: (t, (. value) => bool) => (t, t) /** - `partition p s` returns a pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. +`partition(p, s)` returns a pair of sets `(s1, s2)`, where +`s1` is the set of all the elements of `s` that satisfy the +predicate `p`, and `s2` is the set of all the elements of +`s` that do not satisfy `p`. */ let partition: (t, value => bool) => (t, t) @@ -135,17 +150,17 @@ let getUndefined: (t, value) => Js.undefined let getExn: (t, value) => value /** - `split x s` returns a triple `(l, present, r)`, where - `l` is the set of elements of `s` that are - strictly less than `x`; - `r` is the set of elements of `s` that are - strictly greater than `x`; - `present` is `false` if `s` contains no element equal to `x`, - or `true` if `s` contains an element equal to `x`. +`split(x, s)` returns a triple `(l, present, r)`, where +`l` is the set of elements of `s` that are +strictly less than `x`; +`r` is the set of elements of `s` that are +strictly greater than `x`; +`present` is `false` if `s` contains no element equal to `x`, +or `true` if `s` contains an element equal to `x`. */ let split: (t, value) => ((t, t), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t => unit diff --git a/jscomp/others/belt_SortArray.resi b/jscomp/others/belt_SortArray.resi index dd597467c1..ced18fc335 100644 --- a/jscomp/others/belt_SortArray.resi +++ b/jscomp/others/belt_SortArray.resi @@ -22,36 +22,42 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** A module for Array sort relevant utiliites */ +/*** +A module for Array sort relevant utiliites +*/ -/** Specalized when key type is `int`, more efficient - than the generic type */ +/** +Specalized when key type is `int`, more efficient than the generic type +*/ module Int = Belt_SortArrayInt -/** Specalized when key type is `string`, more efficient - than the generic type */ +/** +Specalized when key type is `string`, more efficient than the generic type +*/ module String = Belt_SortArrayString let strictlySortedLengthU: (array<'a>, (. 'a, 'a) => bool) => int /** - `strictlySortedLenght(xs, cmp);` return `+n` means increasing order `-n` means negative order +`strictlySortedLenght(xs, cmp);` return `+n` means increasing order `-n` means negative order + +## Examples - ```res example - Belt.SortArray.strictlySortedLength([1, 2, 3, 4, 3], (x, y) => x < y) == 4 +```rescript +Belt.SortArray.strictlySortedLength([1, 2, 3, 4, 3], (x, y) => x < y) == 4 - Belt.SortArray.strictlySortedLength([], (x, y) => x < y) == 0 +Belt.SortArray.strictlySortedLength([], (x, y) => x < y) == 0 - Belt.SortArray.strictlySortedLength([1], (x, y) => x < y) == 1 +Belt.SortArray.strictlySortedLength([1], (x, y) => x < y) == 1 - Belt.SortArray.strictlySortedLength([4, 3, 2, 1], (x, y) => x < y) == -4 - ``` +Belt.SortArray.strictlySortedLength([4, 3, 2, 1], (x, y) => x < y) == -4 +``` */ let strictlySortedLength: (array<'a>, ('a, 'a) => bool) => int let isSortedU: (array<'a>, (. 'a, 'a) => int) => bool /** - `isSorted(arr, cmp)`: Returns true if array is increasingly sorted (equal is okay) +`isSorted(arr, cmp)`: Returns true if array is increasingly sorted (equal is okay) */ let isSorted: (array<'a>, ('a, 'a) => int) => bool @@ -60,47 +66,48 @@ let stableSortInPlaceBy: (array<'a>, ('a, 'a) => int) => unit let stableSortByU: (array<'a>, (. 'a, 'a) => int) => array<'a> /** - `stableSortBy(xs, cmp)`: Returns a fresh array Sort `xs` in place using - comparator `cmp`, the stable means if the elements are equal, their order will - be preserved +`stableSortBy(xs, cmp)`: Returns a fresh array Sort `xs` in place using +comparator `cmp`, the stable means if the elements are equal, their order will +be preserved */ let stableSortBy: (array<'a>, ('a, 'a) => int) => array<'a> let binarySearchByU: (array<'a>, 'a, (. 'a, 'a) => int) => int /** - If value is not found and value is less than one or more elements in array, the - negative number returned is the bitwise complement of the index of the first - element that is larger than value. +If value is not found and value is less than one or more elements in array, the +negative number returned is the bitwise complement of the index of the first +element that is larger than value. + +If value is not found and value is greater +than all elements in array, the negative number returned is the bitwise +complement of (the index of the last element plus 1)for example, if `key` is +smaller than all elements return `-1` since `lnot(-1) == 0` if `key` is larger +than all elements return `lnot(-1) == 0` since `lnot(- (len + 1)) == len` - If value is not found and value is greater - than all elements in array, the negative number returned is the bitwise - complement of (the index of the last element plus 1)for example, if `key` is - smaller than all elements return `-1` since `lnot(-1) == 0` if `key` is larger - than all elements return `lnot(-1) == 0` since `lnot(- (len + 1)) == len` +## Examples - ```res example - Belt.SortArray.binarySearchBy([1, 2, 3, 4, 33, 35, 36], 33, Pervasives.compare) == 4 +```rescript +Belt.SortArray.binarySearchBy([1, 2, 3, 4, 33, 35, 36], 33, Pervasives.compare) == 4 - lnot(Belt.SortArray.binarySearchBy([1, 3, 5, 7], 4, Pervasives.compare)) == 2 - ``` +lnot(Belt.SortArray.binarySearchBy([1, 3, 5, 7], 4, Pervasives.compare)) == 2 +``` */ let binarySearchBy: (array<'a>, 'a, ('a, 'a) => int) => int let unionU: (array<'a>, int, int, array<'a>, int, int, array<'a>, int, (. 'a, 'a) => int) => int /** - `union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` - assume `src` and `src2` is strictly sorted. - for equivalent elements, it is picked from `src` - also assume that `dst` is large enough to store all elements +`union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` assume `src` and +`src2` is strictly sorted. for equivalent elements, it is picked from `src` +also assume that `dst` is large enough to store all elements */ let union: (array<'a>, int, int, array<'a>, int, int, array<'a>, int, ('a, 'a) => int) => int let intersectU: (array<'a>, int, int, array<'a>, int, int, array<'a>, int, (. 'a, 'a) => int) => int /** - `union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` +`union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` - **return** the `offset` in the output array +**return** the `offset` in the output array */ let intersect: (array<'a>, int, int, array<'a>, int, int, array<'a>, int, ('a, 'a) => int) => int diff --git a/jscomp/others/belt_SortArrayInt.resi b/jscomp/others/belt_SortArrayInt.resi index 397655800b..ce1c48c6f1 100644 --- a/jscomp/others/belt_SortArrayInt.resi +++ b/jscomp/others/belt_SortArrayInt.resi @@ -22,49 +22,51 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** This is a specialized module for [`Belt_SortArray`](), the docs in that module also - applies here, except the comparator is fixed and inlined +/*** +This is a specialized module for [`Belt_SortArray`](), the docs in that module also +applies here, except the comparator is fixed and inlined */ type element = int /** - The same as [`Belt_SortArray.strictlySortedLength`]() except the comparator is fixed +The same as [`Belt_SortArray.strictlySortedLength`]() except the comparator is fixed - **return** `+n` means increasing order `-n` means negative order +**return** `+n` means increasing order `-n` means negative order */ let strictlySortedLength: array => int -/** `sorted xs` return true if `xs` is in non strict increasing order */ +/** `sorted(xs)` return true if `xs` is in non strict increasing order */ let isSorted: array => bool /** - The same as [`Belt_SortArray.stableSortInPlaceBy`]() except the comparator is fixed +The same as [`Belt_SortArray.stableSortInPlaceBy`]() except the comparator is fixed */ let stableSortInPlace: array => unit -/** The same as [`Belt_SortArray.stableSortBy`]() except the comparator is fixed */ +/** +The same as [`Belt_SortArray.stableSortBy`]() except the comparator is fixed +*/ let stableSort: array => array /** - If value is not found and value is less than one or more elements in array, - the negative number returned is the bitwise complement of the index of the first element - that is larger than value. +If value is not found and value is less than one or more elements in array, +the negative number returned is the bitwise complement of the index of the first element +that is larger than value. - If value is not found and value is greater than all elements in array, - the negative number returned is the bitwise complement of - (the index of the last element plus 1) +If value is not found and value is greater than all elements in array, +the negative number returned is the bitwise complement of +(the index of the last element plus 1) - for example, if `key` is smaller than all elements return `-1` since `lnot (-1) = 0` - if `key` is larger than all elements return `- (len + 1)` since `lnot (-(len+1)) = len` +for example, if `key` is smaller than all elements return `-1` since `lnot (-1) = 0` +if `key` is larger than all elements return `- (len + 1)` since `lnot (-(len+1)) = len` */ let binarySearch: (array, element) => int /** - `union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` - assume `src` and `src2` is strictly sorted. - for equivalent elements, it is picked from `src` - also assume that `dst` is large enough to store all elements +`union(src, src1ofs, src1len, src2, src2ofs, src2len, dst, dstofs, cmp)` assume +`src` and `src2` is strictly sorted. for equivalent elements, it is picked from +`src` also assume that `dst` is large enough to store all elements */ let union: (array, int, int, array, int, int, array, int) => int diff --git a/jscomp/others/belt_SortArrayString.resi b/jscomp/others/belt_SortArrayString.resi index b33e2dc382..3742ce2229 100644 --- a/jscomp/others/belt_SortArrayString.resi +++ b/jscomp/others/belt_SortArrayString.resi @@ -22,49 +22,51 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** This is a specialized module for [`Belt_SortArray`](), the docs in that module also - applies here, except the comparator is fixed and inlined +/*** +This is a specialized module for [`Belt_SortArray`](), the docs in that module also +applies here, except the comparator is fixed and inlined */ type element = string /** - The same as [`Belt_SortArray.strictlySortedLength`]() except the comparator is fixed +The same as [`Belt_SortArray.strictlySortedLength`]() except the comparator is fixed - **return** `+n` means increasing order `-n` means negative order +**return** `+n` means increasing order `-n` means negative order */ let strictlySortedLength: array => int -/** `sorted xs` return true if `xs` is in non strict increasing order */ +/** `sorted(xs)` return true if `xs` is in non strict increasing order */ let isSorted: array => bool /** - The same as [`Belt_SortArray.stableSortInPlaceBy`]() except the comparator is fixed +The same as [`Belt_SortArray.stableSortInPlaceBy`]() except the comparator is fixed */ let stableSortInPlace: array => unit -/** The same as [`Belt_SortArray.stableSortBy`]() except the comparator is fixed */ +/** +The same as [`Belt_SortArray.stableSortBy`]() except the comparator is fixed +*/ let stableSort: array => array /** - If value is not found and value is less than one or more elements in array, - the negative number returned is the bitwise complement of the index of the first element - that is larger than value. +If value is not found and value is less than one or more elements in array, +the negative number returned is the bitwise complement of the index of the first element +that is larger than value. - If value is not found and value is greater than all elements in array, - the negative number returned is the bitwise complement of - (the index of the last element plus 1) +If value is not found and value is greater than all elements in array, +the negative number returned is the bitwise complement of +(the index of the last element plus 1) - for example, if `key` is smaller than all elements return `-1` since `lnot (-1) = 0` - if `key` is larger than all elements return `- (len + 1)` since `lnot (-(len+1)) = len` +for example, if `key` is smaller than all elements return `-1` since `lnot (-1) = 0` +if `key` is larger than all elements return `- (len + 1)` since `lnot (-(len+1)) = len` */ let binarySearch: (array, element) => int /** - `union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` - assume `src` and `src2` is strictly sorted. - for equivalent elements, it is picked from `src` - also assume that `dst` is large enough to store all elements +`union(src, src1ofs, src1len, src2, src2ofs, src2len, dst, dstofs, cmp)` assume +`src` and `src2` is strictly sorted. for equivalent elements, it is picked from +`src` also assume that `dst` is large enough to store all elements */ let union: (array, int, int, array, int, int, array, int) => int diff --git a/jscomp/others/belt_internalAVLset.resi b/jscomp/others/belt_internalAVLset.resi index 5621f8cf48..0f7ccf5e03 100644 --- a/jscomp/others/belt_internalAVLset.resi +++ b/jscomp/others/belt_internalAVLset.resi @@ -23,10 +23,9 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /* - This internal module - contains methods which does not rely on ordering. - Such methods could be shared between - `generic set/specalized set` whether mutable or immutable depends on use cases +This internal module contains methods which does not rely on ordering. +Such methods could be shared between `generic set/specalized set` whether mutable +or immutable depends on use cases */ type rec t<'value> = option> and node<'value> = { @@ -89,7 +88,7 @@ let size: t<'a> => int let toList: t<'a> => list<'a> /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit @@ -111,7 +110,7 @@ let fromArray: (array<'a>, ~cmp: cmp<'a, 'b>) => t<'a> let addMutate: (~cmp: cmp<'a, 'b>, t<'a>, 'a) => t<'a> let balMutate: node<'a> => node<'a> /** - `removeMinAuxWithRootMutate root n` - remove the minimum of n in place and store its value in the `key root` +`removeMinAuxWithRootMutate(root, n)` remove the minimum of n in place and store +its value in the `key root` */ let removeMinAuxWithRootMutate: (node<'a>, node<'a>) => t<'a> diff --git a/jscomp/others/belt_internalAVLtree.resi b/jscomp/others/belt_internalAVLtree.resi index 0f0c0883d8..a1b58f3c3e 100644 --- a/jscomp/others/belt_internalAVLtree.resi +++ b/jscomp/others/belt_internalAVLtree.resi @@ -102,7 +102,7 @@ let size: t<'a, 'b> => int let toList: t<'a, 'b> => list<('a, 'b)> /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<'a, 'b> => unit diff --git a/jscomp/others/hashmap.cppo.resi b/jscomp/others/hashmap.cppo.resi index e1487c4fe1..a6ce4e6497 100644 --- a/jscomp/others/hashmap.cppo.resi +++ b/jscomp/others/hashmap.cppo.resi @@ -15,9 +15,8 @@ let clear: t<'b> => unit let isEmpty: t<_> => bool /** - `setDone tbl k v` if `k` does not exist, - add the binding `k,v`, otherwise, update the old value with the new - `v` +`setDone(tbl, k, v)` if `k` does not exist, add the binding `k,v`, otherwise, +update the old value with the new `v` */ let set: (t<'a>, key, 'a) => unit diff --git a/jscomp/others/js.ml b/jscomp/others/js.ml index 1b2fc5c17d..7c41df8859 100644 --- a/jscomp/others/js.ml +++ b/jscomp/others/js.ml @@ -31,44 +31,46 @@ *) (** - The Js module mostly contains ReScript bindings to _standard JavaScript APIs_ - like [console.log](https://developer.mozilla.org/en-US/docs/Web/API/Console/log), - or the JavaScript - [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), - [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), and - [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - classes. +The Js module mostly contains ReScript bindings to _standard JavaScript APIs_ +like [console.log](https://developer.mozilla.org/en-US/docs/Web/API/Console/log), +or the JavaScript +[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), +[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), and +[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) +classes. - It is meant as a zero-abstraction interop layer and directly exposes JavaScript functions as they are. If you can find your API in this module, prefer this over an equivalent Belt helper. For example, prefer [Js.Array2](js/array-2) over [Belt.Array](belt/array) +It is meant as a zero-abstraction interop layer and directly exposes JavaScript functions as they are. If you can find your API in this module, prefer this over an equivalent Belt helper. For example, prefer [Js.Array2](js/array2) over [Belt.Array](belt/array) - ## Argument Order +## Argument Order - For historical reasons, some APIs in the Js namespace (e.g. [Js.String](js/string)) are - using the data-last argument order whereas others (e.g. [Js.Date](js/date)) are using data-first. +For historical reasons, some APIs in the Js namespace (e.g. [Js.String](js/string)) are +using the data-last argument order whereas others (e.g. [Js.Date](js/date)) are using data-first. - For more information about these argument orders and the trade-offs between them, see - [this blog post](https://www.javierchavarri.com/data-first-and-data-last-a-comparison/). +For more information about these argument orders and the trade-offs between them, see +[this blog post](https://www.javierchavarri.com/data-first-and-data-last-a-comparison/). - _Eventually, all modules in the Js namespace are going to be migrated to data-first though._ +_Eventually, all modules in the Js namespace are going to be migrated to data-first though._ - In the meantime, there are several options for dealing with the data-last APIs: +In the meantime, there are several options for dealing with the data-last APIs: - ```res example - /* Js.String (data-last API used with pipe last operator) */ - Js.log("2019-11-10" |> Js.String.split("-")) - Js.log("ReScript" |> Js.String.startsWith("Re")) +## Examples - /* Js.String (data-last API used with pipe first operator) */ - Js.log("2019-11-10"->Js.String.split("-", _)) - Js.log("ReScript"->Js.String.startsWith("Re", _)) +```rescript +/* Js.String (data-last API used with pipe last operator) */ +Js.log("2019-11-10" |> Js.String.split("-")) +Js.log("ReScript" |> Js.String.startsWith("Re")) - /* Js.String (data-last API used without any piping) */ - Js.log(Js.String.split("-", "2019-11-10")) - Js.log(Js.String.startsWith("Re", "ReScript")) - ``` - ## Js.Xxx2 Modules +/* Js.String (data-last API used with pipe first operator) */ +Js.log("2019-11-10"->Js.String.split("-", _)) +Js.log("ReScript"->Js.String.startsWith("Re", _)) - Prefer `Js.Array2` over `Js.Array`, `Js.String2` over `Js.String`, etc. The latters are old modules. +/* Js.String (data-last API used without any piping) */ +Js.log(Js.String.split("-", "2019-11-10")) +Js.log(Js.String.startsWith("Re", "ReScript")) +``` +## Js.Xxx2 Modules + +Prefer `Js.Array2` over `Js.Array`, `Js.String2` over `Js.String`, etc. The latters are old modules. *) type 'a t = < .. > as 'a @@ -123,7 +125,6 @@ external testAny : 'a -> bool = "#is_nullable" type (+'a, +'e) promise (** The promise type, defined here for interoperation across packages. - @deprecated please use `Js.Promise`. *) external null : 'a null = "#null" @@ -171,7 +172,7 @@ external unsafe_lt : 'a -> 'a -> bool = "#unsafe_lt" external unsafe_le : 'a -> 'a -> bool = "#unsafe_le" (** - `unsafe_le(a, b) will be compiled as `a <= b`. + `unsafe_le(a, b)` will be compiled as `a <= b`. See also `Js.unsafe_lt`. *) @@ -199,7 +200,7 @@ module Nullable = Js_null_undefined (** Provide utilities for `Js.null_undefined` *) module Null_undefined = Js_null_undefined -(** @deprecated please use `Js.Nullable` *) +[@deprecated "Please use `Js.Nullable`"] module Exn = Js_exn (** Provide utilities for dealing with Js exceptions *) diff --git a/jscomp/others/js_array.res b/jscomp/others/js_array.res index ca2f69ab9b..caf332fdc4 100644 --- a/jscomp/others/js_array.res +++ b/jscomp/others/js_array.res @@ -23,43 +23,45 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Provides bindings to JavaScript’s `Array` functions. These bindings are - optimized for pipe-last (`|>`), where the array to be processed is the last - parameter in the function. - - Here is an example to find the sum of squares of all even numbers in an array. - Without pipe last, we must call the functions in reverse order: - - ```res example - let isEven = x => mod(x, 2) == 0 - let square = x => x * x - let result = { - open Js.Array - reduce(\"+", 0, map(square, filter(isEven, [5, 2, 3, 4, 1]))) - } - ``` +Provides bindings to JavaScript’s `Array` functions. These bindings are +optimized for pipe-last (`|>`), where the array to be processed is the last +parameter in the function. - With pipe last, we call the functions in the “natural” order: +Here is an example to find the sum of squares of all even numbers in an array. +Without pipe last, we must call the functions in reverse order: - ```res example - let isEven = x => mod(x, 2) == 0 - let square = x => x * x - let result = { - open Js.Array - [5, 2, 3, 4, 1] |> filter(isEven) |> map(square) |> reduce("+", 0) - } - ``` +## Examples + +```rescript +let isEven = x => mod(x, 2) == 0 +let square = x => x * x +let result = { + open Js.Array + reduce(\"+", 0, map(square, filter(isEven, [5, 2, 3, 4, 1]))) +} +``` + +With pipe last, we call the functions in the “natural” order: + +```rescript +let isEven = x => mod(x, 2) == 0 +let square = x => x * x +let result = { + open Js.Array + [5, 2, 3, 4, 1] |> filter(isEven) |> map(square) |> reduce("+", 0) +} +``` */ @@warning("-103") /** - The type used to describe a JavaScript array. +The type used to describe a JavaScript array. */ type t<'a> = array<'a> /** - A type used to describe JavaScript objects that are like an array or are iterable. +A type used to describe JavaScript objects that are like an array or are iterable. */ type array_like<'a> = Js_array2.array_like<'a> @@ -69,12 +71,14 @@ type array_like<'a> = Js_array2.array_like<'a> @val /** - Creates a shallow copy of an array from an array-like object. See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN. +Creates a shallow copy of an array from an array-like object. See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN. + +## Examples - ```res example - let strArr = Js.String.castToArrayLike("abcd") - Js.Array.from(strArr) == ["a", "b", "c", "d"] - ``` +```rescript +let strArr = Js.String.castToArrayLike("abcd") +Js.Array.from(strArr) == ["a", "b", "c", "d"] +``` */ external from: array_like<'a> => array<'a> = "Array.from" @@ -82,16 +86,18 @@ external from: array_like<'a> => array<'a> = "Array.from" @val /** - Creates a new array by applying a function (the second argument) to each item - in the `array_like` first argument. See - [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) - on MDN. +Creates a new array by applying a function (the second argument) to each item +in the `array_like` first argument. See +[`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) +on MDN. - ```res example - let strArr = Js.String.castToArrayLike("abcd") - let code = s => Js.String.charCodeAt(0, s) - Js.Array.fromMap(strArr, code) == [97.0, 98.0, 99.0, 100.0] - ``` +## Examples + +```rescript +let strArr = Js.String.castToArrayLike("abcd") +let code = s => Js.String.charCodeAt(0, s) +Js.Array.fromMap(strArr, code) == [97.0, 98.0, 99.0, 100.0] +``` */ external fromMap: (array_like<'a>, @uncurry ('a => 'b)) => array<'b> = "Array.from" @@ -100,20 +106,22 @@ external fromMap: (array_like<'a>, @uncurry ('a => 'b)) => array<'b> = "Array.fr @val external isArray: 'a => bool = "Array.isArray" /* ES2015 */ /* - Returns `true` if its argument is an array; `false` otherwise. This is a - runtime check, which is why the second example returns `true` — a list is - internally represented as a nested JavaScript array. +Returns `true` if its argument is an array; `false` otherwise. This is a +runtime check, which is why the second example returns `true` — a list is +internally represented as a nested JavaScript array. - ```res example - Js.Array.isArray([5, 2, 3, 1, 4]) == true - Js.Array.isArray(list{5, 2, 3, 1, 4}) == true - Js.Array.isArray("abcd") == false - ``` +## Examples + +```rescript +Js.Array.isArray([5, 2, 3, 1, 4]) == true +Js.Array.isArray(list{5, 2, 3, 1, 4}) == true +Js.Array.isArray("abcd") == false +``` */ @get /** - Returns the number of elements in the array. See [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) on MDN. +Returns the number of elements in the array. See [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) on MDN. */ external length: array<'a> => int = "length" @@ -121,13 +129,15 @@ external length: array<'a> => int = "length" @bs.send.pipe(: t<'a> as 'this) /** - Copies from the first element in the given array to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. +Copies from the first element in the given array to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.copyWithin(~to_=2, arr) == [100, 101, 100, 101, 102] - arr == [100, 101, 100, 101, 102] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.copyWithin(~to_=2, arr) == [100, 101, 100, 101, 102] +arr == [100, 101, 100, 101, 102] +``` */ external copyWithin: (~to_: int) => 'this = "copyWithin" @@ -135,13 +145,15 @@ external copyWithin: (~to_: int) => 'this = "copyWithin" @bs.send.pipe(: t<'a> as 'this) /** - Copies starting at element `~from` in the given array to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. +Copies starting at element `~from` in the given array to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.copyWithinFrom(~from=2, ~to_=0, arr) == [102, 103, 104, 103, 104] - arr == [102, 103, 104, 103, 104] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.copyWithinFrom(~from=2, ~to_=0, arr) == [102, 103, 104, 103, 104] +arr == [102, 103, 104, 103, 104] +``` */ external copyWithinFrom: (~to_: int, ~from: int) => 'this = "copyWithin" @@ -149,13 +161,15 @@ external copyWithinFrom: (~to_: int, ~from: int) => 'this = "copyWithin" @bs.send.pipe(: t<'a> as 'this) /** - Copies starting at element `~start` in the given array up to but not including `~end_` to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. +Copies starting at element `~start` in the given array up to but not including `~end_` to the designated `~to_` position, returning the resulting array. *This function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104, 105] - Js.Array.copyWithinFromRange(~start=2, ~end_=5, ~to_=1, arr) == [100, 102, 103, 104, 104, 105] - arr == [100, 102, 103, 104, 104, 105] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104, 105] +Js.Array.copyWithinFromRange(~start=2, ~end_=5, ~to_=1, arr) == [100, 102, 103, 104, 104, 105] +arr == [100, 102, 103, 104, 104, 105] +``` */ external copyWithinFromRange: (~to_: int, ~start: int, ~end_: int) => 'this = "copyWithin" @@ -163,13 +177,15 @@ external copyWithinFromRange: (~to_: int, ~start: int, ~end_: int) => 'this = "c @bs.send.pipe(: t<'a> as 'this) /** - Sets all elements of the given array (the second arumgent) to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. +Sets all elements of the given array (the second arumgent) to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.fillInPlace(99, arr) == [99, 99, 99, 99, 99] - arr == [99, 99, 99, 99, 99] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.fillInPlace(99, arr) == [99, 99, 99, 99, 99] +arr == [99, 99, 99, 99, 99] +``` */ external fillInPlace: 'a => 'this = "fill" @@ -177,13 +193,15 @@ external fillInPlace: 'a => 'this = "fill" @bs.send.pipe(: t<'a> as 'this) /** - Sets all elements of the given array (the last arumgent) from position `~from` to the end to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. +Sets all elements of the given array (the last arumgent) from position `~from` to the end to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.fillFromInPlace(99, ~from=2, arr) == [100, 101, 99, 99, 99] - arr == [100, 101, 99, 99, 99] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.fillFromInPlace(99, ~from=2, arr) == [100, 101, 99, 99, 99] +arr == [100, 101, 99, 99, 99] +``` */ external fillFromInPlace: ('a, ~from: int) => 'this = "fill" @@ -191,13 +209,15 @@ external fillFromInPlace: ('a, ~from: int) => 'this = "fill" @bs.send.pipe(: t<'a> as 'this) /** - Sets the elements of the given array (the last arumgent) from position `~start` up to but not including position `~end_` to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. +Sets the elements of the given array (the last arumgent) from position `~start` up to but not including position `~end_` to the designated value (the first argument), returning the resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.fillRangeInPlace(99, ~start=1, ~end_=4, arr) == [100, 99, 99, 99, 104] - arr == [100, 99, 99, 99, 104] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.fillRangeInPlace(99, ~start=1, ~end_=4, arr) == [100, 99, 99, 99, 104] +arr == [100, 99, 99, 99, 104] +``` */ external fillRangeInPlace: ('a, ~start: int, ~end_: int) => 'this = "fill" @@ -206,201 +226,225 @@ external fillRangeInPlace: ('a, ~start: int, ~end_: int) => 'this = "fill" @bs.send.pipe(: t<'a> as 'this) @return(undefined_to_opt) /** - If the array is not empty, removes the last element and returns it as `Some(value)`; returns `None` if the array is empty. *This function modifies the original array.* See [`Array.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) on MDN. +If the array is not empty, removes the last element and returns it as `Some(value)`; returns `None` if the array is empty. *This function modifies the original array.* See [`Array.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.pop(arr) == Some(104) - arr == [100, 101, 102, 103] +## Examples - let empty: array = [] - Js.Array.pop(empty) == None - ``` +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.pop(arr) == Some(104) +arr == [100, 101, 102, 103] + +let empty: array = [] +Js.Array.pop(empty) == None +``` */ external pop: option<'a> = "pop" @bs.send.pipe(: t<'a> as 'this) /** - Appends the given value to the array, returning the number of elements in the updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. +Appends the given value to the array, returning the number of elements in the updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. - ```res example - let arr = ["ant", "bee", "cat"] - Js.Array.push("dog", arr) == 4 - arr == ["ant", "bee", "cat", "dog"] - ``` +## Examples + +```rescript +let arr = ["ant", "bee", "cat"] +Js.Array.push("dog", arr) == 4 +arr == ["ant", "bee", "cat", "dog"] +``` */ external push: 'a => int = "push" @bs.send.pipe(: t<'a> as 'this) @variadic /** - Appends the values from one array (the first argument) to another (the second argument), returning the number of elements in the updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. +Appends the values from one array (the first argument) to another (the second argument), returning the number of elements in the updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. - ```res example - let arr = ["ant", "bee", "cat"] - Js.Array.pushMany(["dog", "elk"], arr) == 5 - arr == ["ant", "bee", "cat", "dog", "elk"] - ``` +## Examples + +```rescript +let arr = ["ant", "bee", "cat"] +Js.Array.pushMany(["dog", "elk"], arr) == 5 +arr == ["ant", "bee", "cat", "dog", "elk"] +``` */ external pushMany: array<'a> => int = "push" @bs.send.pipe(: t<'a> as 'this) /** - Returns an array with the elements of the input array in reverse order. *This function modifies the original array.* See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN. +Returns an array with the elements of the input array in reverse order. *This function modifies the original array.* See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN. - ```res example - let arr = ["ant", "bee", "cat"] - Js.Array.reverseInPlace(arr) == ["cat", "bee", "ant"] - arr == ["cat", "bee", "ant"] - ``` +## Examples + +```rescript +let arr = ["ant", "bee", "cat"] +Js.Array.reverseInPlace(arr) == ["cat", "bee", "ant"] +arr == ["cat", "bee", "ant"] +``` */ external reverseInPlace: 'this = "reverse" @bs.send.pipe(: t<'a> as 'this) @return({undefined_to_opt: undefined_to_opt}) /** - If the array is not empty, removes the first element and returns it as `Some(value)`; returns `None` if the array is empty. *This function modifies the original array.* See [`Array.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift) on MDN. +If the array is not empty, removes the first element and returns it as `Some(value)`; returns `None` if the array is empty. *This function modifies the original array.* See [`Array.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift) on MDN. - ```res example - let arr = [100, 101, 102, 103, 104] - Js.Array.shift(arr) == Some(100) - arr == [101, 102, 103, 104] +## Examples - let empty: array = [] - Js.Array.shift(empty) == None - ``` +```rescript +let arr = [100, 101, 102, 103, 104] +Js.Array.shift(arr) == Some(100) +arr == [101, 102, 103, 104] + +let empty: array = [] +Js.Array.shift(empty) == None +``` */ external shift: option<'a> = "shift" @bs.send.pipe(: t<'a> as 'this) /** - Sorts the given array in place and returns the sorted array. JavaScript sorts the array by converting the arguments to UTF-16 strings and sorting them. See the second example with sorting numbers, which does not do a numeric sort. *This function modifies the original array.* See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. +Sorts the given array in place and returns the sorted array. JavaScript sorts the array by converting the arguments to UTF-16 strings and sorting them. See the second example with sorting numbers, which does not do a numeric sort. *This function modifies the original array.* See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. - ```res example - let words = ["bee", "dog", "ant", "cat"] - Js.Array.sortInPlace(words) == ["ant", "bee", "cat", "dog"] - words == ["ant", "bee", "cat", "dog"] +## Examples - let numbers = [3, 30, 10, 1, 20, 2] - Js.Array.sortInPlace(numbers) == [1, 10, 2, 20, 3, 30] - numbers == [1, 10, 2, 20, 3, 30] - ``` +```rescript +let words = ["bee", "dog", "ant", "cat"] +Js.Array.sortInPlace(words) == ["ant", "bee", "cat", "dog"] +words == ["ant", "bee", "cat", "dog"] + +let numbers = [3, 30, 10, 1, 20, 2] +Js.Array.sortInPlace(numbers) == [1, 10, 2, 20, 3, 30] +numbers == [1, 10, 2, 20, 3, 30] +``` */ external sortInPlace: 'this = "sort" @bs.send.pipe(: t<'a> as 'this) /** - Sorts the given array in place and returns the sorted array. *This function modifies the original array.* +Sorts the given array in place and returns the sorted array. *This function modifies the original array.* - The first argument to `sortInPlaceWith()` is a function that compares two items from the array and returns: +The first argument to `sortInPlaceWith()` is a function that compares two items from the array and returns: - * an integer less than zero if the first item is less than the second item - * zero if the items are equal - * an integer greater than zero if the first item is greater than the second item +* an integer less than zero if the first item is less than the second item +* zero if the items are equal +* an integer greater than zero if the first item is greater than the second item - See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. +See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. - ```res example - // sort by word length - let words = ["horse", "aardvark", "dog", "camel"] - let byLength = (s1, s2) => Js.String.length(s1) - Js.String.length(s2) +## Examples - Js.Array.sortInPlaceWith(byLength, words) == ["dog", "horse", "camel", "aardvark"] +```rescript +// sort by word length +let words = ["horse", "aardvark", "dog", "camel"] +let byLength = (s1, s2) => Js.String.length(s1) - Js.String.length(s2) - // sort in reverse numeric order - let numbers = [3, 30, 10, 1, 20, 2] - let reverseNumeric = (n1, n2) => n2 - n1 - Js.Array.sortInPlaceWith(reverseNumeric, numbers) == [30, 20, 10, 3, 2, 1] - ``` +Js.Array.sortInPlaceWith(byLength, words) == ["dog", "horse", "camel", "aardvark"] + +// sort in reverse numeric order +let numbers = [3, 30, 10, 1, 20, 2] +let reverseNumeric = (n1, n2) => n2 - n1 +Js.Array.sortInPlaceWith(reverseNumeric, numbers) == [30, 20, 10, 3, 2, 1] +``` */ external sortInPlaceWith: (@uncurry ('a, 'a) => int) => 'this = "sort" @bs.send.pipe(: t<'a> as 'this) @variadic /** - Starting at position `~pos`, remove `~remove` elements and then add the - elements from the `~add` array. Returns an array consisting of the removed - items. *This function modifies the original array.* See - [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) - on MDN. +Starting at position `~pos`, remove `~remove` elements and then add the +elements from the `~add` array. Returns an array consisting of the removed +items. *This function modifies the original array.* See +[`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +on MDN. + +## Examples - ```res example - let arr = ["a", "b", "c", "d", "e", "f"] - Js.Array.spliceInPlace(~pos=2, ~remove=2, ~add=["x", "y", "z"], arr) == ["c", "d"] - arr == ["a", "b", "x", "y", "z", "e", "f"] +```rescript +let arr = ["a", "b", "c", "d", "e", "f"] +Js.Array.spliceInPlace(~pos=2, ~remove=2, ~add=["x", "y", "z"], arr) == ["c", "d"] +arr == ["a", "b", "x", "y", "z", "e", "f"] - let arr2 = ["a", "b", "c", "d"] - Js.Array.spliceInPlace(~pos=3, ~remove=0, ~add=["x", "y"], arr2) == [] - arr2 == ["a", "b", "c", "x", "y", "d"] +let arr2 = ["a", "b", "c", "d"] +Js.Array.spliceInPlace(~pos=3, ~remove=0, ~add=["x", "y"], arr2) == [] +arr2 == ["a", "b", "c", "x", "y", "d"] - let arr3 = ["a", "b", "c", "d", "e", "f"] - Js.Array.spliceInPlace(~pos=9, ~remove=2, ~add=["x", "y", "z"], arr3) == [] - arr3 == ["a", "b", "c", "d", "e", "f", "x", "y", "z"] - ``` +let arr3 = ["a", "b", "c", "d", "e", "f"] +Js.Array.spliceInPlace(~pos=9, ~remove=2, ~add=["x", "y", "z"], arr3) == [] +arr3 == ["a", "b", "c", "d", "e", "f", "x", "y", "z"] +``` */ external spliceInPlace: (~pos: int, ~remove: int, ~add: array<'a>) => 'this = "splice" @bs.send.pipe(: t<'a> as 'this) /** - Removes elements from the given array starting at position `~pos` to the end - of the array, returning the removed elements. *This function modifies the - original array.* See - [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) - on MDN. +Removes elements from the given array starting at position `~pos` to the end +of the array, returning the removed elements. *This function modifies the +original array.* See +[`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +on MDN. - ```res example - let arr = ["a", "b", "c", "d", "e", "f"] - Js.Array.removeFromInPlace(~pos=4, arr) == ["e", "f"] - arr == ["a", "b", "c", "d"] - ``` +## Examples + +```rescript +let arr = ["a", "b", "c", "d", "e", "f"] +Js.Array.removeFromInPlace(~pos=4, arr) == ["e", "f"] +arr == ["a", "b", "c", "d"] +``` */ external removeFromInPlace: (~pos: int) => 'this = "splice" @bs.send.pipe(: t<'a> as 'this) /** - Removes `~count` elements from the given array starting at position `~pos`, - returning the removed elements. *This function modifies the original array.* - See - [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) - on MDN. +Removes `~count` elements from the given array starting at position `~pos`, +returning the removed elements. *This function modifies the original array.* +See +[`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) +on MDN. + +## Examples - ```res example - let arr = ["a", "b", "c", "d", "e", "f"] - Js.Array.removeCountInPlace(~pos=2, ~count=3, arr) == ["c", "d", "e"] - arr == ["a", "b", "f"] - ``` +```rescript +let arr = ["a", "b", "c", "d", "e", "f"] +Js.Array.removeCountInPlace(~pos=2, ~count=3, arr) == ["c", "d", "e"] +arr == ["a", "b", "f"] +``` */ external removeCountInPlace: (~pos: int, ~count: int) => 'this = "splice" @bs.send.pipe(: t<'a> as 'this) /** - Adds the given element to the array, returning the new number of elements in - the array. *This function modifies the original array.* See - [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) - on MDN. +Adds the given element to the array, returning the new number of elements in +the array. *This function modifies the original array.* See +[`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) +on MDN. - ```res example - let arr = ["b", "c", "d"] - Js.Array.unshift("a", arr) == 4 - arr == ["a", "b", "c", "d"] - ``` +## Examples + +```rescript +let arr = ["b", "c", "d"] +Js.Array.unshift("a", arr) == 4 +arr == ["a", "b", "c", "d"] +``` */ external unshift: 'a => int = "unshift" @bs.send.pipe(: t<'a> as 'this) @variadic /** - Adds the elements in the first array argument at the beginning of the second - array argument, returning the new number of elements in the array. *This - function modifies the original array.* See - [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) - on MDN. +Adds the elements in the first array argument at the beginning of the second +array argument, returning the new number of elements in the array. *This +function modifies the original array.* See +[`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) +on MDN. + +## Examples - ```res example - let arr = ["d", "e"] - Js.Array.unshiftMany(["a", "b", "c"], arr) == 5 - arr == ["a", "b", "c", "d", "e"] - ``` +```rescript +let arr = ["d", "e"] +Js.Array.unshiftMany(["a", "b", "c"], arr) == 5 +arr == ["a", "b", "c", "d", "e"] +``` */ external unshiftMany: array<'a> => int = "unshift" @@ -408,199 +452,222 @@ external unshiftMany: array<'a> => int = "unshift" */ @bs.send.pipe(: t<'a> as 'this) /** - Concatenates the first array argument to the second array argument, returning - a new array. The original arrays are not modified. See - [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) - on MDN. +Concatenates the first array argument to the second array argument, returning +a new array. The original arrays are not modified. See +[`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) +on MDN. - ```res example - Js.Array.concat(["c", "d", "e"], ["a", "b"]) == ["a", "b", "c", "d", "e"] - ``` +## Examples + +```rescript +Js.Array.concat(["c", "d", "e"], ["a", "b"]) == ["a", "b", "c", "d", "e"] +``` */ external concat: 'this => 'this = "concat" @bs.send.pipe(: t<'a> as 'this) @variadic /** - The first argument to `concatMany()` is an array of arrays; these are added - at the end of the second argument, returning a new array. See - [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) - on MDN. - - ```res example - Js.Array.concatMany([["d", "e"], ["f", "g", "h"]], ["a", "b", "c"]) == [ - "a", - "b", - "c", - "d", - "e", - "f", - "g", - "h", - ] - ``` +The first argument to `concatMany()` is an array of arrays; these are added +at the end of the second argument, returning a new array. See +[`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) +on MDN. + +## Examples + +```rescript +Js.Array.concatMany([["d", "e"], ["f", "g", "h"]], ["a", "b", "c"]) == [ + "a", + "b", + "c", + "d", + "e", + "f", + "g", + "h", + ] +``` */ external concatMany: array<'this> => 'this = "concat" /* ES2016 */ @bs.send.pipe(: t<'a> as 'this) /** - Returns true if the given value is in the array, `false` otherwise. See - [`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes) - on MDN. +Returns true if the given value is in the array, `false` otherwise. See +[`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes) +on MDN. - ```res example - Js.Array.includes("b", ["a", "b", "c"]) == true - Js.Array.includes("x", ["a", "b", "c"]) == false - ``` +## Examples + +```rescript +Js.Array.includes("b", ["a", "b", "c"]) == true +Js.Array.includes("x", ["a", "b", "c"]) == false +``` */ external includes: 'a => bool = "includes" @bs.send.pipe(: t<'a> as 'this) /** - Returns the index of the first element in the array that has the given value. - If the value is not in the array, returns -1. See - [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) - on MDN. +Returns the index of the first element in the array that has the given value. +If the value is not in the array, returns -1. See +[`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) +on MDN. + +## Examples - ```res example - Js.Array.indexOf(102, [100, 101, 102, 103]) == 2 - Js.Array.indexOf(999, [100, 101, 102, 103]) == -1 - ``` +```rescript +Js.Array.indexOf(102, [100, 101, 102, 103]) == 2 +Js.Array.indexOf(999, [100, 101, 102, 103]) == -1 +``` */ external indexOf: 'a => int = "indexOf" @bs.send.pipe(: t<'a> as 'this) /** - Returns the index of the first element in the array with the given value. The - search starts at position `~from`. See - [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) - on MDN. +Returns the index of the first element in the array with the given value. The +search starts at position `~from`. See +[`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) +on MDN. - ```res example - Js.Array.indexOfFrom("a", ~from=2, ["a", "b", "a", "c", "a"]) == 2 - Js.Array.indexOfFrom("a", ~from=3, ["a", "b", "a", "c", "a"]) == 4 - Js.Array.indexOfFrom("b", ~from=2, ["a", "b", "a", "c", "a"]) == -1 - ``` +## Examples + +```rescript +Js.Array.indexOfFrom("a", ~from=2, ["a", "b", "a", "c", "a"]) == 2 +Js.Array.indexOfFrom("a", ~from=3, ["a", "b", "a", "c", "a"]) == 4 +Js.Array.indexOfFrom("b", ~from=2, ["a", "b", "a", "c", "a"]) == -1 +``` */ external indexOfFrom: ('a, ~from: int) => int = "indexOf" -@send @deprecated("please use joinWith instead") /** - @deprecated: Use `joinWith` instead. -*/ +@send @deprecated("please use joinWith instead") external join: t<'a> => string = "join" @bs.send.pipe(: t<'a> as 'this) /** - This function converts each element of the array to a string (via JavaScript) +This function converts each element of the array to a string (via JavaScript) and concatenates them, separated by the string given in the first argument, into a single string. See [`Array.join`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join) on MDN. - ```res example - Js.Array.joinWith("--", ["ant", "bee", "cat"]) == "ant--bee--cat" - Js.Array.joinWith("", ["door", "bell"]) == "doorbell" - Js.Array.joinWith("/", [2020, 9, 4]) == "2020/9/4" - Js.Array.joinWith(";", [2.5, 3.6, 3e-2]) == "2.5;3.6;0.03" - ``` +## Examples + +```rescript +Js.Array.joinWith("--", ["ant", "bee", "cat"]) == "ant--bee--cat" +Js.Array.joinWith("", ["door", "bell"]) == "doorbell" +Js.Array.joinWith("/", [2020, 9, 4]) == "2020/9/4" +Js.Array.joinWith(";", [2.5, 3.6, 3e-2]) == "2.5;3.6;0.03" +``` */ external joinWith: string => string = "join" @bs.send.pipe(: t<'a> as 'this) /** - Returns the index of the last element in the array that has the given value. - If the value is not in the array, returns -1. See - [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) - on MDN. +Returns the index of the last element in the array that has the given value. +If the value is not in the array, returns -1. See +[`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) +on MDN. - ```res example - Js.Array.lastIndexOf("a", ["a", "b", "a", "c"]) == 2 - Js.Array.lastIndexOf("x", ["a", "b", "a", "c"]) == -1 - ``` +## Examples + +```rescript +Js.Array.lastIndexOf("a", ["a", "b", "a", "c"]) == 2 +Js.Array.lastIndexOf("x", ["a", "b", "a", "c"]) == -1 +``` */ external lastIndexOf: 'a => int = "lastIndexOf" @bs.send.pipe(: t<'a> as 'this) /** - Returns the index of the last element in the array that has the given value, - searching from position `~from` down to the start of the array. If the value - is not in the array, returns -1. See - [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) - on MDN. +Returns the index of the last element in the array that has the given value, +searching from position `~from` down to the start of the array. If the value +is not in the array, returns -1. See +[`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) +on MDN. + +## Examples - ```res example - Js.Array.lastIndexOfFrom("a", ~from=3, ["a", "b", "a", "c", "a", "d"]) == 2 - Js.Array.lastIndexOfFrom("c", ~from=2, ["a", "b", "a", "c", "a", "d"]) == -1 - ``` +```rescript +Js.Array.lastIndexOfFrom("a", ~from=3, ["a", "b", "a", "c", "a", "d"]) == 2 +Js.Array.lastIndexOfFrom("c", ~from=2, ["a", "b", "a", "c", "a", "d"]) == -1 +``` */ external lastIndexOfFrom: ('a, ~from: int) => int = "lastIndexOf" @bs.send.pipe(: t<'a> as 'this) /** - Returns a shallow copy of the given array from the `~start` index up to but - not including the `~end_` position. Negative numbers indicate an offset from - the end of the array. See - [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) - on MDN. +Returns a shallow copy of the given array from the `~start` index up to but +not including the `~end_` position. Negative numbers indicate an offset from +the end of the array. See +[`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) +on MDN. - ```res example - let arr = [100, 101, 102, 103, 104, 105, 106] - Js.Array.slice(~start=2, ~end_=5, arr) == [102, 103, 104] - Js.Array.slice(~start=-3, ~end_=-1, arr) == [104, 105] - Js.Array.slice(~start=9, ~end_=10, arr) == [] - ``` +## Examples + +```rescript +let arr = [100, 101, 102, 103, 104, 105, 106] +Js.Array.slice(~start=2, ~end_=5, arr) == [102, 103, 104] +Js.Array.slice(~start=-3, ~end_=-1, arr) == [104, 105] +Js.Array.slice(~start=9, ~end_=10, arr) == [] +``` */ external slice: (~start: int, ~end_: int) => 'this = "slice" @bs.send.pipe(: t<'a> as 'this) /** - Returns a copy of the entire array. Same as `Js.Array.Slice(~start=0, - ~end_=Js.Array.length(arr), arr)`. See - [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) - on MDN. +Returns a copy of the entire array. Same as `Js.Array.Slice(~start=0, +~end_=Js.Array.length(arr), arr)`. See +[`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) +on MDN. */ external copy: 'this = "slice" @bs.send.pipe(: t<'a> as 'this) /** - Returns a shallow copy of the given array from the given index to the end. See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. +Returns a shallow copy of the given array from the given index to the end. +See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. + +## Examples - ```res example - Js.Array.sliceFrom(2, [100, 101, 102, 103, 104]) == [102, 103, 104] - ``` +```rescript +Js.Array.sliceFrom(2, [100, 101, 102, 103, 104]) == [102, 103, 104] +``` */ external sliceFrom: int => 'this = "slice" @bs.send.pipe(: t<'a> as 'this) /** - Converts the array to a string. Each element is converted to a string using - JavaScript. Unlike the JavaScript `Array.toString()`, all elements in a - ReasonML array must have the same type. See - [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) - on MDN. +Converts the array to a string. Each element is converted to a string using +JavaScript. Unlike the JavaScript `Array.toString()`, all elements in a +ReasonML array must have the same type. See +[`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) +on MDN. - ```res example - Js.Array.toString([3.5, 4.6, 7.8]) == "3.5,4.6,7.8" - Js.Array.toString(["a", "b", "c"]) == "a,b,c" - ``` +## Examples + +```rescript +Js.Array.toString([3.5, 4.6, 7.8]) == "3.5,4.6,7.8" +Js.Array.toString(["a", "b", "c"]) == "a,b,c" +``` */ external toString: string = "toString" @bs.send.pipe(: t<'a> as 'this) /** - Converts the array to a string using the conventions of the current locale. - Each element is converted to a string using JavaScript. Unlike the JavaScript - `Array.toLocaleString()`, all elements in a ReasonML array must have the same +Converts the array to a string using the conventions of the current locale. +Each element is converted to a string using JavaScript. Unlike the JavaScript +`Array.toLocaleString()`, all elements in a ReasonML array must have the same type. See [`Array.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString) on MDN. - ```res example - Js.Array.toLocaleString([Js.Date.make()]) - // returns "3/19/2020, 10:52:11 AM" for locale en_US.utf8 - // returns "2020-3-19 10:52:11" for locale de_DE.utf8 - ``` +## Examples + +```rescript +Js.Array.toLocaleString([Js.Date.make()]) +// returns "3/19/2020, 10:52:11 AM" for locale en_US.utf8 +// returns "2020-3-19 10:52:11" for locale de_DE.utf8 +``` */ external toLocaleString: string = "toLocaleString" @@ -612,54 +679,62 @@ external toLocaleString: string = "toLocaleString" @bs.send.pipe(: t<'a> as 'this) /** - The first argument to `every()` is a predicate function that returns a boolean. The `every()` function returns `true` if the predicate function is true for all items in the given array. If given an empty array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. +The first argument to `every()` is a predicate function that returns a boolean. The `every()` function returns `true` if the predicate function is true for all items in the given array. If given an empty array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. - ```res example - let isEven = x => mod(x, 2) == 0 - Js.Array.every(isEven, [6, 22, 8, 4]) == true - Js.Array.every(isEven, [6, 22, 7, 4]) == false - ``` +## Examples + +```rescript +let isEven = x => mod(x, 2) == 0 +Js.Array.every(isEven, [6, 22, 8, 4]) == true +Js.Array.every(isEven, [6, 22, 7, 4]) == false +``` */ external every: (@uncurry ('a => bool)) => bool = "every" @bs.send.pipe(: t<'a> as 'this) /** - The first argument to `everyi()` is a predicate function with two arguments: an array element and that element’s index; it returns a boolean. The `everyi()` function returns `true` if the predicate function is true for all items in the given array. If given an empty array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. +The first argument to `everyi()` is a predicate function with two arguments: an array element and that element’s index; it returns a boolean. The `everyi()` function returns `true` if the predicate function is true for all items in the given array. If given an empty array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. + +## Examples - ```res example - // determine if all even-index items are positive - let evenIndexPositive = (item, index) => mod(index, 2) == 0 ? item > 0 : true +```rescript +// determine if all even-index items are positive +let evenIndexPositive = (item, index) => mod(index, 2) == 0 ? item > 0 : true - Js.Array.everyi(evenIndexPositive, [6, -3, 5, 8]) == true - Js.Array.everyi(evenIndexPositive, [6, 3, -5, 8]) == false - ``` +Js.Array.everyi(evenIndexPositive, [6, -3, 5, 8]) == true +Js.Array.everyi(evenIndexPositive, [6, 3, -5, 8]) == false +``` */ external everyi: (@uncurry ('a, int) => bool) => bool = "every" @bs.send.pipe(: t<'a> as 'this) /** - Applies the given predicate function to each element in the array; the result is an array of those elements for which the predicate function returned `true`. See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN. +Applies the given predicate function to each element in the array; the result is an array of those elements for which the predicate function returned `true`. See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN. + +## Examples - ```res example - let nonEmpty = s => s != "" - Js.Array.filter(nonEmpty, ["abc", "", "", "def", "ghi"]) == ["abc", "def", "ghi"] - ``` +```rescript +let nonEmpty = s => s != "" +Js.Array.filter(nonEmpty, ["abc", "", "", "def", "ghi"]) == ["abc", "def", "ghi"] +``` */ external filter: (@uncurry ('a => bool)) => 'this = "filter" @bs.send.pipe(: t<'a> as 'this) /** - Each element of the given array are passed to the predicate function. The - return value is an array of all those elements for which the predicate - function returned `true`. See - [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) - on MDN. +Each element of the given array are passed to the predicate function. The +return value is an array of all those elements for which the predicate +function returned `true`. See +[`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) +on MDN. - ```res example - // keep only positive elements at odd indices - let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 +## Examples - Js.Array.filteri(positiveOddElement, [6, 3, 5, 8, 7, -4, 1]) == [3, 8] +```rescript +// keep only positive elements at odd indices +let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 + +Js.Array.filteri(positiveOddElement, [6, 3, 5, 8, 7, -4, 1]) == [3, 8] ``` */ external filteri: (@uncurry ('a, int) => bool) => 'this = "filter" @@ -667,79 +742,91 @@ external filteri: (@uncurry ('a, int) => bool) => 'this = "filter" @bs.send.pipe(: t<'a> as 'this) @return({undefined_to_opt: undefined_to_opt}) /** - Returns `Some(value)` for the first element in the array that satisifies the - given predicate function, or `None` if no element satisifies the predicate. - See - [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) - on MDN. +Returns `Some(value)` for the first element in the array that satisifies the +given predicate function, or `None` if no element satisifies the predicate. +See +[`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) +on MDN. - ```res example - // find first negative element - Js.Array.find(x => x < 0, [33, 22, -55, 77, -44]) == Some(-55) - Js.Array.find(x => x < 0, [33, 22, 55, 77, 44]) == None - ``` +## Examples + +```rescript +// find first negative element +Js.Array.find(x => x < 0, [33, 22, -55, 77, -44]) == Some(-55) +Js.Array.find(x => x < 0, [33, 22, 55, 77, 44]) == None +``` */ external find: (@uncurry ('a => bool)) => option<'a> = "find" @bs.send.pipe(: t<'a> as 'this) @return({undefined_to_opt: undefined_to_opt}) /** - Returns `Some(value)` for the first element in the array that satisifies the given predicate function, or `None` if no element satisifies the predicate. The predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. +Returns `Some(value)` for the first element in the array that satisifies the given predicate function, or `None` if no element satisifies the predicate. The predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. - ```res example - // find first positive item at an odd index - let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 +## Examples - Js.Array.findi(positiveOddElement, [66, -33, 55, 88, 22]) == Some(88) - Js.Array.findi(positiveOddElement, [66, -33, 55, -88, 22]) == None - ``` +```rescript +// find first positive item at an odd index +let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 + +Js.Array.findi(positiveOddElement, [66, -33, 55, 88, 22]) == Some(88) +Js.Array.findi(positiveOddElement, [66, -33, 55, -88, 22]) == None +``` */ external findi: (@uncurry ('a, int) => bool) => option<'a> = "find" @bs.send.pipe(: t<'a> as 'this) /** - Returns the index of the first element in the array that satisifies the given predicate function, or -1 if no element satisifies the predicate. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. +Returns the index of the first element in the array that satisifies the given predicate function, or -1 if no element satisifies the predicate. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. - ```res example - Js.Array.findIndex(x => x < 0, [33, 22, -55, 77, -44]) == 2 - Js.Array.findIndex(x => x < 0, [33, 22, 55, 77, 44]) == -1 - ``` +## Examples + +```rescript +Js.Array.findIndex(x => x < 0, [33, 22, -55, 77, -44]) == 2 +Js.Array.findIndex(x => x < 0, [33, 22, 55, 77, 44]) == -1 +``` */ external findIndex: (@uncurry ('a => bool)) => int = "findIndex" @bs.send.pipe(: t<'a> as 'this) /** - Returns `Some(value)` for the first element in the array that satisifies the given predicate function, or `None` if no element satisifies the predicate. The predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. +Returns `Some(value)` for the first element in the array that satisifies the given predicate function, or `None` if no element satisifies the predicate. The predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. - ```res example - // find index of first positive item at an odd index - let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 +## Examples - Js.Array.findIndexi(positiveOddElement, [66, -33, 55, 88, 22]) == 3 - Js.Array.findIndexi(positiveOddElement, [66, -33, 55, -88, 22]) == -1 - ``` +```rescript +// find index of first positive item at an odd index +let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 + +Js.Array.findIndexi(positiveOddElement, [66, -33, 55, 88, 22]) == 3 +Js.Array.findIndexi(positiveOddElement, [66, -33, 55, -88, 22]) == -1 +``` */ external findIndexi: (@uncurry ('a, int) => bool) => int = "findIndex" @bs.send.pipe(: t<'a> as 'this) /** - The `forEach()` function applies the function given as the first argument to each element in the array. The function you provide returns `unit`, and the `forEach()` function also returns `unit`. You use `forEach()` when you need to process each element in the array but not return any new array or value; for example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. +The `forEach()` function applies the function given as the first argument to each element in the array. The function you provide returns `unit`, and the `forEach()` function also returns `unit`. You use `forEach()` when you need to process each element in the array but not return any new array or value; for example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. - ```res example - // display all elements in an array - Js.Array.forEach(x => Js.log(x), ["a", "b", "c"]) == () - ``` +## Examples + +```rescript +// display all elements in an array +Js.Array.forEach(x => Js.log(x), ["a", "b", "c"]) == () +``` */ external forEach: (@uncurry ('a => unit)) => unit = "forEach" @bs.send.pipe(: t<'a> as 'this) /** - The `forEachi()` function applies the function given as the first argument to each element in the array. The function you provide takes an item in the array and its index number, and returns `unit`. The `forEachi()` function also returns `unit`. You use `forEachi()` when you need to process each element in the array but not return any new array or value; for example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. +The `forEachi()` function applies the function given as the first argument to each element in the array. The function you provide takes an item in the array and its index number, and returns `unit`. The `forEachi()` function also returns `unit`. You use `forEachi()` when you need to process each element in the array but not return any new array or value; for example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. - ```res example - // display all elements in an array as a numbered list - Js.Array.forEachi((item, index) => Js.log2(index + 1, item), ["a", "b", "c"]) == () - ``` +## Examples + +```rescript +// display all elements in an array as a numbered list +Js.Array.forEachi((item, index) => Js.log2(index + 1, item), ["a", "b", "c"]) == () +``` */ external forEachi: (@uncurry ('a, int) => unit) => unit = "forEach" @@ -749,33 +836,37 @@ external forEachi: (@uncurry ('a, int) => unit) => unit = "forEach" @bs.send.pipe(: t<'a> as 'this) /** - Applies the function (given as the first argument) to each item in the array, - returning a new array. The result array does not have to have elements of the - same type as the input array. See - [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) - on MDN. +Applies the function (given as the first argument) to each item in the array, +returning a new array. The result array does not have to have elements of the +same type as the input array. See +[`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) +on MDN. + +## Examples - ```res example - Js.Array.map(x => x * x, [12, 4, 8]) == [144, 16, 64] - Js.Array.map(Js.String.length, ["animal", "vegetable", "mineral"]) == [6, 9, 7] - ``` +```rescript +Js.Array.map(x => x * x, [12, 4, 8]) == [144, 16, 64] +Js.Array.map(Js.String.length, ["animal", "vegetable", "mineral"]) == [6, 9, 7] +``` */ external map: (@uncurry ('a => 'b)) => t<'b> = "map" @bs.send.pipe(: t<'a> as 'this) /** - Applies the function (given as the first argument) to each item in the array, - returning a new array. The function acceps two arguments: an item from the - array and its index number. The result array does not have to have elements - of the same type as the input array. See - [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) - on MDN. +Applies the function (given as the first argument) to each item in the array, +returning a new array. The function acceps two arguments: an item from the +array and its index number. The result array does not have to have elements +of the same type as the input array. See +[`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) +on MDN. - ```res example - // multiply each item in array by its position - let product = (item, index) => item * index - Js.Array.mapi(product, [10, 11, 12]) == [0, 11, 24] - ``` +## Examples + +```rescript +// multiply each item in array by its position +let product = (item, index) => item * index +Js.Array.mapi(product, [10, 11, 12]) == [0, 11, 24] +``` */ external mapi: (@uncurry ('a, int) => 'b) => t<'b> = "map" @@ -796,7 +887,9 @@ becomes the return value of `reduce()`. See [`Array.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) on MDN. -```res example +## Examples + +```rescript let sumOfSquares = (accumulator, item) => accumulator + item * item Js.Array.reduce(sumOfSquares, 0, [10, 2, 4]) == 120 @@ -830,7 +923,9 @@ becomes the return value of `reducei()`. See [`Array.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) on MDN. -```res example +## Examples + +```rescript // find sum of even-index elements in array let sumOfEvens = (accumulator, item, index) => if mod(index, 2) == 0 { @@ -863,7 +958,9 @@ on MDN. **NOTE:** In many cases, `reduce()` and `reduceRight()` give the same result. However, see the last example here and compare it to the example from `reduce()`, where order makes a difference. -```res example +## Examples + +```rescript let sumOfSquares = (accumulator, item) => accumulator + item * item Js.Array.reduceRight(sumOfSquares, 0, [10, 2, 4]) == 120 @@ -893,7 +990,9 @@ on MDN. However, there are cases where the order in which items are processed makes a difference. -```res example +## Examples + +```rescript // find sum of even-index elements in array let sumOfEvens = (accumulator, item, index) => if mod(index, 2) == 0 { @@ -912,7 +1011,9 @@ external reduceRighti: (@uncurry ('b, 'a, int) => 'b, 'b) => 'b = "reduceRight" Returns `true` if the predicate function given as the first argument to `some()` returns `true` for any element in the array; `false` otherwise. -```res example +## Examples + +```rescript let isEven = x => mod(x, 2) == 0 Js.Array.some(isEven, [3, 7, 5, 2, 9]) == true @@ -928,7 +1029,9 @@ Returns `true` if the predicate function given as the first argument to predicate function has two arguments: an item from the array and the index value -```res example +## Examples + +```rescript // Does any string in the array // have the same length as its index? @@ -949,7 +1052,9 @@ external somei: (@uncurry ('a, int) => bool) => bool = "some" Returns the value at the given position in the array if the position is in bounds; returns the JavaScript value `undefined` otherwise. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103] Js.Array.unsafe_get(arr, 3) == 103 Js.Array.unsafe_get(arr, 4) // returns undefined @@ -962,7 +1067,9 @@ Sets the value at the given position in the array if the position is in bounds. If the index is out of bounds, well, “here there be dragons.“ *This function modifies the original array.* -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103] Js.Array.unsafe_set(arr, 3, 99) // result is [100, 101, 102, 99] diff --git a/jscomp/others/js_array2.res b/jscomp/others/js_array2.res index 187ecefa57..7c270f0ca1 100644 --- a/jscomp/others/js_array2.res +++ b/jscomp/others/js_array2.res @@ -23,36 +23,42 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Provides bindings to JavaScript’s `Array` functions. These bindings are optimized for pipe-first (`->`), where the array to be processed is the first parameter in the function. +Provides bindings to JavaScript’s `Array` functions. These bindings are optimized for pipe-first (`->`), where the array to be processed is the first parameter in the function. - Here is an example to find the sum of squares of all even numbers in an array. - Without pipe first, we must call the functions in reverse order: +Here is an example to find the sum of squares of all even numbers in an array. +Without pipe first, we must call the functions in reverse order: - ```res example - let isEven = x => mod(x, 2) == 0 - let square = x => x * x - let result = { - open Js.Array2 - reduce(map(filter([5, 2, 3, 4, 1], isEven), square), "+", 0) - } - ``` +## Examples - With pipe first, we call the functions in the “natural” order: +```rescript +let isEven = x => mod(x, 2) == 0 +let square = x => x * x +let result = { + open Js.Array2 + reduce(map(filter([5, 2, 3, 4, 1], isEven), square), "+", 0) +} +``` - ```res example - let isEven = x => mod(x, 2) == 0 - let square = x => x * x - let result = { - open Js.Array2 - [5, 2, 3, 4, 1]->filter(isEven)->map(square)->reduce("+", 0) - } - ``` +With pipe first, we call the functions in the “natural” order: + +```rescript +let isEven = x => mod(x, 2) == 0 +let square = x => x * x +let result = { + open Js.Array2 + [5, 2, 3, 4, 1]->filter(isEven)->map(square)->reduce("+", 0) +} +``` */ -/** The type used to describe a JavaScript array. */ +/** +The type used to describe a JavaScript array. +*/ type t<'a> = array<'a> -/** A type used to describe JavaScript objects that are like an array or are iterable. */ +/** +A type used to describe JavaScript objects that are like an array or are iterable. +*/ type array_like<'a> /* commented out until bs has a plan for iterators @@ -65,7 +71,9 @@ Creates a shallow copy of an array from an array-like object. See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN. -```res example +## Examples + +```rescript let strArr = Js.String.castToArrayLike("abcd") Js.Array2.from(strArr) == ["a", "b", "c", "d"] ``` @@ -81,7 +89,9 @@ in the `array_like` first argument. See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN. -```res example +## Examples + +```rescript let strArr = Js.String.castToArrayLike("abcd") let code = s => Js.String.charCodeAt(0, s) Js.Array2.fromMap(strArr, code) == [97.0, 98.0, 99.0, 100.0] @@ -95,7 +105,9 @@ external fromMap: (array_like<'a>, @uncurry ('a => 'b)) => array<'b> = "Array.fr /** Returns `true` if its argument is an array; `false` otherwise. This is a runtime check, which is why the second example returns `true`---a list is internally represented as a nested JavaScript array. -```res example +## Examples + +```rescript Js.Array2.isArray([5, 2, 3, 1, 4]) == true Js.Array2.isArray(list{5, 2, 3, 1, 4}) == true Js.Array2.isArray("abcd") == false @@ -121,7 +133,9 @@ array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.copyWithin(arr, ~to_=2) == [100, 101, 100, 101, 102] arr == [100, 101, 100, 101, 102] @@ -139,7 +153,9 @@ array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.copyWithinFrom(arr, ~from=2, ~to_=0) == [102, 103, 104, 103, 104] arr == [102, 103, 104, 103, 104] @@ -157,7 +173,9 @@ function modifies the original array.* See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104, 105] Js.Array2.copyWithinFromRange(arr, ~start=2, ~end_=5, ~to_=1) == [100, 102, 103, 104, 104, 105] arr == [100, 102, 103, 104, 104, 105] @@ -177,7 +195,9 @@ See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.fillInPlace(arr, 99) == [99, 99, 99, 99, 99] arr == [99, 99, 99, 99, 99] @@ -195,7 +215,9 @@ resulting array. *This function modifies the original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.fillFromInPlace(arr, 99, ~from=2) == [100, 101, 99, 99, 99] arr == [100, 101, 99, 99, 99] @@ -214,7 +236,9 @@ original array.* See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.fillRangeInPlace(arr, 99, ~start=1, ~end_=4) == [100, 99, 99, 99, 104] arr == [100, 99, 99, 99, 104] @@ -233,7 +257,9 @@ the original array.* See [`Array.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.pop(arr) == Some(104) arr == [100, 101, 102, 103] @@ -251,7 +277,9 @@ updated array. *This function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. -```res example +## Examples + +```rescript let arr = ["ant", "bee", "cat"] Js.Array2.push(arr, "dog") == 4 arr == ["ant", "bee", "cat", "dog"] @@ -268,7 +296,9 @@ function modifies the original array.* See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN. -```res example +## Examples + +```rescript let arr = ["ant", "bee", "cat"] Js.Array2.pushMany(arr, ["dog", "elk"]) == 5 arr == ["ant", "bee", "cat", "dog", "elk"] @@ -283,7 +313,9 @@ function modifies the original array.* See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN. -```res example +## Examples + +```rescript let arr = ["ant", "bee", "cat"] Js.Array2.reverseInPlace(arr) == ["cat", "bee", "ant"] arr == ["cat", "bee", "ant"] @@ -300,7 +332,9 @@ the original array.* See [`Array.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104] Js.Array2.shift(arr) == Some(100) arr == [101, 102, 103, 104] @@ -320,7 +354,9 @@ the second example with sorting numbers, which does not do a numeric sort. [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. -```res example +## Examples + +```rescript let words = ["bee", "dog", "ant", "cat"] Js.Array2.sortInPlace(words) == ["ant", "bee", "cat", "dog"] words == ["ant", "bee", "cat", "dog"] @@ -348,7 +384,9 @@ See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN. -```res example +## Examples + +```rescript // sort by word length let words = ["horse", "aardvark", "dog", "camel"] let byLength = (s1, s2) => Js.String.length(s1) - Js.String.length(s2) @@ -372,7 +410,9 @@ items. *This function modifies the original array.* See [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) on MDN. -```res example +## Examples + +```rescript let arr = ["a", "b", "c", "d", "e", "f"] Js.Array2.spliceInPlace(arr, ~pos=2, ~remove=2, ~add=["x", "y", "z"]) == ["c", "d"] arr == ["a", "b", "x", "y", "z", "e", "f"] @@ -396,7 +436,9 @@ array.* See [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) on MDN. -```res example +## Examples + +```rescript let arr = ["a", "b", "c", "d", "e", "f"] Js.Array2.removeFromInPlace(arr, ~pos=4) == ["e", "f"] arr == ["a", "b", "c", "d"] @@ -412,7 +454,9 @@ See [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) on MDN. -```res example +## Examples + +```rescript let arr = ["a", "b", "c", "d", "e", "f"] Js.Array2.removeCountInPlace(arr, ~pos=2, ~count=3) == ["c", "d", "e"] arr == ["a", "b", "f"] @@ -427,7 +471,9 @@ the array. *This function modifies the original array.* See [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) on MDN. -```res example +## Examples + +```rescript let arr = ["b", "c", "d"] Js.Array2.unshift(arr, "a") == 4 arr == ["a", "b", "c", "d"] @@ -444,7 +490,9 @@ function modifies the original array.* See [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) on MDN. -```res example +## Examples + +```rescript let arr = ["d", "e"] Js.Array2.unshiftMany(arr, ["a", "b", "c"]) == 5 arr == ["a", "b", "c", "d", "e"] @@ -464,7 +512,9 @@ new array. The original arrays are not modified. See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN. -```res example +## Examples + +```rescript Js.Array2.concat(["a", "b"], ["c", "d", "e"]) == ["a", "b", "c", "d", "e"] ``` */ @@ -478,7 +528,9 @@ the end of the first argument, returning a new array. See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN. -```res example +## Examples + +```rescript Js.Array2.concatMany(["a", "b", "c"], [["d", "e"], ["f", "g", "h"]]) == [ "a", "b", @@ -499,7 +551,9 @@ Returns true if the given value is in the array, `false` otherwise. See [`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes) on MDN. -```res example +## Examples + +```rescript Js.Array2.includes(["a", "b", "c"], "b") == true Js.Array2.includes(["a", "b", "c"], "x") == false ``` @@ -513,7 +567,9 @@ If the value is not in the array, returns -1. See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) on MDN. -```res example +## Examples + +```rescript Js.Array2.indexOf([100, 101, 102, 103], 102) == 2 Js.Array2.indexOf([100, 101, 102, 103], 999) == -1 ``` @@ -527,7 +583,9 @@ search starts at position `~from`. See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) on MDN. -```res example +## Examples + +```rescript Js.Array2.indexOfFrom(["a", "b", "a", "c", "a"], "a", ~from=2) == 2 Js.Array2.indexOfFrom(["a", "b", "a", "c", "a"], "a", ~from=3) == 4 Js.Array2.indexOfFrom(["a", "b", "a", "c", "a"], "b", ~from=2) == -1 @@ -543,7 +601,9 @@ into a single string. See [`Array.join`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join) on MDN. -```res example +## Examples + +```rescript Js.Array2.joinWith(["ant", "bee", "cat"], "--") == "ant--bee--cat" Js.Array2.joinWith(["door", "bell"], "") == "doorbell" Js.Array2.joinWith([2020, 9, 4], "/") == "2020/9/4" @@ -559,7 +619,9 @@ the value is not in the array, returns -1. See [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) on MDN. -```res example +## Examples + +```rescript Js.Array2.lastIndexOf(["a", "b", "a", "c"], "a") == 2 Js.Array2.lastIndexOf(["a", "b", "a", "c"], "x") == -1 ``` @@ -574,7 +636,9 @@ not in the array, returns -1. See [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) on MDN. -```res example +## Examples + +```rescript Js.Array2.lastIndexOfFrom(["a", "b", "a", "c", "a", "d"], "a", ~from=3) == 2 Js.Array2.lastIndexOfFrom(["a", "b", "a", "c", "a", "d"], "c", ~from=2) == -1 ``` @@ -589,7 +653,9 @@ end of the array. See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103, 104, 105, 106] Js.Array2.slice(arr, ~start=2, ~end_=5) == [102, 103, 104] Js.Array2.slice(arr, ~start=-3, ~end_=-1) == [104, 105] @@ -623,7 +689,9 @@ ReasonML array must have the same type. See [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString) on MDN. -```res example +## Examples + +```rescript Js.Array2.toString([3.5, 4.6, 7.8]) == "3.5,4.6,7.8" Js.Array2.toString(["a", "b", "c"]) == "a,b,c" ``` @@ -639,7 +707,9 @@ type. See [`Array.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString) on MDN. -```res example +## Examples + +```rescript Js.Array2.toLocaleString([Js.Date.make()]) // returns "3/19/2020, 10:52:11 AM" for locale en_US.utf8 // returns "2020-3-19 10:52:11" for locale de_DE.utf8 @@ -662,7 +732,9 @@ array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. -```res example +## Examples + +```rescript let isEven = x => mod(x, 2) == 0 Js.Array2.every([6, 22, 8, 4], isEven) == true Js.Array2.every([6, 22, 7, 4], isEven) == false @@ -680,7 +752,9 @@ array, returns `true`. See [`Array.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) on MDN. -```res example +## Examples + +```rescript // determine if all even-index items are positive let evenIndexPositive = (item, index) => mod(index, 2) == 0 ? item > 0 : true @@ -698,7 +772,9 @@ function returned `true`. See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN. -```res example +## Examples + +```rescript let nonEmpty = s => s != "" Js.Array2.filter(["abc", "", "", "def", "ghi"], nonEmpty) == ["abc", "def", "ghi"] ``` @@ -715,7 +791,9 @@ See [`Array.filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) on MDN. -```res example +## Examples + +```rescript // keep only positive elements at odd indices let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 @@ -732,7 +810,9 @@ given predicate function, or `None` if no element satisifies the predicate. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. -```res example +## Examples + +```rescript // find first negative element Js.Array2.find([33, 22, -55, 77, -44], x => x < 0) == Some(-55) Js.Array2.find([33, 22, 55, 77, 44], x => x < 0) == None @@ -751,7 +831,9 @@ predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. -```res example +## Examples + +```rescript // find first positive item at an odd index let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 @@ -770,7 +852,9 @@ predicate function, or -1 if no element satisifies the predicate. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. -```res example +## Examples + +```rescript Js.Array2.findIndex([33, 22, -55, 77, -44], x => x < 0) == 2 Js.Array2.findIndex([33, 22, 55, 77, 44], x => x < 0) == -1 ``` @@ -787,7 +871,9 @@ predicate function takes an array element and an index as its parameters. See [`Array.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) on MDN. -```res example +## Examples + +```rescript // find index of first positive item at an odd index let positiveOddElement = (item, index) => mod(index, 2) == 1 && item > 0 @@ -809,7 +895,9 @@ example, to print the items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. -```res example +## Examples + +```rescript // display all elements in an array Js.Array2.forEach(["a", "b", "c"], x => Js.log(x)) == () ``` @@ -827,7 +915,9 @@ items in an array. See [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on MDN. -```res example +## Examples + +```rescript // display all elements in an array as a numbered list Js.Array2.forEachi(["a", "b", "c"], (item, index) => Js.log2(index + 1, item)) == () ``` @@ -846,7 +936,9 @@ as the input array. See [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on MDN. -```res example +## Examples + +```rescript Js.Array2.map([12, 4, 8], x => x * x) == [144, 16, 64] Js.Array2.map(["animal", "vegetable", "mineral"], Js.String.length) == [6, 9, 7] ``` @@ -862,7 +954,9 @@ as the input array. See [`Array.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on MDN. -```res example +## Examples + +```rescript // multiply each item in array by its position let product = (item, index) => item * index Js.Array2.mapi([10, 11, 12], product) == [0, 11, 24] @@ -887,7 +981,9 @@ becomes the return value of `reduce()`. See [`Array.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) on MDN. -```res example +## Examples + +```rescript let sumOfSquares = (accumulator, item) => accumulator + item * item Js.Array2.reduce([10, 2, 4], sumOfSquares, 0) == 120 @@ -921,7 +1017,9 @@ becomes the return value of `reducei()`. See [`Array.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) on MDN. -```res example +## Examples + +```rescript // find sum of even-index elements in array let sumOfEvens = (accumulator, item, index) => if mod(index, 2) == 0 { @@ -956,7 +1054,9 @@ on MDN. However, see the last example here and compare it to the example from `reduce()`, where order makes a difference. -```res example +## Examples + +```rescript let sumOfSquares = (accumulator, item) => accumulator + item * item Js.Array2.reduceRight([10, 2, 4], sumOfSquares, 0) == 120 @@ -986,7 +1086,9 @@ on MDN. However, there are cases where the order in which items are processed makes a difference. -```res example +## Examples + +```rescript // find sum of even-index elements in array let sumOfEvens = (accumulator, item, index) => if mod(index, 2) == 0 { @@ -1005,7 +1107,9 @@ external reduceRighti: (t<'a>, @uncurry ('b, 'a, int) => 'b, 'b) => 'b = "reduce Returns `true` if the predicate function given as the second argument to `some()` returns `true` for any element in the array; `false` otherwise. -```res example +## Examples + +```rescript let isEven = x => mod(x, 2) == 0 Js.Array2.some([3, 7, 5, 2, 9], isEven) == true @@ -1021,7 +1125,9 @@ Returns `true` if the predicate function given as the second argument to predicate function has two arguments: an item from the array and the index value -```res example +## Examples + +```rescript // Does any string in the array // have the same length as its index? @@ -1043,7 +1149,9 @@ external somei: (t<'a>, @uncurry ('a, int) => bool) => bool = "some" Returns the value at the given position in the array if the position is in bounds; returns the JavaScript value `undefined` otherwise. -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103] Js.Array2.unsafe_get(arr, 3) == 103 Js.Array2.unsafe_get(arr, 4) // returns undefined @@ -1057,7 +1165,9 @@ If the index is out of bounds, well, “here there be dragons.“ *This function modifies the original array.* -```res example +## Examples + +```rescript let arr = [100, 101, 102, 103] Js.Array2.unsafe_set(arr, 3, 99) // result is [100, 101, 102, 99]; diff --git a/jscomp/others/js_cast.resi b/jscomp/others/js_cast.resi index 04daff5e39..8ef323b732 100644 --- a/jscomp/others/js_cast.resi +++ b/jscomp/others/js_cast.resi @@ -23,23 +23,26 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Safe cast between OCaml values which share the same - runtime representation +Safe cast between OCaml values which share the same +runtime representation - Different OCaml types might share the same represention in the - ReScript runtime; while this is a compiler internal knowledge, - applications might benefit from having a safe and zero cost - conversion between those types. +Different OCaml types might share the same represention in the +ReScript runtime; while this is a compiler internal knowledge, +applications might benefit from having a safe and zero cost +conversion between those types. - This modules acts as the **single place** for such conversion. +This modules acts as the **single place** for such conversion. - If for any reason, the runtime representation changes, those function - will be modified accordingly. +If for any reason, the runtime representation changes, those function +will be modified accordingly. */ -/** `intOfBool b` returns `1` for when `b` is `true` and `0` when `b` is - `false` */ +/** +`intOfBool(b)` returns `1` for when `b` is `true` and `0` when `b` is `false` +*/ external intOfBool: bool => int = "%identity" -/** `floatOfInt i` returns the float value of `i` */ +/** +`floatOfInt(i)` returns the float value of `i` +*/ external floatOfInt: int => float = "%identity" diff --git a/jscomp/others/js_date.res b/jscomp/others/js_date.res index 352deebd4d..2a7b6be24b 100644 --- a/jscomp/others/js_date.res +++ b/jscomp/others/js_date.res @@ -37,7 +37,9 @@ Returns the primitive value of this date, equivalent to `getTime()`. (See [`Date.valueOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/valueOf) on MDN.) -```res example +## Examples + +```rescript Js.Date.valueOf(exampleDate) == 123456654321.0 ``` */ @@ -49,7 +51,9 @@ Returns a date representing the current time. See [`Date()` Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) on MDN. -```res example +## Examples + +```rescript let now = Js.Date.make() ``` */ @@ -62,7 +66,9 @@ milliseconds since the epoch. See [`Date()` Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) on MDN. -```res example +## Examples + +```rescript Js.Date.fromFloat(123456654321.0) == exampleDate ``` */ @@ -76,7 +82,9 @@ Returns `NaN` if given an invalid date string. According to the [`Date()` Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) documentation on MDN, its use is discouraged. -```res example +## Examples + +```rescript Js.Date.fromString("Thu, 29 Nov 1973 21:30:54.321 GMT") == exampleDate Js.Date.fromString("1973-11-29T21:30:54.321Z00:00") == exampleDate Js.Date.fromString("Thor, 32 Lok -19 60:70:80 XYZ") // returns NaN @@ -92,7 +100,9 @@ year in the current time zone. Fractional parts of arguments are ignored. See Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) on MDN. -```res example +## Examples + +```rescript let november1 = Js.Date.makeWithYM(~year=2020.0, ~month=10.0, ()) ``` */ @@ -144,7 +154,9 @@ parts of arguments are ignored. See [`Date()` Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) on MDN. -```res example +## Examples + +```rescript Js.Date.makeWithYMDHMS( ~year=1973.0, ~month=11.0, @@ -174,7 +186,9 @@ of arguments are ignored. See [`Date.UTC`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/UTC) on MDN. -```res example +## Examples + +```rescript let november1 = Js.Date.utcWithYM(~year=2020.0, ~month=10.0, ()) ``` */ @@ -264,7 +278,9 @@ current time zone. See [`Date.getDate`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getDate) on MDN. -```res example +## Examples + +```rescript Js.Date.getDate(exampleDate) == 29.0 ``` */ @@ -277,7 +293,9 @@ Sunday. The argument is evaluated in the current time zone. See [`Date.getDay`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getDay) on MDN. -```res example +## Examples + +```rescript Js.Date.getDay(exampleDate) == 4.0 ``` */ @@ -290,7 +308,9 @@ argument is evaluated in the current time zone. See [`Date.getFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getFullYear) on MDN. -```res example +## Examples + +```rescript Js.Date.getFullYear(exampleDate) == 1973.0 ``` */ @@ -302,7 +322,9 @@ Returns the hours for its argument, evaluated in the current time zone. See [`Date.getHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getHours) on MDN. -```res example +## Examples + +```rescript Js.Date.getHours(exampleDate) == 22.0 // Vienna is in GMT+01:00 ``` */ @@ -315,7 +337,9 @@ time zone. See [`Date.getMilliseconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getMilliseconds) on MDN. -```res example +## Examples + +```rescript Js.Date.getMilliseconds(exampleDate) == 321.0 ``` */ @@ -328,7 +352,9 @@ zone. See [`Date.getMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getMinutes) on MDN. -```res example +## Examples + +```rescript Js.Date.getMinutes(exampleDate) == 30.0 ``` */ @@ -341,7 +367,9 @@ zone. January is month zero. See [`Date.getMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getMonth) on MDN. -```res example +## Examples + +```rescript Js.Date.getMonth(exampleDate) == 10.0 ``` */ @@ -353,7 +381,9 @@ Returns the seconds for its argument, evaluated in the current time zone. See [`Date.getSeconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getSeconds) on MDN. -```res example +## Examples + +```rescript Js.Date.getSeconds(exampleDate) == 54.0 ``` */ @@ -365,7 +395,9 @@ Returns the number of milliseconds since Unix epoch, evaluated in UTC. See [`Date.getTime`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime) on MDN. -```res example +## Examples + +```rescript Js.Date.getTime(exampleDate) == 123456654321.0 ``` */ @@ -377,7 +409,9 @@ Returns the time zone offset in minutes from the current time zone to UTC. See [`Date.getTimezoneOffset`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset) on MDN. -```res example +## Examples + +```rescript Js.Date.getTimezoneOffset(exampleDate) == -60.0 ``` */ @@ -389,7 +423,9 @@ Returns the day of the month of the argument, evaluated in UTC. See [`Date.getUTCDate`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCDate) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCDate(exampleDate) == 29.0 ``` */ @@ -402,7 +438,9 @@ return value is 0.0-6.0, where Sunday is zero. See [`Date.getUTCDay`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCDay) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCDay(exampleDate) == 4.0 ``` */ @@ -415,7 +453,9 @@ argument is evaluated in UTC. See [`Date.getUTCFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCFullYear) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCFullYear(exampleDate) == 1973.0 ``` */ @@ -427,7 +467,9 @@ Returns the hours for its argument, evaluated in the current time zone. See [`Date.getUTCHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCHours) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCHours(exampleDate) == 21.0 ``` */ @@ -439,7 +481,9 @@ Returns the number of milliseconds for its argument, evaluated in UTC. See [`Date.getUTCMilliseconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCMilliseconds) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCMilliseconds(exampleDate) == 321.0 ``` */ @@ -451,7 +495,9 @@ Returns the number of minutes for its argument, evaluated in UTC. See [`Date.getUTCMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCMinutes) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCMinutes(exampleDate) == 30.0 ``` */ @@ -464,7 +510,9 @@ month zero. See [`Date.getUTCMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCMonth) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCMonth(exampleDate) == 10.0 ``` */ @@ -476,7 +524,9 @@ Returns the seconds for its argument, evaluated in UTC. See [`Date.getUTCSeconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getUTCSeconds) on MDN. -```res example +## Examples + +```rescript Js.Date.getUTCSeconds(exampleDate) == 54.0 ``` */ @@ -493,7 +543,9 @@ See [`Date.setDate`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setDate) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let twoWeeksBefore = Js.Date.setDate(date1, 15.0) date1 == Js.Date.fromString("1973-11-15T21:30:54.321Z00:00") @@ -510,7 +562,9 @@ the updated `Date`. *This function modifies the original `Date`.* See [`Date.setFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setFullYear) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let nextYear = Js.Date.setFullYear(date1, 1974.0) date1 == Js.Date.fromString("1974-11-15T21:30:54.321Z00:00") @@ -528,7 +582,9 @@ See [`Date.setFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setFullYear) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let future = Js.Date.setFullYearM(date1, ~year=1974.0, ~month=0.0, ()) date1 == Js.Date.fromString("1974-01-22T21:30:54.321Z00:00") @@ -546,7 +602,9 @@ original `Date`.* See [`Date.setFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setFullYear) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let future = Js.Date.setFullYearMD(date1, ~year=1974.0, ~month=0.0, ~date=7.0, ()) date1 == Js.Date.fromString("1974-01-07T21:30:54.321Z00:00") @@ -564,7 +622,9 @@ the updated `Date`. *This function modifies the original `Date`.* See [`Date.setHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let nextHour = Js.Date.setHours(date1, 22.0) date1 == Js.Date.fromString("1973-11-29T22:30:54.321Z00:00") @@ -582,7 +642,9 @@ original `Date`.* See [`Date.setHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setHoursM(date1, ~hours=22.0, ~minutes=46.0, ()) date1 == Js.Date.fromString("1973-11-29T22:46:54.321Z00:00") @@ -600,7 +662,9 @@ original `Date`.* See [`Date.setHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setHoursMS(date1, ~hours=22.0, ~minutes=46.0, ~seconds=37.0, ()) date1 == Js.Date.fromString("1973-11-29T22:46:37.321Z00:00") @@ -619,7 +683,9 @@ the original `Date`.* See [`Date.setHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setHoursMSMs( date1, @@ -651,7 +717,9 @@ See [`Date.setMilliseconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMilliseconds) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setMilliseconds(date1, 494.0) date1 == Js.Date.fromString("1973-11-29T21:30:54.494Z00:00") @@ -668,7 +736,9 @@ the updated `Date`. *This function modifies the original `Date`.* See [`Date.setMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMinutes) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setMinutes(date1, 34.0) date1 == Js.Date.fromString("1973-11-29T21:34:54.494Z00:00") @@ -686,7 +756,9 @@ original `Date`.* See [`Date.setMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMinutes) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setMinutesS(date1, ~minutes=34.0, ~seconds=56.0, ()) date1 == Js.Date.fromString("1973-11-29T21:34:56.494Z00:00") @@ -704,7 +776,9 @@ original `Date`.* See [`Date.setMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMinutes) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setMinutesSMs( date1, @@ -728,7 +802,9 @@ the updated `Date`. *This function modifies the original `Date`.* See [`Date.setMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMonth) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setMonth(date1, 11.0) date1 == Js.Date.fromString("1973-12-29T21:34:56.789Z00:00") @@ -746,7 +822,9 @@ original `Date`.* See [`Date.setMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMonth) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setMonthD(date1, ~month=11.0, ~date=8.0, ()) date1 == Js.Date.fromString("1973-12-08T21:34:56.789Z00:00") @@ -763,7 +841,9 @@ the updated `Date`. *This function modifies the original `Date`.* See [`Date.setSeconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setSeconds) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setSeconds(date1, 56.0) date1 == Js.Date.fromString("1973-12-29T21:30:56.321Z00:00") @@ -781,7 +861,9 @@ original `Date`.* See [`Date.setSeconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setSeconds) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setSecondsMs(date1, ~seconds=56.0, ~milliseconds=789.0, ()) date1 == Js.Date.fromString("1973-12-29T21:30:56.789Z00:00") @@ -798,7 +880,9 @@ function modifies the original `Date`.* See [`Date.setTime`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setTime) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setTime(date1, 198765432101.0) @@ -816,7 +900,9 @@ updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCDate`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCDate) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let twoWeeksBefore = Js.Date.setUTCDate(date1, 15.0) date1 == Js.Date.fromString("1973-11-15T21:30:54.321Z00:00") @@ -833,7 +919,9 @@ UTC. Returns the number of milliseconds since the epoch of the updated `Date`. [`Date.setUTCFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCFullYear) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let nextYear = Js.Date.setUTCFullYear(date1, 1974.0) date1 == Js.Date.fromString("1974-11-15T21:30:54.321Z00:00") @@ -850,7 +938,9 @@ updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCFullYear) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let future = Js.Date.setUTCFullYearM(date1, ~year=1974.0, ~month=0.0, ()) date1 == Js.Date.fromString("1974-01-22T21:30:54.321Z00:00") @@ -868,7 +958,9 @@ See [`Date.setUTCFullYear`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCFullYear) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let future = Js.Date.setUTCFullYearMD(date1, ~year=1974.0, ~month=0.0, ~date=7.0, ()) date1 == Js.Date.fromString("1974-01-07T21:30:54.321Z00:00") @@ -886,7 +978,9 @@ UTC. Returns the number of milliseconds since the epoch of the updated `Date`. [`Date.setUTCHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let nextHour = Js.Date.setUTCHours(date1, 22.0) date1 == Js.Date.fromString("1973-11-29T22:30:54.321Z00:00") @@ -903,7 +997,9 @@ of the updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCHoursM(date1, ~hours=22.0, ~minutes=46.0, ()) date1 == Js.Date.fromString("1973-11-29T22:46:54.321Z00:00") @@ -922,7 +1018,9 @@ See [`Date.setUTCHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCHoursMS(date1, ~hours=22.0, ~minutes=46.0, ~seconds=37.0, ()) date1 == Js.Date.fromString("1973-11-29T22:46:37.321Z00:00") @@ -941,7 +1039,9 @@ since the epoch of the updated `Date`. *This function modifies the original [`Date.setUTCHours`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCHours) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCHoursMSMs( date1, @@ -972,7 +1072,9 @@ updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCMilliseconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCMilliseconds) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCMilliseconds(date1, 494.0) date1 == Js.Date.fromString("1973-11-29T21:30:54.494Z00:00") @@ -989,7 +1091,9 @@ the updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCMinutes) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCMinutes(date1, 34.0) date1 == Js.Date.fromString("1973-11-29T21:34:54.494Z00:00") @@ -1006,7 +1110,9 @@ of the updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCMinutes) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCMinutesS(date1, ~minutes=34.0, ~seconds=56.0, ()) date1 == Js.Date.fromString("1973-11-29T21:34:56.494Z00:00") @@ -1024,7 +1130,9 @@ See [`Date.setUTCMinutes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCMinutes) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCMinutesSMs( date1, @@ -1053,7 +1161,9 @@ UTC. Returns the number of milliseconds since the epoch of the updated `Date`. [`Date.setUTCMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCMonth) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCMonth(date1, 11.0) date1 == Js.Date.fromString("1973-12-29T21:34:56.789Z00:00") @@ -1070,7 +1180,9 @@ of the updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCMonth`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCMonth) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCMonthD(date1, ~month=11.0, ~date=8.0, ()) date1 == Js.Date.fromString("1973-12-08T21:34:56.789Z00:00") @@ -1087,7 +1199,9 @@ to UTC. Returns the number of milliseconds since the epoch of the updated [`Date.setUTCSeconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCSeconds) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCSeconds(date1, 56.0) date1 == Js.Date.fromString("1973-12-29T21:30:56.321Z00:00") @@ -1104,7 +1218,9 @@ of the updated `Date`. *This function modifies the original `Date`.* See [`Date.setUTCSeconds`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setUTCSeconds) on MDN. -```res example +## Examples + +```rescript let date1 = Js.Date.fromFloat(123456654321.0) // 29 November 1973 21:30:54.321 GMT let futureTime = Js.Date.setUTCSecondsMs(date1, ~seconds=56.0, ~milliseconds=789.0, ()) date1 == Js.Date.fromString("1973-12-29T21:30:56.789Z00:00") @@ -1126,7 +1242,9 @@ Returns the date (day of week, year, month, and day of month) portion of a [`Date.toDateString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toDateString) on MDN. -```res example +## Examples + +```rescript Js.Date.toDateString(exampleDate) == "Thu Nov 29 1973" ``` */ @@ -1140,7 +1258,9 @@ Returns a simplified version of the ISO 8601 format for the date. See [`Date.toISOString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) on MDN. -```res example +## Examples + +```rescript Js.Date.toISOString(exampleDate) == "1973-11-29T21:30:54.321Z" ``` */ @@ -1168,7 +1288,9 @@ format. See [`Date.toLocaleDateString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString) on MDN. -```res example +## Examples + +```rescript Js.Date.toLocaleDateString(exampleDate) == "11/29/1973" // for en_US.utf8 Js.Date.toLocaleDateString(exampleDate) == "29.11.73" // for de_DE.utf8 ``` @@ -1184,7 +1306,9 @@ See [`Date.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString) on MDN. -```res example +## Examples + +```rescript Js.Date.toLocaleString(exampleDate) == "11/29/1973, 10:30:54 PM" // for en_US.utf8 Js.Date.toLocaleString(exampleDate) == "29.11.1973, 22:30:54" // for de_DE.utf8 ``` @@ -1199,7 +1323,9 @@ Returns the time of day for the given `Date` in the current locale format. See [`Date.toLocaleTimeString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString) on MDN. -```res example +## Examples + +```rescript Js.Date.toLocaleString(exampleDate) == "10:30:54 PM" // for en_US.utf8 Js.Date.toLocaleString(exampleDate) == "22:30:54" // for de_DE.utf8 ``` @@ -1215,7 +1341,9 @@ the current locale and time zone. See [`Date.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toString) on MDN. -```res example +## Examples + +```rescript Js.Date.toString( exampleDate, ) == "Thu Nov 29 1973 22:30:54 GMT+0100 (Central European Standard Time)" @@ -1230,7 +1358,9 @@ current locale and time zone. See [`Date.toTimeString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toTimeString) on MDN. -```res example +## Examples + +```rescript Js.Date.toTimeString(exampleDate) == "22:30:54 GMT+0100 (Central European Standard Time)" ``` */ @@ -1243,7 +1373,9 @@ the current locale and UTC (GMT time zone). See [`Date.toUTCString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toUTCString) on MDN. -```res example +## Examples + +```rescript Js.Date.toUTCString(exampleDate) == "Thu, 29 Nov 1973 21:30:54 GMT" ``` */ diff --git a/jscomp/others/js_dict.resi b/jscomp/others/js_dict.resi index 23e1f11112..c9c4584f44 100644 --- a/jscomp/others/js_dict.resi +++ b/jscomp/others/js_dict.resi @@ -27,7 +27,9 @@ Provide utilities for JS dictionary object. **Note:** This module's examples will assume this predeclared dictionary: -```res prelude +## Examples + +```rescript let ages = Js.Dict.fromList(list{("Maria", 30), ("Vinh", 22), ("Fred", 49)}) ``` */ @@ -48,7 +50,9 @@ type key = string `Js.Dict.get(key)` returns `None` if the key is not found in the dictionary, `Some(value)` otherwise. -```res example +## Examples + +```rescript Js.Dict.get(ages, "Vinh") == Some(22) Js.Dict.get(ages, "Paul") == None ``` @@ -59,7 +63,9 @@ let get: (t<'a>, key) => option<'a> /** `Js.Dict.unsafeGet(key)` returns the value if the key exists, otherwise an `undefined` value is returned. Use this only when you are sure the key exists (i.e. when having used the `keys()` function to check that the key is valid). -```res example +## Examples + +```rescript Js.Dict.unsafeGet(ages, "Fred") == 49 Js.Dict.unsafeGet(ages, "Paul") // returns undefined ``` @@ -73,7 +79,9 @@ the key does not exist, and entry will be created for it. *This function modifies the original dictionary.* -```res example +## Examples + +```rescript Js.Dict.set(ages, "Maria", 31) Js.log(ages == Js.Dict.fromList(list{("Maria", 31), ("Vinh", 22), ("Fred", 49)})) @@ -87,7 +95,9 @@ external set: (t<'a>, key, 'a) => unit = "" /** Returns all the keys in the dictionary `dict`. -```res example +## Examples + +```rescript Js.Dict.keys(ages) == ["Maria", "Vinh", "Fred"] ``` */ @@ -102,7 +112,9 @@ let unsafeDeleteKey: (. t, string) => unit /** Returns an array of key/value pairs in the given dictionary (ES2017). -```res example +## Examples + +```rescript Js.Dict.entries(ages) == [("Maria", 30), ("Vinh", 22), ("Fred", 49)] ``` */ @@ -111,7 +123,9 @@ let entries: t<'a> => array<(key, 'a)> /** Returns the values in the given dictionary (ES2017). -```res example +## Examples + +```rescript Js.Dict.values(ages) == [30, 22, 49] ``` */ @@ -121,7 +135,9 @@ let values: t<'a> => array<'a> Creates a new dictionary containing each (key, value) pair in its list argument. -```res example +## Examples + +```rescript let capitals = Js.Dict.fromList(list{("Japan", "Tokyo"), ("France", "Paris"), ("Egypt", "Cairo")}) ``` */ @@ -131,7 +147,9 @@ let fromList: list<(key, 'a)> => t<'a> Creates a new dictionary containing each (key, value) pair in its array argument. -```res example +## Examples + +```rescript let capitals2 = Js.Dict.fromArray([("Germany", "Berlin"), ("Burkina Faso", "Ouagadougou")]) ``` */ @@ -141,7 +159,9 @@ let fromArray: array<(key, 'a)> => t<'a> `map(f, dict)` maps `dict` to a new dictionary with the same keys, using the function `f` to map each value. -```res example +## Examples + +```rescript let prices = Js.Dict.fromList(list{("pen", 1.00), ("book", 5.00), ("stapler", 7.00)}) let discount = (. price) => price *. 0.90 diff --git a/jscomp/others/js_exn.resi b/jscomp/others/js_exn.resi index 7dbae85bf6..87ce8ca887 100644 --- a/jscomp/others/js_exn.resi +++ b/jscomp/others/js_exn.resi @@ -22,7 +22,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Provide utilities for dealing with JS exceptions. */ +/*** +Provide utilities for dealing with JS exceptions. +*/ /** Represents a JS exception */ type t @@ -40,25 +42,27 @@ external asJsExn: exn => option = "?as_js_exn" external isCamlExceptionOrOpenVariant: 'a => bool = "?is_extension" /** - `anyToExnInternal obj` will take any value `obj` and wrap it - in a Js.Exn.Error if given value is not an exn already. If - `obj` is an exn, it will return `obj` without any changes. +`anyToExnInternal(obj)` will take any value `obj` and wrap it +in a Js.Exn.Error if given value is not an exn already. If +`obj` is an exn, it will return `obj` without any changes. + +This function is mostly useful for cases where you want to unify a type of a value +that potentially is either exn, a JS error, or any other JS value really (e.g. for +a value passed to a Promise.catch callback) - This function is mostly useful for cases where you want to unify a type of a value - that potentially is either exn, a JS error, or any other JS value really (e.g. for - a value passed to a Promise.catch callback) +**IMPORTANT**: This is an internal API and may be changed / removed any time in the future. - **IMPORTANT**: This is an internal API and may be changed / removed any time in the future. +## Examples - ``` - switch (Js.Exn.unsafeAnyToExn("test")) { - | Js.Exn.Error(v) => - switch(Js.Exn.message(v)) { - | Some(str) => Js.log("We won't end up here") - | None => Js.log2("We will land here: ", v) - } +```rescript +switch (Js.Exn.unsafeAnyToExn("test")) { +| Js.Exn.Error(v) => + switch(Js.Exn.message(v)) { + | Some(str) => Js.log("We won't end up here") + | None => Js.log2("We will land here: ", v) } - ``` +} +``` */ external anyToExnInternal: 'a => exn = "#wrap_exn" diff --git a/jscomp/others/js_float.res b/jscomp/others/js_float.res index fbffdaf3c6..0b632058ce 100644 --- a/jscomp/others/js_float.res +++ b/jscomp/others/js_float.res @@ -22,163 +22,147 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Provide utilities for JS float. */ +/*** +Provide utilities for JS float. +*/ @val /** - The special value "Not a Number" - - **See:** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN) +The special value "Not a Number". See [`NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN) on MDN. */ external _NaN: float = "NaN" @val @scope("Number") /** - Tests if the given value is `_NaN` - - Note that both `_NaN = _NaN` and `_NaN == _NaN` will return `false`. `isNaN` is - therefore necessary to test for `_NaN`. +Tests if the given value is `_NaN` - **return** `true` if the given value is `_NaN`, `false` otherwise - - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN) +Note that both `_NaN = _NaN` and `_NaN == _NaN` will return `false`. `isNaN` is +therefore necessary to test for `_NaN`. Return `true` if the given value is +`_NaN`, `false` otherwise. See [`isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN) on MDN. */ external isNaN: float => bool = "isNaN" @val @scope("Number") /** - Tests if the given value is finite - - **return** `true` if the given value is a finite number, `false` otherwise +Tests if the given value is finite. Return `true` if the given value is a finite +number, `false` otherwise. See [`isFinite`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite) on MDN. - ```res example - /* returns [false] */ - Js.Float.isFinite(infinity) +## Examples - /* returns [false] */ - Js.Float.isFinite(neg_infinity) +```rescript +/* returns [false] */ +Js.Float.isFinite(infinity) - /* returns [false] */ - Js.Float.isFinite(Js.Float._NaN) +/* returns [false] */ +Js.Float.isFinite(neg_infinity) - /* returns [true] */ - Js.Float.isFinite(1234.) - ``` +/* returns [false] */ +Js.Float.isFinite(Js.Float._NaN) - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite) +/* returns [true] */ +Js.Float.isFinite(1234.) +``` */ external isFinite: float => bool = "isFinite" @send /** - Formats a `float` using exponential (scientific) notation - - **return** a `string` representing the given value in exponential notation +Formats a `float` using exponential (scientific) notation. Return a +`string` representing the given value in exponential notation. Raise +RangeError if digits is not in the range [0, 20] (inclusive). See [`toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) on MDN. - **raise** RangeError if digits is not in the range [0, 20] (inclusive) +## Examples - ```res example - /* prints "7.71234e+1" */ - Js.Float.toExponential(77.1234)->Js.log +```rescript +/* prints "7.71234e+1" */ +Js.Float.toExponential(77.1234)->Js.log - /* prints "7.7e+1" */ - Js.Float.toExponential(77.)->Js.log - ``` - - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) +/* prints "7.7e+1" */ +Js.Float.toExponential(77.)->Js.log +``` */ external toExponential: float => string = "toExponential" @send /** - Formats a `float` using exponential (scientific) notation - - **digits** specifies how many digits should appear after the decimal point. The - value must be in the range [0, 20] (inclusive). - - **return** a `string` representing the given value in exponential notation - - The output will be rounded or padded with zeroes if necessary. - - **raise** RangeError if digits is not in the range [0, 20] (inclusive) - - ```res example - /* prints "7.71e+1" */ - Js.Float.toExponentialWithPrecision(77.1234, ~digits=2)->Js.log - ``` - - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) +Formats a `float` using exponential (scientific) notation. `digits` specifies +how many digits should appear after the decimal point. The value must be in +the range [0, 20] (inclusive). Return a `string` representing the given value +in exponential notation. The output will be rounded or padded with zeroes if +necessary. Raise RangeError if `digits` is not in the range [0, 20] (inclusive). +See [`toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) on MDN. + +## Examples + +```rescript +/* prints "7.71e+1" */ +Js.Float.toExponentialWithPrecision(77.1234, ~digits=2)->Js.log +``` */ external toExponentialWithPrecision: (float, ~digits: int) => string = "toExponential" @send /** - Formats a `float` using fixed point notation - - **return** a `string` representing the given value in fixed-point notation (usually) - - **raise** RangeError if digits is not in the range [0, 20] (inclusive) +Formats a `float` using fixed point notation. Return a `string` representing the +given value in fixed-point notation (usually). Raise RangeError if digits is not +in the range [0, 20] (inclusive). See [`toFixed`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) on MDN. - ```res example - /* prints "12346" (note the rounding) */ - Js.Float.toFixed(12345.6789)->Js.log +## Examples - /* print "1.2e+21" */ - Js.Float.toFixed(1.2e21)->Js.log - ``` +```rescript +/* prints "12346" (note the rounding) */ +Js.Float.toFixed(12345.6789)->Js.log - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) +/* print "1.2e+21" */ +Js.Float.toFixed(1.2e21)->Js.log +``` */ external toFixed: float => string = "toFixed" @send /** - Formats a `float` using fixed point notation +Formats a `float` using fixed point notation. `digits` specifies how many digits +should appear after the decimal point. The value must be in the range [0, 20] +(inclusive). Defaults to `0`. Return a `string` representing the given value in +fixed-point notation (usually). See [`toFixed`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) on MDN. - **digits** specifies how many digits should appear after the decimal point. The - value must be in the range [0, 20] (inclusive). Defaults to `0`. +The output will be rounded or padded with zeroes if necessary. - **return** a `string` representing the given value in fixed-point notation (usually) +Raise RangeError if digits is not in the range [0, 20] (inclusive) - The output will be rounded or padded with zeroes if necessary. +## Examples - **raise** RangeError if digits is not in the range [0, 20] (inclusive) +```rescript +/* prints "12345.7" (note the rounding) */ +Js.Float.toFixedWithPrecision(12345.6789, ~digits=1)->Js.log - ```res example - /* prints "12345.7" (note the rounding) */ - Js.Float.toFixedWithPrecision(12345.6789, ~digits=1)->Js.log - - /* prints "0.00" (note the added zeroes) */ - Js.Float.toFixedWithPrecision(0., ~digits=2)->Js.log - ``` - - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) +/* prints "0.00" (note the added zeroes) */ +Js.Float.toFixedWithPrecision(0., ~digits=2)->Js.log +``` */ external toFixedWithPrecision: (float, ~digits: int) => string = "toFixed" @send /** - Formats a `float` using some fairly arbitrary rules - - **return** a `string` representing the given value in fixed-point (usually) +Formats a `float` using some fairly arbitrary rules. Return a `string` +representing the given value in fixed-point (usually). `toPrecision` differs +from `Js.Float.toFixed` in that the former will format the number with full +precision, while the latter will not output any digits after the decimal point. +See [`toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN. - `toPrecision` differs from `toFixed` in that the former will format the number - with full precision, while the latter will not output any digits after the - decimal point. +Raise RangeError if digits is not in the range accepted by this function (what do you mean "vague"?) - **raise** RangeError if digits is not in the range accepted by this function (what do you mean "vague"?) +## Examples - ```res example - /* prints "12345.6789" */ - Js.Float.toPrecision(12345.6789)->Js.log +```rescript +/* prints "12345.6789" */ +Js.Float.toPrecision(12345.6789)->Js.log - /* print "1.2e+21" */ - Js.Float.toPrecision(1.2e21)->Js.log - ``` - - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) +/* print "1.2e+21" */ +Js.Float.toPrecision(1.2e21)->Js.log +``` */ external toPrecision: float => string = "toPrecision" @@ -186,110 +170,105 @@ external toPrecision: float => string = "toPrecision" @send /** - Formats a `float` using some fairly arbitrary rules - - **digits** specifies how many digits should appear in total. The - value must between 0 and some arbitrary number that's hopefully at least larger - than 20 (for Node it's 21. Why? Who knows). - - **return** a `string` representing the given value in fixed-point or scientific notation +Formats a `float` using some fairly arbitrary rules. `digits` specifies how many +digits should appear in total. The value must between 0 and some arbitrary number +that's hopefully at least larger than 20 (for Node it's 21. Why? Who knows). +See [`toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN. - The output will be rounded or padded with zeroes if necessary. +Return a `string` representing the given value in fixed-point or scientific +notation. The output will be rounded or padded with zeroes if necessary. - `toPrecisionWithPrecision` differs from `toFixedWithPrecision` in that the former - will count all digits against the precision, while the latter will count only - the digits after the decimal point. `toPrecisionWithPrecision` will also use - scientific notation if the specified precision is less than the number for digits - before the decimal point. +`toPrecisionWithPrecision` differs from `toFixedWithPrecision` in that the former +will count all digits against the precision, while the latter will count only +the digits after the decimal point. `toPrecisionWithPrecision` will also use +scientific notation if the specified precision is less than the number for digits +before the decimal point. - **raise** RangeError if digits is not in the range accepted by this function (what do you mean "vague"?) +Raise RangeError if digits is not in the range accepted by this function (what do you mean "vague"?) - ```res example - /* prints "1e+4" */ - Js.Float.toPrecisionWithPrecision(12345.6789, ~digits=1)->Js.log +## Examples - /* prints "0.0" */ - Js.Float.toPrecisionWithPrecision(0., ~digits=2)->Js.log - ``` +```rescript +/* prints "1e+4" */ +Js.Float.toPrecisionWithPrecision(12345.6789, ~digits=1)->Js.log - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) +/* prints "0.0" */ +Js.Float.toPrecisionWithPrecision(0., ~digits=2)->Js.log +``` */ external toPrecisionWithPrecision: (float, ~digits: int) => string = "toPrecision" @send /** - Formats a `float` as a string +Formats a `float` as a string. Return a `string` representing the given value in +fixed-point (usually). See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) on MDN. - **return** a `string` representing the given value in fixed-point (usually) +## Examples - ```res example - /* prints "12345.6789" */ - Js.Float.toString(12345.6789)->Js.log - ``` - - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) +```rescript +/* prints "12345.6789" */ +Js.Float.toString(12345.6789)->Js.log +``` */ external toString: float => string = "toString" @send /** - Formats a `float` as a string - - **radix** specifies the radix base to use for the formatted number. The - value must be in the range [2, 36] (inclusive). - - **return** a `string` representing the given value in fixed-point (usually) +Formats a `float` as a string. `radix` specifies the radix base to use for the +formatted number. The value must be in the range [2, 36] (inclusive). Return a +`string` representing the given value in fixed-point (usually). See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) on MDN. - **raise** RangeError if radix is not in the range [2, 36] (inclusive) +Raise RangeError if radix is not in the range [2, 36] (inclusive) - ```res example - /* prints "110" */ - Js.Float.toStringWithRadix(6., ~radix=2)->Js.log +## Examples - /* prints "11.001000111101011100001010001111010111000010100011111" */ - Js.Float.toStringWithRadix(3.14, ~radix=2)->Js.log +```rescript +/* prints "110" */ +Js.Float.toStringWithRadix(6., ~radix=2)->Js.log - /* prints "deadbeef" */ - Js.Float.toStringWithRadix(3735928559., ~radix=16)->Js.log +/* prints "11.001000111101011100001010001111010111000010100011111" */ +Js.Float.toStringWithRadix(3.14, ~radix=2)->Js.log - /* prints "3f.gez4w97ry0a18ymf6qadcxr" */ - Js.Float.toStringWithRadix(123.456, ~radix=36)->Js.log - ``` +/* prints "deadbeef" */ +Js.Float.toStringWithRadix(3735928559., ~radix=16)->Js.log - **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) +/* prints "3f.gez4w97ry0a18ymf6qadcxr" */ +Js.Float.toStringWithRadix(123.456, ~radix=36)->Js.log +``` */ external toStringWithRadix: (float, ~radix: int) => string = "toString" @val /** - Parses the given `string` into a `float` using JavaScript semantics +Parses the given `string` into a `float` using JavaScript semantics. Return the +number as a `float` if successfully parsed, `_NaN` otherwise. - **return** the number as a `float` if successfully parsed, `_NaN` otherwise. +## Examples - ```res example - /* returns 123 */ - Js.Float.fromString("123") +```rescript +/* returns 123 */ +Js.Float.fromString("123") - /* returns 12.3 */ - Js.Float.fromString("12.3") +/* returns 12.3 */ +Js.Float.fromString("12.3") - /* returns 0 */ - Js.Float.fromString("") +/* returns 0 */ +Js.Float.fromString("") - /* returns 17 */ - Js.Float.fromString("0x11") +/* returns 17 */ +Js.Float.fromString("0x11") - /* returns 3 */ - Js.Float.fromString("0b11") +/* returns 3 */ +Js.Float.fromString("0b11") - /* returns 9 */ - Js.Float.fromString("0o11") +/* returns 9 */ +Js.Float.fromString("0o11") - /* returns [_NaN] */ - Js.Float.fromString("hello") +/* returns [_NaN] */ +Js.Float.fromString("hello") - /* returns [_NaN] */ - Js.Float.fromString("100a") - ``` +/* returns [_NaN] */ +Js.Float.fromString("100a") +``` */ external fromString: string => float = "Number" diff --git a/jscomp/others/js_global.res b/jscomp/others/js_global.res index f0d2c5eb74..901a64d3e4 100644 --- a/jscomp/others/js_global.res +++ b/jscomp/others/js_global.res @@ -22,8 +22,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Contains functions available in the global scope - (`window` in a browser context) */ +/*** +Contains functions available in the global scope (`window` in a browser context) +*/ /** Identify an interval started by `Js.Global.setInterval`. */ type intervalId @@ -35,7 +36,9 @@ type timeoutId /** Clear an interval started by `Js.Global.setInterval` -```res example +## Examples + +```rescript /* API for a somewhat aggressive snoozing alarm clock */ let punchSleepyGuy = () => Js.log("Punch") @@ -60,7 +63,9 @@ external clearInterval: intervalId => unit = "clearInterval" /** Clear a timeout started by `Js.Global.setTimeout`. -```res example +## Examples + +```rescript /* A simple model of a code monkey's brain */ let closeHackerNewsTab = () => Js.log("close") @@ -83,7 +88,9 @@ Repeatedly executes a callback with a specified interval (in milliseconds) between calls. Returns a `Js.Global.intervalId` that can be passed to `Js.Global.clearInterval` to cancel the timeout. -```res example +## Examples + +```rescript /* Will count up and print the count to the console every second */ let count = ref(0) @@ -104,7 +111,9 @@ Repeatedly executes a callback with a specified interval (in milliseconds) between calls. Returns a `Js.Global.intervalId` that can be passed to `Js.Global.clearInterval` to cancel the timeout. -```res example +## Examples + +```rescript /* Will count up and print the count to the console every second */ let count = ref(0) @@ -125,7 +134,9 @@ Execute a callback after a specified delay (in milliseconds). Returns a `Js.Global.timeoutId` that can be passed to `Js.Global.clearTimeout` to cancel the timeout. -```res example +## Examples + +```rescript /* Prints "Timed out!" in the console after one second */ let message = "Timed out!" @@ -141,7 +152,9 @@ Execute a callback after a specified delay (in milliseconds). Returns a `Js.Global.timeoutId` that can be passed to `Js.Global.clearTimeout` to cancel the timeout. -```res example +## Examples + +```rescript /* Prints "Timed out!" in the console after one second */ let message = "Timed out!" @@ -153,32 +166,32 @@ external setTimeoutFloat: (unit => unit, float) => timeoutId = "setTimeout" @val /** - URL-encodes a string. +URL-encodes a string. - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) +See [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) on MDN. */ external encodeURI: string => string = "encodeURI" @val /** - Decodes a URL-enmcoded string produced by `encodeURI` +Decodes a URL-enmcoded string produced by `encodeURI` - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) +See [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) on MDN. */ external decodeURI: string => string = "decodeURI" @val /** - URL-encodes a string, including characters with special meaning in a URI. +URL-encodes a string, including characters with special meaning in a URI. - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) +See [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) on MDN. */ external encodeURIComponent: string => string = "encodeURIComponent" @val /** - Decodes a URL-enmcoded string produced by `encodeURIComponent` +Decodes a URL-enmcoded string produced by `encodeURIComponent` - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) +See [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) on MDN. */ external decodeURIComponent: string => string = "decodeURIComponent" diff --git a/jscomp/others/js_int.res b/jscomp/others/js_int.res index 2400955652..f375b0535a 100644 --- a/jscomp/others/js_int.res +++ b/jscomp/others/js_int.res @@ -22,13 +22,15 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Provide utilities for handling `int`. */ +/*** +Provide utilities for handling `int`. +*/ /* - If we use number, we need coerce to int32 by adding `|0`, - otherwise `+0` can be wrong. - Most JS API is float oriented, it may overflow int32 or - comes with `NAN` +If we use number, we need coerce to int32 by adding `|0`, +otherwise `+0` can be wrong. +Most JS API is float oriented, it may overflow int32 or +comes with `NAN` */ /* + conversion */ @@ -39,9 +41,11 @@ Formats an `int` using exponential (scientific) notation. Returns a `string` representing the given value in exponential notation. Raises `RangeError` if digits is not in the range \[0, 20\] (inclusive). -**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) +See [`toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) on MDN. + +## Examples -```res example +```rescript /* prints "7.7e+1" */ Js.log(Js.Int.toExponential(77)) ``` @@ -58,9 +62,11 @@ Returns a `string` representing the given value in exponential notation. The output will be rounded or padded with zeroes if necessary. Raises `RangeError` if `digits` is not in the range \[0, 20\] (inclusive). -**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) +See [`toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential) on MDN. -```res example +## Examples + +```rescript /* prints "7.70e+1" */ Js.log(Js.Int.toExponentialWithPrecision(77, ~digits=2)) @@ -78,9 +84,11 @@ Returns a `string` representing the given value in fixed-point (usually). `toPrecision` differs from `toFixed` in that the former will format the number with full precision, while the latter will not output any digits after the decimal point. Raises `RangeError` if `digits` is not in the range accepted by this function. -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) +See [`toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN. + +## Examples -```res example +```rescript /* prints "123456789" */ Js.log(Js.Int.toPrecision(123456789)) ``` @@ -101,9 +109,11 @@ The output will be rounded or padded with zeroes if necessary. Raises `RangeError` if `digits` is not in the range accepted by this function. -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) +See [`toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN. -```res example +## Examples + +```rescript /* prints "1.2e+8" */ Js.log(Js.Int.toPrecisionWithPrecision(123456789, ~digits=2)) @@ -118,9 +128,11 @@ external toPrecisionWithPrecision: (int, ~digits: int) => string = "toPrecision" Formats an `int` as a `string`. Returns a `string` representing the given value in fixed-point (usually). -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) +See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) on MDN. + +## Examples -```res example +```rescript /* prints "123456789" */ Js.log(Js.Int.toString(123456789)) ``` @@ -135,9 +147,11 @@ a `string` representing the given value in fixed-point (usually). Raises `RangeError` if `radix` is not in the range \[2, 36\] (inclusive). -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) +See [`toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) on MDN. + +## Examples -```res example +```rescript /* prints "110" */ Js.log(Js.Int.toStringWithRadix(6, ~radix=2)) diff --git a/jscomp/others/js_json.resi b/jscomp/others/js_json.resi index fad033bf14..218d5f5626 100644 --- a/jscomp/others/js_json.resi +++ b/jscomp/others/js_json.resi @@ -23,9 +23,9 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Efficient JSON encoding using JavaScript API +Efficient JSON encoding using JavaScript API - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) +**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) */ /* ## Types */ @@ -64,25 +64,39 @@ type tagged_t = let classify: t => tagged_t -/** `test(v, kind)` returns `true` if `v` is of `kind`. */ +/** +`test(v, kind)` returns `true` if `v` is of `kind`. +*/ let test: ('a, Kind.t<'b>) => bool -/** `decodeString(json)` returns `Some(s)` if `json` is a `string`, `None` otherwise. */ +/** +`decodeString(json)` returns `Some(s)` if `json` is a `string`, `None` otherwise. +*/ let decodeString: t => option -/** `decodeNumber(json)` returns `Some(n)` if `json` is a `number`, `None` otherwise. */ +/** +`decodeNumber(json)` returns `Some(n)` if `json` is a `number`, `None` otherwise. +*/ let decodeNumber: t => option -/** `decodeObject(json)` returns `Some(o)` if `json` is an `object`, `None` otherwise. */ +/** +`decodeObject(json)` returns `Some(o)` if `json` is an `object`, `None` otherwise. +*/ let decodeObject: t => option> -/** `decodeArray(json)` returns `Some(a)` if `json` is an `array`, `None` otherwise. */ +/** +`decodeArray(json)` returns `Some(a)` if `json` is an `array`, `None` otherwise. +*/ let decodeArray: t => option> -/** `decodeBoolean(json)` returns `Some(b)` if `json` is a `boolean`, `None` otherwise. */ +/** +`decodeBoolean(json)` returns `Some(b)` if `json` is a `boolean`, `None` otherwise. +*/ let decodeBoolean: t => option -/** `decodeNull(json)` returns `Some(null)` if `json` is a `null`, `None` otherwise. */ +/** +`decodeNull(json)` returns `Some(null)` if `json` is a `null`, `None` otherwise. +*/ let decodeNull: t => option> /* ## Constructors */ @@ -137,9 +151,11 @@ external objectArray: array> => t = "%identity" Returns a JSON data structure. Raises `SyntaxError` if the given string is not a valid JSON. Note: `SyntaxError` is a JavaScript exception. -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) +See [`parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) on MDN. -```res example +## Examples + +```rescript /* parse a simple JSON string */ let json = try Js.Json.parseExn(` "hello" `) catch { @@ -152,7 +168,7 @@ switch Js.Json.classify(json) { } ``` -```res example +```rescript /* parse a complex JSON string */ let getIds = s => { @@ -188,9 +204,11 @@ external parseExn: string => t = "parse" `stringify(json)` formats the JSON data structure as a `string`. Returns the string representation of a given JSON data structure. -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) +See [`stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on MDN. + +## Examples -```res example +```rescript /* Creates and stringifies a simple JS object */ let dict = Js.Dict.empty() @@ -209,9 +227,11 @@ external stringify: t => string = "stringify" `stringifyWithSpace(json)` formats the JSON data structure as a `string`. Returns the string representation of a given JSON data structure with spacing. -**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) +See [`stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on MDN. -```res example +## Examples + +```rescript /* Creates and stringifies a simple JS object with spacing */ let dict = Js.Dict.empty() @@ -229,7 +249,9 @@ external stringifyWithSpace: (t, @as(json`null`) _, int) => string = "stringify" /** `stringifyAny(value)` formats any value into a JSON string. -```res example +## Examples + +```rescript /* prints `["hello", "world"]` */ Js.log(Js.Json.stringifyAny(["hello", "world"])) ``` @@ -237,19 +259,19 @@ Js.log(Js.Json.stringifyAny(["hello", "world"])) external stringifyAny: 'a => option = "stringify" /** - Best-effort serialization, it tries to seralize as - many objects as possible and deserialize it back +Best-effort serialization, it tries to seralize as +many objects as possible and deserialize it back - It is unsafe in two aspects - - It may throw during parsing - - when you cast it to a specific type, it may have a type mismatch +It is unsafe in two aspects +- It may throw during parsing +- when you cast it to a specific type, it may have a type mismatch */ let deserializeUnsafe: string => 'a /** - It will raise in such situations: - - The object can not be serlialized to a JSON - - There are cycles - - Some JS engines can not stringify deeply nested json objects +It will raise in such situations: +- The object can not be serlialized to a JSON +- There are cycles +- Some JS engines can not stringify deeply nested json objects */ let serializeExn: 'a => string diff --git a/jscomp/others/js_list.resi b/jscomp/others/js_list.resi index 270c59b464..d4c9efa3cd 100644 --- a/jscomp/others/js_list.resi +++ b/jscomp/others/js_list.resi @@ -53,8 +53,7 @@ let iteri: ((. int, 'a) => unit, t<'a>) => unit /** Application order is left to right, tail recurisve */ let foldLeft: ((. 'a, 'b) => 'a, 'a, list<'b>) => 'a -/** Application order is right to left - tail-recursive. */ +/** Application order is right to left tail-recursive. */ let foldRight: ((. 'a, 'b) => 'b, list<'a>, 'b) => 'b let flatten: t> => t<'a> diff --git a/jscomp/others/js_mapperRt.resi b/jscomp/others/js_mapperRt.resi index 554f123f56..6b9dbddfde 100644 --- a/jscomp/others/js_mapperRt.resi +++ b/jscomp/others/js_mapperRt.resi @@ -25,8 +25,7 @@ let raiseWhenNotFound: 'a => 'a /** - `fromInt len array int` - return the mapped `enum` +`fromInt(len, array, int)` return the mapped `enum` */ let fromInt: (int, array, int) => option diff --git a/jscomp/others/js_math.ml b/jscomp/others/js_math.ml index 4f91f239f4..c03ffcb0c5 100644 --- a/jscomp/others/js_math.ml +++ b/jscomp/others/js_math.ml @@ -23,604 +23,634 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) (** - Provide utilities for JS Math. Note: The constants `_E`, `_LN10`, `_LN2`, - `_LOG10E`, `_LOG2E`, `_PI`, `_SQRT1_2`, and `_SQRT2` begin with an underscore - because ReScript variable names cannot begin with a capital letter. (Module - names begin with upper case.) +Provide utilities for JS Math. Note: The constants `_E`, `_LN10`, `_LN2`, +`_LOG10E`, `_LOG2E`, `_PI`, `_SQRT1_2`, and `_SQRT2` begin with an underscore +because ReScript variable names cannot begin with a capital letter. (Module +names begin with upper case.) *) (** - Euler's number; ≈ 2.718281828459045. See - [`Math.E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/E) - on MDN. +Euler's number; ≈ 2.718281828459045. See +[`Math.E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/E) +on MDN. *) external _E : float = "E" [@@bs.val] [@@bs.scope "Math"] (** - Natural logarithm of 2; ≈ 0.6931471805599453. See - [`Math.LN2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LN2) - on MDN. +Natural logarithm of 2; ≈ 0.6931471805599453. See +[`Math.LN2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LN2) +on MDN. *) external _LN2 : float = "LN2" [@@bs.val] [@@bs.scope "Math"] (** - Natural logarithm of 10; ≈ 2.302585092994046. See - [`Math.LN10`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LN10) - on MDN. +Natural logarithm of 10; ≈ 2.302585092994046. See +[`Math.LN10`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LN10) +on MDN. *) external _LN10 : float = "LN10" [@@bs.val] [@@bs.scope "Math"] (** - Base 2 logarithm of E; ≈ 1.4426950408889634. See - [`Math.LOG2E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LOG2E) - on MDN. +Base 2 logarithm of E; ≈ 1.4426950408889634. See +[`Math.LOG2E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LOG2E) +on MDN. *) external _LOG2E : float = "LOG2E" [@@bs.val] [@@bs.scope "Math"] (** - Base 10 logarithm of E; ≈ 0.4342944819032518. See - [`Math.LOG10E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LOG10E) - on MDN. +Base 10 logarithm of E; ≈ 0.4342944819032518. See +[`Math.LOG10E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LOG10E) +on MDN. *) external _LOG10E : float = "LOG10E" [@@bs.val] [@@bs.scope "Math"] (** - Pi - ratio of the circumference to the diameter of a circle; ≈ 3.141592653589793. See - [`Math.PI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/PI) - on MDN. +Pi - ratio of the circumference to the diameter of a circle; ≈ 3.141592653589793. See +[`Math.PI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/PI) +on MDN. *) external _PI : float = "PI" [@@bs.val] [@@bs.scope "Math"] (** - Square root of 1/2; ≈ 0.7071067811865476. See - [`Math.SQRT1_2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/SQRT1_2) - on MDN. +Square root of 1/2; ≈ 0.7071067811865476. See +[`Math.SQRT1_2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/SQRT1_2) +on MDN. *) external _SQRT1_2 : float = "SQRT1_2" [@@bs.val] [@@bs.scope "Math"] (** - Square root of 2; ≈ 1.4142135623730951. See - [`Math.SQRT2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/SQRT2) - on MDN. +Square root of 2; ≈ 1.4142135623730951. See +[`Math.SQRT2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/SQRT2) +on MDN. *) external _SQRT2 : float = "SQRT2" [@@bs.val] [@@bs.scope "Math"] (** - Absolute value for integer argument. See - [`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs) - on MDN. +Absolute value for integer argument. See +[`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs) +on MDN. *) external abs_int : int -> int = "abs" [@@bs.val] [@@bs.scope "Math"] (** - Absolute value for float argument. See - [`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs) - on MDN. +Absolute value for float argument. See +[`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs) +on MDN. *) external abs_float : float -> float = "abs" [@@bs.val] [@@bs.scope "Math"] (** - Arccosine (in radians) of argument; returns `NaN` if the argument is outside - the range [-1.0, 1.0]. See - [`Math.acos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/acos) - on MDN. +Arccosine (in radians) of argument; returns `NaN` if the argument is outside +the range [-1.0, 1.0]. See +[`Math.acos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/acos) +on MDN. *) external acos : float -> float = "acos" [@@bs.val] [@@bs.scope "Math"] (** - Hyperbolic arccosine (in radians) of argument; returns `NaN` if the argument - is less than 1.0. See - [`Math.acosh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/acosh) - on MDN. +Hyperbolic arccosine (in radians) of argument; returns `NaN` if the argument +is less than 1.0. See +[`Math.acosh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/acosh) +on MDN. *) external acosh : float -> float = "acosh" [@@bs.val] [@@bs.scope "Math"] (** - Arcsine (in radians) of argument; returns `NaN` if the argument is outside - the range [-1.0, 1.0]. See - [`Math.asin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/asin) - on MDN. +Arcsine (in radians) of argument; returns `NaN` if the argument is outside +the range [-1.0, 1.0]. See +[`Math.asin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/asin) +on MDN. *) external asin : float -> float = "asin" [@@bs.val] [@@bs.scope "Math"] (** - Hyperbolic arcsine (in radians) of argument. See - [`Math.asinh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/asinh) - on MDN. +Hyperbolic arcsine (in radians) of argument. See +[`Math.asinh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/asinh) +on MDN. *) external asinh : float -> float = "asinh" [@@bs.val] [@@bs.scope "Math"] (** - Arctangent (in radians) of argument. See - [`Math.atan`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan) - on MDN. +Arctangent (in radians) of argument. See +[`Math.atan`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan) +on MDN. *) external atan : float -> float = "atan" [@@bs.val] [@@bs.scope "Math"] (** - Hyperbolic arctangent (in radians) of argument; returns `NaN` if the argument - is is outside the range [-1.0, 1.0]. Returns `-Infinity` and `Infinity` for - arguments -1.0 and 1.0. See - [`Math.atanh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atanh) - on MDN. +Hyperbolic arctangent (in radians) of argument; returns `NaN` if the argument +is is outside the range [-1.0, 1.0]. Returns `-Infinity` and `Infinity` for +arguments -1.0 and 1.0. See +[`Math.atanh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atanh) +on MDN. *) external atanh : float -> float = "atanh" [@@bs.val] [@@bs.scope "Math"] (** - Returns the angle (in radians) of the quotient `y /. x`. It is also the angle - between the *x*-axis and point (*x*, *y*). See - [`Math.atan2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2) - on MDN. +Returns the angle (in radians) of the quotient `y /. x`. It is also the angle +between the *x*-axis and point (*x*, *y*). See +[`Math.atan2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2) +on MDN. - ```res example - Js.Math.atan2(~y=0.0, ~x=10.0, ()) == 0.0 - Js.Math.atan2(~x=5.0, ~y=5.0, ()) == Js.Math._PI /. 4.0 - Js.Math.atan2(~x=-5.0, ~y=5.0, ()) - Js.Math.atan2(~x=-5.0, ~y=5.0, ()) == 3.0 *. Js.Math._PI /. 4.0 - Js.Math.atan2(~x=-0.0, ~y=-5.0, ()) == -.Js.Math._PI /. 2.0 - ``` +## Examples + +```rescript +Js.Math.atan2(~y=0.0, ~x=10.0, ()) == 0.0 +Js.Math.atan2(~x=5.0, ~y=5.0, ()) == Js.Math._PI /. 4.0 +Js.Math.atan2(~x=-5.0, ~y=5.0, ()) +Js.Math.atan2(~x=-5.0, ~y=5.0, ()) == 3.0 *. Js.Math._PI /. 4.0 +Js.Math.atan2(~x=-0.0, ~y=-5.0, ()) == -.Js.Math._PI /. 2.0 +``` *) external atan2 : y:float -> x:float -> unit -> float = "atan2" [@@bs.val] [@@bs.scope "Math"] (** - Cube root. See - [`Math.cbrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cbrt) - on MDN +Cube root. See +[`Math.cbrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cbrt) +on MDN *) external cbrt : float -> float = "cbrt" [@@bs.val] [@@bs.scope "Math"] (** - Returns the smallest integer greater than or equal to the argument. This - function may return values not representable by `int`, whose range is - -2147483648 to 2147483647. This is because, in JavaScript, there are only - 64-bit floating point numbers, which can represent integers in the range - ±(253-1) exactly. See - [`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) - on MDN. +Returns the smallest integer greater than or equal to the argument. This +function may return values not representable by `int`, whose range is +-2147483648 to 2147483647. This is because, in JavaScript, there are only +64-bit floating point numbers, which can represent integers in the range +±(253-1) exactly. See +[`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) +on MDN. + +## Examples - ```res example - Js.Math.unsafe_ceil_int(3.1) == 4 - Js.Math.unsafe_ceil_int(3.0) == 3 - Js.Math.unsafe_ceil_int(-3.1) == -3 - Js.Math.unsafe_ceil_int(1.0e15) // result is outside range of int datatype - ``` +```rescript +Js.Math.unsafe_ceil_int(3.1) == 4 +Js.Math.unsafe_ceil_int(3.0) == 3 +Js.Math.unsafe_ceil_int(-3.1) == -3 +Js.Math.unsafe_ceil_int(1.0e15) // result is outside range of int datatype +``` *) external unsafe_ceil_int : float -> int = "ceil" [@@bs.val] [@@bs.scope "Math"] -(** Deprecated; please use [`unsafe_ceil_int`](#unsafe_ceil_int) instead. *) let unsafe_ceil = unsafe_ceil_int [@@deprecated "Please use `unsafe_ceil_int` instead"] (** - Returns the smallest `int` greater than or equal to the argument; the result - is pinned to the range of the `int` data type: -2147483648 to 2147483647. See - [`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) - on MDN. +Returns the smallest `int` greater than or equal to the argument; the result +is pinned to the range of the `int` data type: -2147483648 to 2147483647. See +[`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) +on MDN. + +## Examples - ```res example - Js.Math.ceil_int(3.1) == 4 - Js.Math.ceil_int(3.0) == 3 - Js.Math.ceil_int(-3.1) == -3 - Js.Math.ceil_int(-1.0e15) == -2147483648 - Js.Math.ceil_int(1.0e15) == 2147483647 - ``` +```rescript +Js.Math.ceil_int(3.1) == 4 +Js.Math.ceil_int(3.0) == 3 +Js.Math.ceil_int(-3.1) == -3 +Js.Math.ceil_int(-1.0e15) == -2147483648 +Js.Math.ceil_int(1.0e15) == 2147483647 +``` *) let ceil_int (f : float) : int = if f > Js_int.toFloat Js_int.max then Js_int.max else if f < Js_int.toFloat Js_int.min then Js_int.min else unsafe_ceil_int f -(** Deprecated; please use [`ceil_int`](#ceil_int) instead. *) let ceil = ceil_int [@@deprecated "Please use `ceil_int` instead"] (** - Returns the smallest integral value greater than or equal to the argument. - The result is a `float` and is not restricted to the `int` data type range. - See - [`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) - on MDN. +Returns the smallest integral value greater than or equal to the argument. +The result is a `float` and is not restricted to the `int` data type range. +See +[`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) +on MDN. - ```res example - Js.Math.ceil_float(3.1) == 4.0 - Js.Math.ceil_float(3.0) == 3.0 - Js.Math.ceil_float(-3.1) == -3.0 - Js.Math.ceil_float(2_150_000_000.3) == 2_150_000_001.0 - ``` +## Examples + +```rescript +Js.Math.ceil_float(3.1) == 4.0 +Js.Math.ceil_float(3.0) == 3.0 +Js.Math.ceil_float(-3.1) == -3.0 +Js.Math.ceil_float(2_150_000_000.3) == 2_150_000_001.0 +``` *) external ceil_float : float -> float = "ceil" [@@bs.val] [@@bs.scope "Math"] (** - Number of leading zero bits of the argument's 32 bit int representation. See - [`Math.clz32`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/clz32) - on MDN. +Number of leading zero bits of the argument's 32 bit int representation. See +[`Math.clz32`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/clz32) +on MDN. + +## Examples - ```res example - Js.Math.clz32(0) == 32 - Js.Math.clz32(-1) == 0 - Js.Math.clz32(255) == 24 - ``` +```rescript +Js.Math.clz32(0) == 32 +Js.Math.clz32(-1) == 0 +Js.Math.clz32(255) == 24 +``` *) external clz32 : int -> int = "clz32" [@@bs.val] [@@bs.scope "Math"] (** - Cosine of argument, which must be specified in radians. See - [`Math.cos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos) - on MDN. +Cosine of argument, which must be specified in radians. See +[`Math.cos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos) +on MDN. *) external cos : float -> float = "cos" [@@bs.val] [@@bs.scope "Math"] (** - Hyperbolic cosine of argument, which must be specified in radians. See - [`Math.cosh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cosh) - on MDN. +Hyperbolic cosine of argument, which must be specified in radians. See +[`Math.cosh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cosh) +on MDN. *) external cosh : float -> float = "cosh" [@@bs.val] [@@bs.scope "Math"] (** - Natural exponentional; returns *e* (the base of natural logarithms) to the - power of the given argument. See - [`Math.exp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/exp) - on MDN. +Natural exponentional; returns *e* (the base of natural logarithms) to the +power of the given argument. See +[`Math.exp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/exp) +on MDN. *) external exp : float -> float = "exp" [@@bs.val] [@@bs.scope "Math"] (** - Returns *e* (the base of natural logarithms) to the power of the given - argument minus 1. See - [`Math.expm1`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/expm1) - on MDN. +Returns *e* (the base of natural logarithms) to the power of the given +argument minus 1. See +[`Math.expm1`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/expm1) +on MDN. *) external expm1 : float -> float = "expm1" [@@bs.val] [@@bs.scope "Math"] (** - Returns the largest integer less than or equal to the argument. This function - may return values not representable by `int`, whose range is -2147483648 to - 2147483647. This is because, in JavaScript, there are only 64-bit floating - point numbers, which can represent integers in the range - ±(253-1) exactly. See - [`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) - on MDN. +Returns the largest integer less than or equal to the argument. This function +may return values not representable by `int`, whose range is -2147483648 to +2147483647. This is because, in JavaScript, there are only 64-bit floating +point numbers, which can represent integers in the range +±(253-1) exactly. See +[`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) +on MDN. - ```res example - Js.Math.unsafe_floor_int(3.7) == 3 - Js.Math.unsafe_floor_int(3.0) == 3 - Js.Math.unsafe_floor_int(-3.7) == -4 - Js.Math.unsafe_floor_int(1.0e15) // result is outside range of int datatype - ``` +## Examples + +```rescript +Js.Math.unsafe_floor_int(3.7) == 3 +Js.Math.unsafe_floor_int(3.0) == 3 +Js.Math.unsafe_floor_int(-3.7) == -4 +Js.Math.unsafe_floor_int(1.0e15) // result is outside range of int datatype +``` *) external unsafe_floor_int : float -> int = "floor" [@@bs.val] [@@bs.scope "Math"] -(** Deprecated; please use [`unsafe_floor_int`](#unsafe_floor_int) instead. *) let unsafe_floor = unsafe_floor_int [@@deprecated "Please use `unsafe_floor_int` instead"] (** - Returns the largest `int` less than or equal to the argument; the result is - pinned to the range of the `int` data type: -2147483648 to 2147483647. See - [`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) - on MDN. +Returns the largest `int` less than or equal to the argument; the result is +pinned to the range of the `int` data type: -2147483648 to 2147483647. See +[`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) +on MDN. + +## Examples - ```res example - Js.Math.floor_int(3.7) == 3 - Js.Math.floor_int(3.0) == 3 - Js.Math.floor_int(-3.1) == -4 - Js.Math.floor_int(-1.0e15) == -2147483648 - Js.Math.floor_int(1.0e15) == 2147483647 - ``` +```rescript +Js.Math.floor_int(3.7) == 3 +Js.Math.floor_int(3.0) == 3 +Js.Math.floor_int(-3.1) == -4 +Js.Math.floor_int(-1.0e15) == -2147483648 +Js.Math.floor_int(1.0e15) == 2147483647 +``` *) let floor_int f = if f > Js_int.toFloat Js_int.max then Js_int.max else if f < Js_int.toFloat Js_int.min then Js_int.min else unsafe_floor f -(** Deprecated; please use [`floor_int`](#floor_int) instead. *) let floor = floor_int [@@deprecated "Please use `floor_int` instead"] (** - Returns the largest integral value less than or equal to the argument. The - result is a `float` and is not restricted to the `int` data type range. See - [`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) - on MDN. +Returns the largest integral value less than or equal to the argument. The +result is a `float` and is not restricted to the `int` data type range. See +[`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) +on MDN. - ```res example - Js.Math.floor_float(3.7) == 3.0 - Js.Math.floor_float(3.0) == 3.0 - Js.Math.floor_float(-3.1) == -4.0 - Js.Math.floor_float(2_150_000_000.3) == 2_150_000_000.0 - ``` +## Examples + +```rescript +Js.Math.floor_float(3.7) == 3.0 +Js.Math.floor_float(3.0) == 3.0 +Js.Math.floor_float(-3.1) == -4.0 +Js.Math.floor_float(2_150_000_000.3) == 2_150_000_000.0 +``` *) external floor_float : float -> float = "floor" [@@bs.val] [@@bs.scope "Math"] (** - Round to nearest single precision float. See - [`Math.fround`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/fround) - on MDN. +Round to nearest single precision float. See +[`Math.fround`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/fround) +on MDN. + +## Examples - ```res example - Js.Math.fround(5.5) == 5.5 - Js.Math.fround(5.05) == 5.050000190734863 - ``` +```rescript +Js.Math.fround(5.5) == 5.5 +Js.Math.fround(5.05) == 5.050000190734863 +``` *) external fround : float -> float = "fround" [@@bs.val] [@@bs.scope "Math"] (** - Returns the square root of the sum of squares of its two arguments (the - Pythagorean formula). See - [`Math.hypot`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/hypot) - on MDN. +Returns the square root of the sum of squares of its two arguments (the +Pythagorean formula). See +[`Math.hypot`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/hypot) +on MDN. *) external hypot : float -> float -> float = "hypot" [@@bs.val] [@@bs.scope "Math"] (** - Returns the square root of the sum of squares of the numbers in the array - argument (generalized Pythagorean equation). Using an array allows you to - have more than two items. See - [`Math.hypot`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/hypot) - on MDN. +Returns the square root of the sum of squares of the numbers in the array +argument (generalized Pythagorean equation). Using an array allows you to +have more than two items. See +[`Math.hypot`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/hypot) +on MDN. - ```res example - Js.Math.hypotMany([3.0, 4.0, 12.0]) == 13.0 - ``` +## Examples + +```rescript +Js.Math.hypotMany([3.0, 4.0, 12.0]) == 13.0 +``` *) external hypotMany : float array -> float = "hypot" [@@bs.val] [@@bs.splice] [@@bs.scope "Math"] (** - 32-bit integer multiplication. Use this only when you need to optimize - performance of multiplication of numbers stored as 32-bit integers. See - [`Math.imul`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/imul) - on MDN. +32-bit integer multiplication. Use this only when you need to optimize +performance of multiplication of numbers stored as 32-bit integers. See +[`Math.imul`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/imul) +on MDN. *) external imul : int -> int -> int = "imul" [@@bs.val] [@@bs.scope "Math"] (** - Returns the natural logarithm of its argument; this is the number *x* such - that *e**x* equals the argument. Returns `NaN` for negative - arguments. See - [`Math.log`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log) - on MDN. +Returns the natural logarithm of its argument; this is the number *x* such +that *e**x* equals the argument. Returns `NaN` for negative +arguments. See +[`Math.log`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log) +on MDN. + +## Examples - ```res example - Js.Math.log(Js.Math._E) == 1.0 - Js.Math.log(100.0) == 4.605170185988092 - ``` +```rescript +Js.Math.log(Js.Math._E) == 1.0 +Js.Math.log(100.0) == 4.605170185988092 +``` *) external log : float -> float = "log" [@@bs.val] [@@bs.scope "Math"] (** - Returns the natural logarithm of one plus the argument. Returns `NaN` for - arguments less than -1. See - [`Math.log1p`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log1p) - on MDN. +Returns the natural logarithm of one plus the argument. Returns `NaN` for +arguments less than -1. See +[`Math.log1p`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log1p) +on MDN. - ```res example - Js.Math.log1p(Js.Math._E -. 1.0) == 1.0 - Js.Math.log1p(99.0) == 4.605170185988092 - ``` +## Examples + +```rescript +Js.Math.log1p(Js.Math._E -. 1.0) == 1.0 +Js.Math.log1p(99.0) == 4.605170185988092 +``` *) external log1p : float -> float = "log1p" [@@bs.val] [@@bs.scope "Math"] (** - Returns the base 10 logarithm of its argument. Returns `NaN` for negative - arguments. See - [`Math.log10`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log10) - on MDN. +Returns the base 10 logarithm of its argument. Returns `NaN` for negative +arguments. See +[`Math.log10`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log10) +on MDN. + +## Examples - ```res example - Js.Math.log10(1000.0) == 3.0 - Js.Math.log10(0.01) == -2.0 - Js.Math.log10(Js.Math.sqrt(10.0)) == 0.5 - ``` +```rescript +Js.Math.log10(1000.0) == 3.0 +Js.Math.log10(0.01) == -2.0 +Js.Math.log10(Js.Math.sqrt(10.0)) == 0.5 +``` *) external log10 : float -> float = "log10" [@@bs.val] [@@bs.scope "Math"] (** - Returns the base 2 logarithm of its argument. Returns `NaN` for negative - arguments. See - [`Math.log2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log2) - on MDN. +Returns the base 2 logarithm of its argument. Returns `NaN` for negative +arguments. See +[`Math.log2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log2) +on MDN. - ```res example - Js.Math.log2(512.0) == 9.0 - Js.Math.log2(0.125) == -3.0 - Js.Math.log2(Js.Math._SQRT2) == 0.5000000000000001 // due to precision - ``` +## Examples + +```rescript +Js.Math.log2(512.0) == 9.0 +Js.Math.log2(0.125) == -3.0 +Js.Math.log2(Js.Math._SQRT2) == 0.5000000000000001 // due to precision +``` *) external log2 : float -> float = "log2" [@@bs.val] [@@bs.scope "Math"] (** - Returns the maximum of its two integer arguments. See - [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) - on MDN. +Returns the maximum of its two integer arguments. See +[`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) +on MDN. *) external max_int : int -> int -> int = "max" [@@bs.val] [@@bs.scope "Math"] (** - Returns the maximum of the integers in the given array. See - [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) - on MDN. +Returns the maximum of the integers in the given array. See +[`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) +on MDN. *) external maxMany_int : int array -> int = "max" [@@bs.val] [@@bs.splice] [@@bs.scope "Math"] (** - Returns the maximum of its two floating point arguments. See - [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) - on MDN. +Returns the maximum of its two floating point arguments. See +[`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) +on MDN. *) external max_float : float -> float -> float = "max" [@@bs.val] [@@bs.scope "Math"] (** - Returns the maximum of the floating point values in the given array. See - [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) - on MDN. +Returns the maximum of the floating point values in the given array. See +[`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) +on MDN. *) external maxMany_float : float array -> float = "max" [@@bs.val] [@@bs.splice] [@@bs.scope "Math"] (** - Returns the minimum of its two integer arguments. See - [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) - on MDN. +Returns the minimum of its two integer arguments. See +[`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) +on MDN. *) external min_int : int -> int -> int = "min" [@@bs.val] [@@bs.scope "Math"] (** - Returns the minimum of the integers in the given array. See - [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) - on MDN. +Returns the minimum of the integers in the given array. See +[`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) +on MDN. *) external minMany_int : int array -> int = "min" [@@bs.val] [@@bs.splice] [@@bs.scope "Math"] (** - Returns the minimum of its two floating point arguments. See - [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) - on MDN. +Returns the minimum of its two floating point arguments. See +[`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) +on MDN. *) external min_float : float -> float -> float = "min" [@@bs.val] [@@bs.scope "Math"] (** - Returns the minimum of the floating point values in the given array. See - [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) - on MDN. +Returns the minimum of the floating point values in the given array. See +[`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) +on MDN. *) external minMany_float : float array -> float = "min" [@@bs.val] [@@bs.splice] [@@bs.scope "Math"] (** - Raises the given base to the given exponent. (Arguments and result are - integers.) See - [`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow) - on MDN. +Raises the given base to the given exponent. (Arguments and result are +integers.) See +[`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow) +on MDN. + +## Examples - ```res example - Js.Math.pow_int(~base=3, ~exp=4) == 81 - ``` +```rescript +Js.Math.pow_int(~base=3, ~exp=4) == 81 +``` *) external pow_int : base:int -> exp:int -> int = "pow" [@@bs.val] [@@bs.scope "Math"] [@@deprecated "use `pow_float` instead, the return type may be not int"] (** - Raises the given base to the given exponent. (Arguments and result are - floats.) Returns `NaN` if the result would be imaginary. See - [`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow) - on MDN. +Raises the given base to the given exponent. (Arguments and result are +floats.) Returns `NaN` if the result would be imaginary. See +[`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow) +on MDN. - ```res example - Js.Math.pow_float(~base=3.0, ~exp=4.0) == 81.0 - Js.Math.pow_float(~base=4.0, ~exp=-2.0) == 0.0625 - Js.Math.pow_float(~base=625.0, ~exp=0.5) == 25.0 - Js.Math.pow_float(~base=625.0, ~exp=-0.5) == 0.04 - Js.Float.isNaN(Js.Math.pow_float(~base=-2.0, ~exp=0.5)) == true - ``` +## Examples + +```rescript +Js.Math.pow_float(~base=3.0, ~exp=4.0) == 81.0 +Js.Math.pow_float(~base=4.0, ~exp=-2.0) == 0.0625 +Js.Math.pow_float(~base=625.0, ~exp=0.5) == 25.0 +Js.Math.pow_float(~base=625.0, ~exp=-0.5) == 0.04 +Js.Float.isNaN(Js.Math.pow_float(~base=-2.0, ~exp=0.5)) == true +``` *) external pow_float : base:float -> exp:float -> float = "pow" [@@bs.val] [@@bs.scope "Math"] (** - Returns a random number in the half-closed interval [0,1). See - [`Math.random`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) - on MDN. +Returns a random number in the half-closed interval [0,1). See +[`Math.random`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) +on MDN. *) external random : unit -> float = "random" [@@bs.val] [@@bs.scope "Math"] (** - A call to `random_int(minVal, maxVal)` returns a random number in the - half-closed interval [minVal, maxVal). See - [`Math.random`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) - on MDN. +A call to `random_int(minVal, maxVal)` returns a random number in the +half-closed interval [minVal, maxVal). See +[`Math.random`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) +on MDN. *) let random_int min max = floor ((random ()) *. (Js_int.toFloat (max - min))) + min (** - Rounds its argument to nearest integer. For numbers with a fractional portion - of exactly 0.5, the argument is rounded to the next integer in the direction - of positive infinity. This function may return values not representable by - `int`, whose range is -2147483648 to 2147483647. This is because, in - JavaScript, there are only 64-bit floating point numbers, which can represent - integers in the range ±(253-1) exactly. See - [`Math.round`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round) - on MDN. +Rounds its argument to nearest integer. For numbers with a fractional portion +of exactly 0.5, the argument is rounded to the next integer in the direction +of positive infinity. This function may return values not representable by +`int`, whose range is -2147483648 to 2147483647. This is because, in +JavaScript, there are only 64-bit floating point numbers, which can represent +integers in the range ±(253-1) exactly. See +[`Math.round`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round) +on MDN. + +## Examples - ```res example - Js.Math.unsafe_round(3.7) == 4 - Js.Math.unsafe_round(-3.5) == -3 - Js.Math.unsafe_round(2_150_000_000_000.3) // out of range for int - ``` +```rescript +Js.Math.unsafe_round(3.7) == 4 +Js.Math.unsafe_round(-3.5) == -3 +Js.Math.unsafe_round(2_150_000_000_000.3) // out of range for int +``` *) external unsafe_round : float -> int = "round" [@@bs.val] [@@bs.scope "Math"] (** - Rounds to nearest integral value (expressed as a float). See - [`Math.round`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round) - on MDN. +Rounds to nearest integral value (expressed as a float). See +[`Math.round`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round) +on MDN. *) external round : float -> float = "round" [@@bs.val] [@@bs.scope "Math"] (** - Returns the sign of its integer argument: -1 if negative, 0 if zero, 1 if - positive. See - [`Math.sign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign) - on MDN. +Returns the sign of its integer argument: -1 if negative, 0 if zero, 1 if +positive. See +[`Math.sign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign) +on MDN. *) external sign_int : int -> int = "sign" [@@bs.val][@@bs.scope "Math"] (** - Returns the sign of its float argument: -1.0 if negative, 0.0 if zero, 1.0 if - positive. See - [`Math.sign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign) - on MDN. +Returns the sign of its float argument: -1.0 if negative, 0.0 if zero, 1.0 if +positive. See +[`Math.sign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign) +on MDN. *) external sign_float : float -> float = "sign" [@@bs.val][@@bs.scope "Math"] (** - Sine of argument, which must be specified in radians. See - [`Math.sin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sin) - on MDN. +Sine of argument, which must be specified in radians. See +[`Math.sin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sin) +on MDN. *) external sin : float -> float = "sin" [@@bs.val][@@bs.scope "Math"] (** - Hyperbolic sine of argument, which must be specified in radians. See - [`Math.sinh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sinh) - on MDN. +Hyperbolic sine of argument, which must be specified in radians. See +[`Math.sinh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sinh) +on MDN. *) external sinh : float -> float = "sinh" [@@bs.val][@@bs.scope "Math"] (** - Square root. If the argument is negative, this function returns `NaN`. See - [`Math.sqrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sqrt) - on MDN. +Square root. If the argument is negative, this function returns `NaN`. See +[`Math.sqrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sqrt) +on MDN. *) external sqrt : float -> float = "sqrt" [@@bs.val][@@bs.scope "Math"] (** - Tangent of argument, which must be specified in radians. Returns `NaN` if the - argument is positive infinity or negative infinity. See - [`Math.cos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos) - on MDN. +Tangent of argument, which must be specified in radians. Returns `NaN` if the +argument is positive infinity or negative infinity. See +[`Math.cos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos) +on MDN. *) external tan : float -> float = "tan" [@@bs.val][@@bs.scope "Math"] (** - Hyperbolic tangent of argument, which must be specified in radians. See - [`Math.tanh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/tanh) - on MDN. +Hyperbolic tangent of argument, which must be specified in radians. See +[`Math.tanh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/tanh) +on MDN. *) external tanh : float -> float = "tanh" [@@bs.val][@@bs.scope "Math"] (** - Truncates its argument; i.e., removes fractional digits. This function may - return values not representable by `int`, whose range is -2147483648 to - 2147483647. This is because, in JavaScript, there are only 64-bit floating - point numbers, which can represent integers in the range ±(253-1) - exactly. See - [`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc) - on MDN. +Truncates its argument; i.e., removes fractional digits. This function may +return values not representable by `int`, whose range is -2147483648 to +2147483647. This is because, in JavaScript, there are only 64-bit floating +point numbers, which can represent integers in the range ±(253-1) +exactly. See +[`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc) +on MDN. *) external unsafe_trunc : float -> int = "trunc" [@@bs.val][@@bs.scope "Math"] (** - Truncates its argument; i.e., removes fractional digits. See - [`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc) - on MDN. +Truncates its argument; i.e., removes fractional digits. See +[`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc) +on MDN. *) external trunc : float -> float = "trunc" [@@bs.val][@@bs.scope "Math"] diff --git a/jscomp/others/js_null.resi b/jscomp/others/js_null.resi index e9f00e6055..4c9963500b 100644 --- a/jscomp/others/js_null.resi +++ b/jscomp/others/js_null.resi @@ -49,7 +49,9 @@ If `Js.null<'a>` contains a value, that value is unwrapped, mapped to a `'b` using the given function `'a => 'b`, then wrapped back up and returned as `Js.null<'b>`. -```res example +## Examples + +```rescript let maybeGreetWorld = (maybeGreeting: Js.null) => Js.Null.bind(maybeGreeting, (. greeting) => greeting ++ " world!") ``` @@ -60,7 +62,9 @@ let bind: (t<'a>, (. 'a) => 'b) => t<'b> Iterates over the contained value with the given function. If `Js.null<'a>` contains a value, that value is unwrapped and applied to the given function. -```res example +## Examples + +```rescript let maybeSay = (maybeMessage: Js.null) => Js.Null.iter(maybeMessage, (. message) => Js.log(message)) ``` diff --git a/jscomp/others/js_null_undefined.resi b/jscomp/others/js_null_undefined.resi index c36f38bd36..e183e73ffe 100644 --- a/jscomp/others/js_null_undefined.resi +++ b/jscomp/others/js_null_undefined.resi @@ -22,9 +22,12 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Contains functionality for dealing with values that can be both `null` and `undefined` */ +/*** +Contains functionality for dealing with values that can be both `null` and `undefined` +*/ -@unboxed /** Local alias for `Js.null_undefined<'a>`. */ +/** Local alias for `Js.null_undefined<'a>`. */ +@unboxed type t<+'a> = Js.nullable<'a> = | Value('a) | @as(null) Null @@ -49,7 +52,9 @@ If `Js.null_undefined<'a>` contains a value, that value is unwrapped, mapped to a `'b` using the given function `a' => 'b`, then wrapped back up and returned as `Js.null_undefined<'b>`. -```res example +## Examples + +```rescript let maybeGreetWorld = (maybeGreeting: Js.null_undefined) => Js.Null_undefined.bind(maybeGreeting, (. greeting) => greeting ++ " world!") ``` @@ -60,7 +65,9 @@ let bind: (t<'a>, (. 'a) => 'b) => t<'b> Iterates over the contained value with the given function. If `Js.null_undefined<'a>` contains a value, that value is unwrapped and applied to the given function. -```res example +## Examples + +```rescript let maybeSay = (maybeMessage: Js.null_undefined) => Js.Null_undefined.iter(maybeMessage, (. message) => Js.log(message)) ``` diff --git a/jscomp/others/js_obj.res b/jscomp/others/js_obj.res index bec7ab1bae..eb3fb14ca1 100644 --- a/jscomp/others/js_obj.res +++ b/jscomp/others/js_obj.res @@ -22,7 +22,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Provides functions for inspecting and manipulating native JavaScript objects */ +/*** +Provides functions for inspecting and manipulating native JavaScript objects +*/ @obj /** `empty()` returns the empty object `{}` */ external empty: unit => {..} = "" @@ -35,7 +37,9 @@ Returns `target`. **See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) -```res example +## Examples + +```rescript /* Copy an object */ let obj = {"a": 1} @@ -94,5 +98,6 @@ external assign: ({..}, {..}) => {..} = "Object.assign" - Object.is */ -@val /** `keys(obj)` returns an `array` of the keys of `obj`'s own enumerable properties. */ +/** `keys(obj)` returns an `array` of the keys of `obj`'s own enumerable properties. */ +@val external keys: {..} => array = "Object.keys" diff --git a/jscomp/others/js_option.res b/jscomp/others/js_option.res index 587f89d427..d18e815031 100644 --- a/jscomp/others/js_option.res +++ b/jscomp/others/js_option.res @@ -25,22 +25,24 @@ /*** Provide utilities for handling `option`. */ /** - `Js.Option.t` is an alias for `option` +`Js.Option.t` is an alias for `option` */ type t<'a> = option<'a> /** - Wraps the given value in `Some()` +Wraps the given value in `Some()` - ```res example - Js.Option.some(1066) == Some(1066) - ``` +## Examples + +```rescript +Js.Option.some(1066) == Some(1066) +``` */ let some = x => Some(x) /** - Returns `true` if the argument is `Some(value)`; `false` if the argument is - `None`. +Returns `true` if the argument is `Some(value)`; `false` if the argument is +`None`. */ let isSome = x => switch x { @@ -49,19 +51,21 @@ let isSome = x => } /** - The first argument to `isSomeValue` is an uncurried function `eq()` that - takes two arguments and returns `true` if they are considered to be equal. It - is used to compare a plain value `v1`(the second argument) with an `option` - value. If the `option` value is `None`, `isSomeValue()` returns `false`; if - the third argument is `Some(v2)`, `isSomeValue()` returns the result of - calling `eq(v1, v2)`. - - ```res example - let clockEqual = (. a, b) => mod(a, 12) == mod(b, 12) - Js.Option.isSomeValue(clockEqual, 3, Some(15)) == true - Js.Option.isSomeValue(clockEqual, 3, Some(4)) == false - Js.Option.isSomeValue(clockEqual, 3, None) == false - ``` +The first argument to `isSomeValue` is an uncurried function `eq()` that +takes two arguments and returns `true` if they are considered to be equal. It +is used to compare a plain value `v1`(the second argument) with an `option` +value. If the `option` value is `None`, `isSomeValue()` returns `false`; if +the third argument is `Some(v2)`, `isSomeValue()` returns the result of +calling `eq(v1, v2)`. + +## Examples + +```rescript +let clockEqual = (. a, b) => mod(a, 12) == mod(b, 12) +Js.Option.isSomeValue(clockEqual, 3, Some(15)) == true +Js.Option.isSomeValue(clockEqual, 3, Some(4)) == false +Js.Option.isSomeValue(clockEqual, 3, None) == false +``` */ let isSomeValue = (eq, v, x) => switch x { @@ -77,8 +81,8 @@ let isNone = x => } /** - If the argument to `getExn()` is of the form `Some(value)`, returns `value`. - If given `None`, it throws a `getExn` exception. +If the argument to `getExn()` is of the form `Some(value)`, returns `value`. +If given `None`, it throws a `getExn` exception. */ let getExn = x => switch x { @@ -87,25 +91,27 @@ let getExn = x => } /** - The first argument to `equal` is an uncurried function `eq()` that takes two - arguments and returns `true` if they are considered to be equal. The second +The first argument to `equal` is an uncurried function `eq()` that takes two +arguments and returns `true` if they are considered to be equal. The second and third arguments are `option` values. - If the second and third arguments are of the form: - - * `Some(v1)` and `Some(v2)`: returns `eq(v1, v2)` - * `Some(v1)` and `None`: returns `false` - * `None` and `Some(v2)`: returns `false` - * `None` and `None`: returns `true` - - ```res example - let clockEqual = (. a, b) => mod(a, 12) == mod(b, 12) - Js.Option.equal(clockEqual, Some(3), Some(15)) == true - Js.Option.equal(clockEqual, Some(3), Some(16)) == false - Js.Option.equal(clockEqual, Some(3), None) == false - Js.Option.equal(clockEqual, None, Some(15)) == false - Js.Option.equal(clockEqual, None, None) == true - ``` +If the second and third arguments are of the form: + +* `Some(v1)` and `Some(v2)`: returns `eq(v1, v2)` +* `Some(v1)` and `None`: returns `false` +* `None` and `Some(v2)`: returns `false` +* `None` and `None`: returns `true` + +## Examples + +```rescript +let clockEqual = (. a, b) => mod(a, 12) == mod(b, 12) +Js.Option.equal(clockEqual, Some(3), Some(15)) == true +Js.Option.equal(clockEqual, Some(3), Some(16)) == false +Js.Option.equal(clockEqual, Some(3), None) == false +Js.Option.equal(clockEqual, None, Some(15)) == false +Js.Option.equal(clockEqual, None, None) == true +``` */ let equal = (eq, a, b) => switch a { @@ -118,17 +124,19 @@ let equal = (eq, a, b) => } /** - The first argument to `andThen()` is an uncurried function `f()` that takes a - plain value and returns an `option` result. The second argument is an - `option` value. If the second argument is `None`, the return value is `None`. - If the second argument is `Some(v)`, the return value is `f(v)`. - - ```res example - let reciprocal = (. x) => x == 0 ? None : Some(1.0 /. Belt.Int.toFloat(x)) - Js.Option.andThen(reciprocal, Some(5)) == Some(0.2) - Js.Option.andThen(reciprocal, Some(0)) == None - Js.Option.andThen(reciprocal, None) == None - ``` +The first argument to `andThen()` is an uncurried function `f()` that takes a +plain value and returns an `option` result. The second argument is an +`option` value. If the second argument is `None`, the return value is `None`. +If the second argument is `Some(v)`, the return value is `f(v)`. + +## Examples + +```rescript +let reciprocal = (. x) => x == 0 ? None : Some(1.0 /. Belt.Int.toFloat(x)) +Js.Option.andThen(reciprocal, Some(5)) == Some(0.2) +Js.Option.andThen(reciprocal, Some(0)) == None +Js.Option.andThen(reciprocal, None) == None +``` */ let andThen = (f, x) => switch x { @@ -137,16 +145,18 @@ let andThen = (f, x) => } /** - The first argument to `map()` is an uncurried function `f()` that takes a - plain value and returns a plain result. The second argument is an `option` - value. If it is of the form `Some(v)`, `map()` returns `Some(f(v))`; if it is - `None`, the return value is `None`, and function `f()` is not called. - - ```res example - let square = (. x) => x * x - Js.Option.map(square, Some(3)) == Some(9) - Js.Option.map(square, None) == None - ``` +The first argument to `map()` is an uncurried function `f()` that takes a +plain value and returns a plain result. The second argument is an `option` +value. If it is of the form `Some(v)`, `map()` returns `Some(f(v))`; if it is +`None`, the return value is `None`, and function `f()` is not called. + +## Examples + +```rescript +let square = (. x) => x * x +Js.Option.map(square, Some(3)) == Some(9) +Js.Option.map(square, None) == None +``` */ let map = (f, x) => switch x { @@ -155,14 +165,16 @@ let map = (f, x) => } /** - The first argument to `getWithDefault()` is a default value. If the second - argument is of the form `Some(v)`, `getWithDefault()` returns `v`; if the - second argument is `None`, the return value is the default value. - - ```res example - Js.Option.getWithDefault(1066, Some(15)) == 15 - Js.Option.getWithDefault(1066, None) == 1066 - ``` +The first argument to `getWithDefault()` is a default value. If the second +argument is of the form `Some(v)`, `getWithDefault()` returns `v`; if the +second argument is `None`, the return value is the default value. + +## Examples + +```rescript +Js.Option.getWithDefault(1066, Some(15)) == 15 +Js.Option.getWithDefault(1066, None) == 1066 +``` */ let getWithDefault = (a, x) => switch x { @@ -174,18 +186,20 @@ let getWithDefault = (a, x) => let default = getWithDefault /** - The first argument to `filter()` is an uncurried function that takes a plain - value and returns a boolean. The second argument is an `option` value. - - If the second argument is of the form `Some(v)` and `f(v)` is `true`, - the return value is `Some(v)`. Otherwise, the return value is `None`. - - ```res example - let isEven = (. x) => mod(x, 2) == 0 - Js.Option.filter(isEven, Some(2)) == Some(2) - Js.Option.filter(isEven, Some(3)) == None - Js.Option.filter(isEven, None) == None - ``` +The first argument to `filter()` is an uncurried function that takes a plain +value and returns a boolean. The second argument is an `option` value. + +If the second argument is of the form `Some(v)` and `f(v)` is `true`, +the return value is `Some(v)`. Otherwise, the return value is `None`. + +## Examples + +```rescript +let isEven = (. x) => mod(x, 2) == 0 +Js.Option.filter(isEven, Some(2)) == Some(2) +Js.Option.filter(isEven, Some(3)) == None +Js.Option.filter(isEven, None) == None +``` */ let filter = (f, x) => switch x { @@ -199,14 +213,16 @@ let filter = (f, x) => } /** - The `firstSome()` function takes two `option` values; if the first is of the form `Some(v1)`, that is the return value. Otherwise, `firstSome()` returns the second value. - - ```res example - Js.Option.firstSome(Some("one"), Some("two")) == Some("one") - Js.Option.firstSome(Some("one"), None) == Some("one") - Js.Option.firstSome(None, Some("two")) == Some("two") - Js.Option.firstSome(None, None) == None - ``` +The `firstSome()` function takes two `option` values; if the first is of the form `Some(v1)`, that is the return value. Otherwise, `firstSome()` returns the second value. + +## Examples + +```rescript +Js.Option.firstSome(Some("one"), Some("two")) == Some("one") +Js.Option.firstSome(Some("one"), None) == Some("one") +Js.Option.firstSome(None, Some("two")) == Some("two") +Js.Option.firstSome(None, None) == None +``` */ let firstSome = (a, b) => switch (a, b) { diff --git a/jscomp/others/js_promise.res b/jscomp/others/js_promise.res index defdb52264..7268e1e37b 100644 --- a/jscomp/others/js_promise.res +++ b/jscomp/others/js_promise.res @@ -22,11 +22,12 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** Deprecation note: These bindings are pretty outdated and cannot be used - properly with the `->` operator. +/*** +Deprecation note: These bindings are pretty outdated and cannot be used properly +with the `->` operator. - More details on proper Promise usage can be found here: - https://rescript-lang.org/docs/manual/latest/promise#promise-legacy +More details on proper Promise usage can be found here: +https://rescript-lang.org/docs/manual/latest/promise#promise-legacy */ @@warning("-103") @@ -35,7 +36,9 @@ type t<+'a> = promise<'a> type error = Js_promise2.error /* -```res prelude +## Examples + +```rescript type error ``` */ diff --git a/jscomp/others/js_re.res b/jscomp/others/js_re.res index 6ddc0f89fa..5ba7b6038c 100644 --- a/jscomp/others/js_re.res +++ b/jscomp/others/js_re.res @@ -23,11 +23,11 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - Provide bindings to JS regular expressions (RegExp). +Provide bindings to JS regular expressions (RegExp). - **Note:** This is not an immutable API. A RegExp object with the `global` ("g") - flag set will modify the [`lastIndex`]() property when the RegExp object is used, - and subsequent uses will continue the search from the previous [`lastIndex`](). +**Note:** This is not an immutable API. A RegExp object with the `global` ("g") +flag set will modify the [`lastIndex`]() property when the RegExp object is used, +and subsequent uses will continue the search from the previous [`lastIndex`](). */ /** The RegExp object. */ @@ -37,14 +37,11 @@ type t type result /** - An `array` of the match and captures, the first is the full match and the - remaining are the substring captures. +An `array` of the match and captures, the first is the full match and the +remaining are the substring captures. */ external captures: result => array> = "%identity" -/** - Deprecated. Use `captures` instead. -*/ @deprecated("Use Js.Re.captures instead") external matches: result => array = "%identity" @@ -57,38 +54,40 @@ external index: result => int = "index" external input: result => string = "input" /** - Constructs a RegExp object (Js.Re.t) from a `string`. - Regex literals `%re("/.../")` should generally be preferred, but `fromString` - is useful when you need to dynamically construct a regex using strings, - exactly like when you do so in JavaScript. - - ```res example - let firstReScriptFileExtension = (filename, content) => { - let result = Js.Re.fromString(filename ++ "\.(res|resi)")->Js.Re.exec_(content) - switch result { - | Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1]) - | None => None - } +Constructs a RegExp object (Js.Re.t) from a `string`. +Regex literals `%re("/.../")` should generally be preferred, but `fromString` +is useful when you need to dynamically construct a regex using strings, +exactly like when you do so in JavaScript. + +## Examples + +```rescript +let firstReScriptFileExtension = (filename, content) => { + let result = Js.Re.fromString(filename ++ "\.(res|resi)")->Js.Re.exec_(content) + switch result { + | Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1]) + | None => None } +} - // outputs "res" - firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js") - ``` +// outputs "res" +firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js") +``` */ @new external fromString: string => t = "RegExp" /** - Constructs a RegExp object (`Js.Re.t`) from a string with the given flags. - See `Js.Re.fromString`. +Constructs a RegExp object (`Js.Re.t`) from a string with the given flags. +See `Js.Re.fromString`. - Valid flags: +Valid flags: - - **g** global - - **i** ignore case - - **m** multiline - - **u** unicode (es2015) - - **y** sticky (es2015) +- **g** global +- **i** ignore case +- **m** multiline +- **u** unicode (es2015) +- **y** sticky (es2015) */ @new external fromStringWithFlags: (string, ~flags: string) => t = "RegExp" @@ -106,29 +105,31 @@ external global: t => bool = "global" external ignoreCase: t => bool = "ignoreCase" /** - Returns the index where the next match will start its search. This property - will be modified when the RegExp object is used, if the global ("g") flag is - set. - - ```res example - let re = %re("/ab*TODO/g") - let str = "abbcdefabh" - - let break = ref(false) - while !break.contents { - switch Js.Re.exec_(re, str) { - | Some(result) => Js.Nullable.iter(Js.Re.captures(result)[0], (. match_) => { - let next = Belt.Int.toString(Js.Re.lastIndex(re)) - Js.log("Found " ++ (match_ ++ (". Next match starts at " ++ next))) - }) - | None => break := true - } +Returns the index where the next match will start its search. This property +will be modified when the RegExp object is used, if the global ("g") flag is +set. + +## Examples + +```rescript +let re = %re("/ab*TODO/g") +let str = "abbcdefabh" + +let break = ref(false) +while !break.contents { + switch Js.Re.exec_(re, str) { + | Some(result) => Js.Nullable.iter(Js.Re.captures(result)[0], (. match_) => { + let next = Belt.Int.toString(Js.Re.lastIndex(re)) + Js.log("Found " ++ (match_ ++ (". Next match starts at " ++ next))) + }) + | None => break := true } - ``` +} +``` - See - [`RegExp: lastIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) - on MDN. +See +[`RegExp: lastIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex) +on MDN. */ @get external lastIndex: t => int = "lastIndex" @@ -154,45 +155,47 @@ external sticky: t => bool = "sticky" external unicode: t => bool = "unicode" /** - Executes a search on a given string using the given RegExp object. - Returns `Some(Js.Re.result)` if a match is found, `None` otherwise. - - ```res example - /* Match "quick brown" followed by "jumps", ignoring characters in between - * Remember "brown" and "jumps" - * Ignore case - */ - - let re = %re("/quick\s(brown).+?(jumps)/ig") - let result = Js.Re.exec_(re, "The Quick Brown Fox Jumps Over The Lazy Dog") - ``` - - See - [`RegExp.prototype.exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) - on MDN. +Executes a search on a given string using the given RegExp object. +Returns `Some(Js.Re.result)` if a match is found, `None` otherwise. + +## Examples + +```rescript +/* Match "quick brown" followed by "jumps", ignoring characters in between + * Remember "brown" and "jumps" + * Ignore case + */ + +let re = %re("/quick\s(brown).+?(jumps)/ig") +let result = Js.Re.exec_(re, "The Quick Brown Fox Jumps Over The Lazy Dog") +``` + +See [`RegExp.prototype.exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec) +on MDN. */ @send @return(null_to_opt) external exec_: (t, string) => option = "exec" /** - Tests whether the given RegExp object will match a given `string`. - Returns true if a match is found, false otherwise. +Tests whether the given RegExp object will match a given `string`. +Returns true if a match is found, false otherwise. + +## Examples - ```res example - /* A simple implementation of Js.String.startsWith */ +```rescript +/* A simple implementation of Js.String.startsWith */ - let str = "hello world!" +let str = "hello world!" - let startsWith = (target, substring) => - Js.Re.fromString("^" ++ substring)->Js.Re.test_(target) +let startsWith = (target, substring) => + Js.Re.fromString("^" ++ substring)->Js.Re.test_(target) - Js.log(str->startsWith("hello")) /* prints "true" */ - ``` +Js.log(str->startsWith("hello")) /* prints "true" */ +``` - See - [`RegExp.prototype.test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test) - on MDN. +See [`RegExp.prototype.test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test) +on MDN. */ @send external test_: (t, string) => bool = "test" diff --git a/jscomp/others/js_string.res b/jscomp/others/js_string.res index d68f582eb1..811d1b2b00 100644 --- a/jscomp/others/js_string.res +++ b/jscomp/others/js_string.res @@ -32,7 +32,9 @@ type t = string /** `make(value)` converts the given value to a `string`. -```res example +## Examples + +```rescript Js.String2.make(3.5) == "3.5" Js.String2.make([1, 2, 3]) == "1,2,3" ``` @@ -44,7 +46,9 @@ external make: 'a => t = "String" `fromCharCode(n)` creates a `string` containing the character corresponding to that number; `n` ranges from 0 to 65535. If out of range, the lower 16 bits of the value are used. Thus, `fromCharCode(0x1F63A)` gives the same result as `fromCharCode(0xF63A)`. See [`String.fromCharCode`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCharCode) on MDN. -```res example +## Examples + +```rescript Js.String2.fromCharCode(65) == "A" Js.String2.fromCharCode(0x3c8) == `ψ` Js.String2.fromCharCode(0xd55c) == `한` @@ -74,7 +78,9 @@ unlike `fromCharCode(0x1F63A)`, and `fromCodePoint(-5)` will raise a See [`String.fromCodePoint`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint) on MDN. -```res example +## Examples + +```rescript Js.String2.fromCodePoint(65) == "A" Js.String2.fromCodePoint(0x3c8) == `ψ` Js.String2.fromCodePoint(0xd55c) == `한` @@ -93,7 +99,9 @@ corresponding to the given code point numbers, using the same rules as See [`String.fromCodePoint`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint) on MDN. -```res example +## Examples + +```rescript Js.String2.fromCodePointMany([0xd55c, 0xae00, 0x1f63a]) == `한글😺` ``` */ @@ -107,7 +115,9 @@ external fromCodePointMany: array => t = "String.fromCodePoint" [`String.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) on MDN. -```res example +## Examples + +```rescript Js.String2.length("abcd") == 4 ``` */ @@ -119,7 +129,9 @@ external length: t => int = "length" `n` is out of range, this function returns `undefined`, so at some point this function may be modified to return `option`. -```res example +## Examples + +```rescript Js.String2.get("Reason", 0) == "R" Js.String2.get("Reason", 4) == "o" Js.String2.get(`Rẽasöń`, 5) == `ń` @@ -137,7 +149,9 @@ first 16-bit value at that position in the string. See [`String.charAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt) on MDN. -```res example +## Examples + +```rescript Js.String.charAt(0, "Reason") == "R" Js.String.charAt(12, "Reason") == "" Js.String.charAt(5, `Rẽasöń`) == `ń` @@ -156,7 +170,9 @@ zero or greater than the length of the string. See [`String.charCodeAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charCodeAt) on MDN. -```res example +## Examples + +```rescript Js.String.charCodeAt(0, `😺`) == 0xd83d->Belt.Int.toFloat Js.String.codePointAt(0, `😺`) == Some(0x1f63a) ``` @@ -173,7 +189,9 @@ a `Some(value)`. The return value handles code points greater than or equal to See [`String.codePointAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt) on MDN. -```res example +## Examples + +```rescript Js.String.codePointAt(1, `¿😺?`) == Some(0x1f63a) Js.String.codePointAt(5, "abc") == None ``` @@ -188,7 +206,9 @@ external codePointAt: int => option = "codePointAt" See [`String.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat) on MDN. -```res example +## Examples + +```rescript Js.String.concat("bell", "cow") == "cowbell" ``` */ @@ -203,7 +223,9 @@ array of strings added to the `original` string. See [`String.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat) on MDN. -```res example +## Examples + +```rescript Js.String.concatMany(["2nd", "3rd", "4th"], "1st") == "1st2nd3rd4th" ``` */ @@ -217,7 +239,9 @@ ES2015: `endsWith(substr, str)` returns `true` if the `str` ends with `substr`, See [`String.endsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith) on MDN. -```res example +## Examples + +```rescript Js.String.endsWith("Script", "ReScript") == true Js.String.endsWith("Script", "C++") == false ``` @@ -234,7 +258,9 @@ have been named endsWithAt, but oh well.) See [`String.endsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith) on MDN. -```res example +## Examples + +```rescript Js.String.endsWithFrom("cd", 4, "abcd") == true Js.String.endsWithFrom("cd", 3, "abcde") == false Js.String.endsWithFrom("cde", 99, "abcde") == true @@ -251,7 +277,9 @@ anywhere within `str`, false otherwise. See [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN. -```res example +## Examples + +```rescript Js.String.includes("gram", "programmer") == true Js.String.includes("er", "programmer") == true Js.String.includes("pro", "programmer") == true @@ -269,7 +297,9 @@ the first character), `false` otherwise. See [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN. -```res example +## Examples + +```rescript Js.String.includesFrom("gram", 1, "programmer") == true Js.String.includesFrom("gram", 4, "programmer") == false Js.String.includesFrom(`한`, 1, `대한민국`) == true @@ -285,7 +315,9 @@ was first found within `str`, or -1 if `searchValue` is not in `str`. See [`String.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf) on MDN. -```res example +## Examples + +```rescript Js.String.indexOf("ok", "bookseller") == 2 Js.String.indexOf("sell", "bookseller") == 4 Js.String.indexOf("ee", "beekeeper") == 1 @@ -305,7 +337,9 @@ from. See [`String.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf) on MDN. -```res example +## Examples + +```rescript Js.String.indexOfFrom("ok", 1, "bookseller") == 2 Js.String.indexOfFrom("sell", 2, "bookseller") == 4 Js.String.indexOfFrom("sell", 5, "bookseller") == -1 @@ -323,7 +357,9 @@ relative to the beginning of the string. See [`String.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf) on MDN. -```res example +## Examples + +```rescript Js.String.lastIndexOf("ok", "bookseller") == 2 Js.String.lastIndexOf("ee", "beekeeper") == 4 Js.String.lastIndexOf("xyz", "abcdefg") == -1 @@ -341,7 +377,9 @@ is always relative to the beginning of the string. See [`String.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf) on MDN. -```res example +## Examples + +```rescript Js.String.lastIndexOfFrom("ok", 6, "bookseller") == 2 Js.String.lastIndexOfFrom("ee", 8, "beekeeper") == 4 Js.String.lastIndexOfFrom("ee", 3, "beekeeper") == 1 @@ -361,7 +399,9 @@ external lastIndexOfFrom: (t, int) => int = "lastIndexOf" See [`String.localeCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) on MDN. -```res example +## Examples + +```rescript Js.String.localeCompare("ant", "zebra") > 0.0 Js.String.localeCompare("zebra", "ant") < 0.0 Js.String.localeCompare("cat", "cat") == 0.0 @@ -385,7 +425,9 @@ For regular expressions with the g modifier, a matched expression returns See [`String.match`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) on MDN. -```res example +## Examples + +```rescript Js.String.match_(%re("/b[aeiou]t/"), "The better bats") == Some(["bet"]) Js.String.match_(%re("/b[aeiou]t/g"), "The better bats") == Some(["bet", "bat"]) Js.String.match_(%re("/(\d+)-(\d+)-(\d+)/"), "Today is 2018-04-05.") == @@ -433,7 +475,9 @@ Raises `RangeError` if `n` is negative. See [`String.repeat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat) on MDN. -```res example +## Examples + +```rescript Js.String.repeat(3, "ha") == "hahaha" Js.String.repeat(0, "empty") == "" ``` @@ -450,7 +494,9 @@ regular expression. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript Js.String.replace("old", "new", "old string") == "new string" Js.String.replace("the", "this", "the cat and the dog") == "this cat and the dog" ``` @@ -465,7 +511,9 @@ matching regex have been replaced by `replacement`. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript Js.String.replaceByRe(%re("/[aeiou]/g"), "x", "vowels be gone") == "vxwxls bx gxnx" Js.String.replaceByRe(%re("/(\w+) (\w+)/"), "$2, $1", "Juan Fulano") == "Fulano, Juan" ``` @@ -482,7 +530,9 @@ match begins, and the whole string being matched. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript let str = "beautiful vowels" let re = %re("/[aeiou]/g") let matchFn = (matchPart, _offset, _wholeString) => Js.String.toUpperCase(matchPart) @@ -503,7 +553,9 @@ matched. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript let str = "Jony is 40" let re = %re("/(Jony is )\d+/g") let matchFn = (_match, part1, _offset, _wholeString) => { @@ -526,7 +578,9 @@ matched. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript let str = "7 times 6" let re = %re("/(\d+) times (\d+)/") let matchFn = (_match, p1, p2, _offset, _wholeString) => { @@ -562,7 +616,9 @@ external unsafeReplaceBy3: (Js_re.t, @uncurry (t, t, t, t, int, t) => t) => t = See [`String.search`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search) on MDN. -```res example +## Examples + +```rescript Js.String.search(%re("/\d+/"), "testing 1 2 3") == 8 Js.String.search(%re("/\d+/"), "no numbers") == -1 ``` @@ -579,7 +635,9 @@ character `n1` up to but not including `n2`. See [`String.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) on MDN. -```res example +## Examples + +```rescript Js.String.slice(~from=2, ~to_=5, "abcdefg") == "cde" Js.String.slice(~from=2, ~to_=9, "abcdefg") == "cdefg" Js.String.slice(~from=-4, ~to_=-2, "abcdefg") == "de" @@ -597,7 +655,9 @@ external slice: (~from: int, ~to_: int) => t = "slice" See [`String.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) on MDN. -```res example +## Examples + +```rescript Js.String.sliceToEnd(~from=4, "abcdefg") == "efg" Js.String.sliceToEnd(~from=-2, "abcdefg") == "fg" Js.String.sliceToEnd(~from=7, "abcdefg") == "" @@ -613,7 +673,9 @@ external sliceToEnd: (~from: int) => t = "slice" See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String.split("-", "2018-01-02") == ["2018", "01", "02"] Js.String.split(",", "a,b,,c") == ["a", "b", "", "c"] Js.String.split("::", "good::bad as great::awful") == ["good", "bad as great", "awful"] @@ -632,7 +694,9 @@ array will contain all the substrings. See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String.splitAtMost("/", ~limit=3, "ant/bee/cat/dog/elk") == ["ant", "bee", "cat"] Js.String.splitAtMost("/", ~limit=0, "ant/bee/cat/dog/elk") == [] Js.String.splitAtMost("/", ~limit=9, "ant/bee/cat/dog/elk") == ["ant", "bee", "cat", "dog", "elk"] @@ -648,7 +712,9 @@ and returns an array of the resulting substrings. See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String.splitByRe(%re(\"/\s*[,;]\s*/\"), \"art; bed , cog ;dad\") == [ Some(\"art\"), Some(\"bed\"), @@ -669,7 +735,9 @@ array will contain all the substrings. See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String.splitByReAtMost(%re(\"/\s*:\s*/\"), ~limit=3, \"one: two: three: four\") == [ Some(\"one\"), Some(\"two\"), @@ -696,7 +764,9 @@ ES2015: `startsWith(substr, str)` returns `true` if the `str` starts with See [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) on MDN. -```res example +## Examples + +```rescript Js.String.startsWith("Re", "ReScript") == true Js.String.startsWith("", "ReScript") == true Js.String.startsWith("Re", "JavaScript") == false @@ -713,7 +783,9 @@ the search starts at the beginning of `str`. See [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) on MDN. -```res example +## Examples + +```rescript Js.String.startsWithFrom("Scri", 2, "ReScript") == true Js.String.startsWithFrom("", 2, "ReScript") == true Js.String.startsWithFrom("Scri", 2, "JavaScript") == false @@ -734,7 +806,9 @@ JavaScript’s `String.substr()` is a legacy function. When possible, use See [`String.substr`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) on MDN. -```res example +## Examples + +```rescript Js.String.substr(~from=3, "abcdefghij") == "defghij" Js.String.substr(~from=-3, "abcdefghij") == "hij" Js.String.substr(~from=12, "abcdefghij") == "" @@ -756,7 +830,9 @@ JavaScript’s `String.substr()` is a legacy function. When possible, use See [`String.substr`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) on MDN. -```res example +## Examples + +```rescript Js.String.substrAtMost(~from=3, ~length=4, "abcdefghij") == "defg" Js.String.substrAtMost(~from=-3, ~length=4, "abcdefghij") == "hij" Js.String.substrAtMost(~from=12, ~length=2, "abcdefghij") == "" @@ -774,7 +850,9 @@ but not including finish from `str`. See [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN. -```res example +## Examples + +```rescript Js.String.substring(~from=3, ~to_=6, "playground") == "ygr" Js.String.substring(~from=6, ~to_=3, "playground") == "ygr" Js.String.substring(~from=4, ~to_=12, "playground") == "ground" @@ -791,7 +869,9 @@ position `start` to the end. See [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN. -```res example +## Examples + +```rescript Js.String.substringToEnd(~from=4, "playground") == "ground" Js.String.substringToEnd(~from=-3, "playground") == "playground" Js.String.substringToEnd(~from=12, "playground") == "" @@ -810,7 +890,9 @@ character in a string and another when it is not. See [`String.toLowerCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) on MDN. -```res example +## Examples + +```rescript Js.String.toLowerCase("ABC") == "abc" Js.String.toLowerCase(`ΣΠ`) == `σπ` Js.String.toLowerCase(`ΠΣ`) == `πς` @@ -837,7 +919,9 @@ capitalizes to two Ses in a row. See [`String.toUpperCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) on MDN. -```res example +## Examples + +```rescript Js.String.toUpperCase("abc") == "ABC" Js.String.toUpperCase(`Straße`) == `STRASSE` Js.String.toUpperCase(`πς`) == `ΠΣ` @@ -862,7 +946,9 @@ ends. Internal whitespace is not removed. See [`String.trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trim) on MDN. -```res example +## Examples + +```rescript Js.String.trim(" abc def ") == "abc def" Js.String.trim("\n\r\t abc def \n\n\t\r ") == "abc def" ``` @@ -880,7 +966,9 @@ not use this method, as it has been removed from the relevant web standards. See [`String.anchor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor) on MDN. -```res example +## Examples + +```rescript Js.String.anchor("page1", "Page One") == "Page One" ``` */ @@ -895,7 +983,9 @@ use this method, as it has been removed from the relevant web standards. See [`String.link`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link) on MDN. -```res example +## Examples + +```rescript Js.String.link("page2.html", "Go to page two") == "Go to page two" ``` */ @@ -905,7 +995,9 @@ external link: t => t = "link" Casts its argument to an `array_like` entity that can be processed by functions such as `Js.Array2.fromMap()` -```res example +## Examples + +```rescript let s = "abcde" let arr = Js.Array2.fromMap(Js.String.castToArrayLike(s), x => x) arr == ["a", "b", "c", "d", "e"] diff --git a/jscomp/others/js_string2.res b/jscomp/others/js_string2.res index 917987b717..998b60c6bc 100644 --- a/jscomp/others/js_string2.res +++ b/jscomp/others/js_string2.res @@ -30,7 +30,9 @@ type t = string /** `make(value)` converts the given value to a `string`. -```res example +## Examples + +```rescript Js.String2.make(3.5) == "3.5" Js.String2.make([1, 2, 3]) == "1,2,3" ``` @@ -47,7 +49,9 @@ the value are used. Thus, `fromCharCode(0x1F63A)` gives the same result as See [`String.fromCharCode`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCharCode) on MDN. -```res example +## Examples + +```rescript Js.String2.fromCharCode(65) == "A" Js.String2.fromCharCode(0x3c8) == `ψ` Js.String2.fromCharCode(0xd55c) == `한` @@ -78,7 +82,9 @@ unlike `fromCharCode(0x1F63A)`, and `fromCodePoint(-5)` will raise a See [`String.fromCodePoint`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint) on MDN. -```res example +## Examples + +```rescript Js.String2.fromCodePoint(65) == "A" Js.String2.fromCodePoint(0x3c8) == `ψ` Js.String2.fromCodePoint(0xd55c) == `한` @@ -97,7 +103,9 @@ corresponding to the given code point numbers, using the same rules as See [`String.fromCodePoint`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint) on MDN. -```res example +## Examples + +```rescript Js.String2.fromCodePointMany([0xd55c, 0xae00, 0x1f63a]) == `한글😺` ``` */ @@ -112,7 +120,9 @@ external fromCodePointMany: array => t = "String.fromCodePoint" See [`String.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) on MDN. -```res example +## Examples + +```rescript Js.String2.length("abcd") == 4 ``` */ @@ -124,7 +134,9 @@ external length: t => int = "length" `n` is out of range, this function returns `undefined`,so at some point this function may be modified to return `option`. -```res example +## Examples + +```rescript Js.String2.get("Reason", 0) == "R" Js.String2.get("Reason", 4) == "o" Js.String2.get(`Rẽasöń`, 5) == `ń` @@ -142,7 +154,9 @@ first 16-bit value at that position in the string. See [`String.charAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt) on MDN. -```res example +## Examples + +```rescript Js.String2.charAt("Reason", 0) == "R" Js.String2.charAt("Reason", 12) == "" Js.String2.charAt(`Rẽasöń`, 5) == `ń` @@ -161,7 +175,9 @@ zero or greater than the length of the string. See [`String.charCodeAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charCodeAt) on MDN. -```res example +## Examples + +```rescript Js.String2.charCodeAt(`😺`, 0) == 0xd83d->Belt.Int.toFloat Js.String2.codePointAt(`😺`, 0) == Some(0x1f63a) ``` @@ -178,7 +194,9 @@ a `Some(value)`. The return value handles code points greater than or equal to See [`String.codePointAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt) on MDN. -```res example +## Examples + +```rescript Js.String2.codePointAt(`¿😺?`, 1) == Some(0x1f63a) Js.String2.codePointAt("abc", 5) == None ``` @@ -193,7 +211,9 @@ external codePointAt: (t, int) => option = "codePointAt" See [`String.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat) on MDN. -```res example +## Examples + +```rescript Js.String2.concat("cow", "bell") == "cowbell" ``` */ @@ -208,7 +228,9 @@ array of strings added to the `original` string. See [`String.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat) on MDN. -```res example +## Examples + +```rescript Js.String2.concatMany("1st", ["2nd", "3rd", "4th"]) == "1st2nd3rd4th" ``` */ @@ -222,7 +244,9 @@ ES2015: `endsWith(str, substr)` returns `true` if the `str` ends with `substr`, See [`String.endsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith) on MDN. -```res example +## Examples + +```rescript Js.String2.endsWith("ReScript", "Script") == true Js.String2.endsWith("C++", "Script") == false ``` @@ -239,7 +263,9 @@ have been named endsWithAt, but oh well). See [`String.endsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith) on MDN. -```res example +## Examples + +```rescript Js.String2.endsWithFrom("abcd", "cd", 4) == true Js.String2.endsWithFrom("abcde", "cd", 3) == false Js.String2.endsWithFrom("abcde", "cde", 99) == true @@ -256,7 +282,9 @@ anywhere within `str`, false otherwise. See [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN. -```res example +## Examples + +```rescript Js.String2.includes("programmer", "gram") == true Js.String2.includes("programmer", "er") == true Js.String2.includes("programmer", "pro") == true @@ -274,7 +302,9 @@ the first character), `false` otherwise. See [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN. -```res example +## Examples + +```rescript Js.String2.includesFrom("programmer", "gram", 1) == true Js.String2.includesFrom("programmer", "gram", 4) == false Js.String2.includesFrom(`대한민국`, `한`, 1) == true @@ -290,7 +320,9 @@ was first found within `str`, or -1 if `searchValue` is not in `str`. See [`String.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf) on MDN. -```res example +## Examples + +```rescript Js.String2.indexOf("bookseller", "ok") == 2 Js.String2.indexOf("bookseller", "sell") == 4 Js.String2.indexOf("beekeeper", "ee") == 1 @@ -310,7 +342,9 @@ from. See [`String.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf) on MDN. -```res example +## Examples + +```rescript Js.String2.indexOfFrom("bookseller", "ok", 1) == 2 Js.String2.indexOfFrom("bookseller", "sell", 2) == 4 Js.String2.indexOfFrom("bookseller", "sell", 5) == -1 @@ -328,7 +362,9 @@ relative to the beginning of the string. See [`String.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf) on MDN. -```res example +## Examples + +```rescript Js.String2.lastIndexOf("bookseller", "ok") == 2 Js.String2.lastIndexOf("beekeeper", "ee") == 4 Js.String2.lastIndexOf("abcdefg", "xyz") == -1 @@ -346,7 +382,9 @@ is always relative to the beginning of the string. See [`String.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf) on MDN. -```res example +## Examples + +```rescript Js.String2.lastIndexOfFrom("bookseller", "ok", 6) == 2 Js.String2.lastIndexOfFrom("beekeeper", "ee", 8) == 4 Js.String2.lastIndexOfFrom("beekeeper", "ee", 3) == 1 @@ -366,7 +404,9 @@ external lastIndexOfFrom: (t, t, int) => int = "lastIndexOf" See [`String.localeCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) on MDN. -```res example +## Examples + +```rescript Js.String2.localeCompare("zebra", "ant") > 0.0 Js.String2.localeCompare("ant", "zebra") < 0.0 Js.String2.localeCompare("cat", "cat") == 0.0 @@ -389,7 +429,9 @@ For regular expressions with the g modifier, a matched expression returns See [`String.match`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) on MDN. -```res example +## Examples + +```rescript Js.String2.match_("The better bats", %re("/b[aeiou]t/")) == Some(["bet"]) Js.String2.match_("The better bats", %re("/b[aeiou]t/g")) == Some(["bet", "bat"]) Js.String2.match_("Today is 2018-04-05.", %re("/(\d+)-(\d+)-(\d+)/")) == @@ -435,7 +477,9 @@ Raises `RangeError` if `n` is negative. See [`String.repeat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat) on MDN. -```res example +## Examples + +```rescript Js.String2.repeat("ha", 3) == "hahaha" Js.String2.repeat("empty", 0) == "" ``` @@ -452,7 +496,9 @@ regular expression. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript Js.String2.replace("old string", "old", "new") == "new string" Js.String2.replace("the cat and the dog", "the", "this") == "this cat and the dog" ``` @@ -467,7 +513,9 @@ matching regex have been replaced by `replacement`. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript Js.String2.replaceByRe("vowels be gone", %re("/[aeiou]/g"), "x") == "vxwxls bx gxnx" Js.String2.replaceByRe("Juan Fulano", %re("/(\w+) (\w+)/"), "$2, $1") == "Fulano, Juan" ``` @@ -484,7 +532,9 @@ match begins, and the whole string being matched. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript let str = "beautiful vowels" let re = %re("/[aeiou]/g") let matchFn = (matchPart, _offset, _wholeString) => Js.String2.toUpperCase(matchPart) @@ -505,7 +555,9 @@ matched. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript let str = "Jony is 40" let re = %re("/(Jony is )\d+/g") let matchFn = (_match, part1, _offset, _wholeString) => { @@ -528,7 +580,9 @@ matched. See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) on MDN. -```res example +## Examples + +```rescript let str = "7 times 6" let re = %re("/(\d+) times (\d+)/") let matchFn = (_match, p1, p2, _offset, _wholeString) => { @@ -564,7 +618,9 @@ external unsafeReplaceBy3: (t, Js_re.t, @uncurry (t, t, t, t, int, t) => t) => t See [`String.search`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search) on MDN. -```res example +## Examples + +```rescript Js.String2.search("testing 1 2 3", %re("/\d+/")) == 8 Js.String2.search("no numbers", %re("/\d+/")) == -1 ``` @@ -581,7 +637,9 @@ character `n1` up to but not including `n2`. See [`String.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) on MDN. -```res example +## Examples + +```rescript Js.String2.slice("abcdefg", ~from=2, ~to_=5) == "cde" Js.String2.slice("abcdefg", ~from=2, ~to_=9) == "cdefg" Js.String2.slice("abcdefg", ~from=-4, ~to_=-2) == "de" @@ -599,7 +657,9 @@ external slice: (t, ~from: int, ~to_: int) => t = "slice" See [`String.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) on MDN. -```res example +## Examples + +```rescript Js.String2.sliceToEnd("abcdefg", ~from=4) == "efg" Js.String2.sliceToEnd("abcdefg", ~from=-2) == "fg" Js.String2.sliceToEnd("abcdefg", ~from=7) == "" @@ -615,7 +675,9 @@ external sliceToEnd: (t, ~from: int) => t = "slice" See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String2.split("2018-01-02", "-") == ["2018", "01", "02"] Js.String2.split("a,b,,c", ",") == ["a", "b", "", "c"] Js.String2.split("good::bad as great::awful", "::") == ["good", "bad as great", "awful"] @@ -626,7 +688,7 @@ external split: (t, t) => array = "split" @send /** - `splitAtMost delimiter ~limit: n str` splits the given `str` at every occurrence of `delimiter` and returns an array of the first `n` resulting substrings. If `n` is negative or greater than the number of substrings, the array will contain all the substrings. +`splitAtMost delimiter ~limit: n str` splits the given `str` at every occurrence of `delimiter` and returns an array of the first `n` resulting substrings. If `n` is negative or greater than the number of substrings, the array will contain all the substrings. ``` splitAtMost "ant/bee/cat/dog/elk" "/" ~limit: 3 = [|"ant"; "bee"; "cat"|];; @@ -644,7 +706,9 @@ and returns an array of the resulting substrings. See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String2.splitByRe("art; bed , cog ;dad", %re("/\s*[,;]\s*TODO/")) == [ Some("art"), Some("bed"), @@ -665,7 +729,9 @@ array will contain all the substrings. See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split) on MDN. -```res example +## Examples + +```rescript Js.String2.splitByReAtMost("one: two: three: four", %re("/\s*:\s*TODO/"), ~limit=3) == [ Some("one"), Some("two"), @@ -692,7 +758,9 @@ ES2015: `startsWith(str, substr)` returns `true` if the `str` starts with See [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) on MDN. -```res example +## Examples + +```rescript Js.String2.startsWith("ReScript", "Re") == true Js.String2.startsWith("ReScript", "") == true Js.String2.startsWith("JavaScript", "Re") == false @@ -709,7 +777,9 @@ the search starts at the beginning of `str`. See [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) on MDN. -```res example +## Examples + +```rescript Js.String2.startsWithFrom("ReScript", "Scri", 2) == true Js.String2.startsWithFrom("ReScript", "", 2) == true Js.String2.startsWithFrom("JavaScript", "Scri", 2) == false @@ -730,7 +800,9 @@ JavaScript’s `String.substr()` is a legacy function. When possible, use See [`String.substr`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) on MDN. -```res example +## Examples + +```rescript Js.String2.substr("abcdefghij", ~from=3) == "defghij" Js.String2.substr("abcdefghij", ~from=-3) == "hij" Js.String2.substr("abcdefghij", ~from=12) == "" @@ -752,7 +824,9 @@ JavaScript’s `String.substr()` is a legacy function. When possible, use See [`String.substr`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) on MDN. -```res example +## Examples + +```rescript Js.String2.substrAtMost("abcdefghij", ~from=3, ~length=4) == "defg" Js.String2.substrAtMost("abcdefghij", ~from=-3, ~length=4) == "hij" Js.String2.substrAtMost("abcdefghij", ~from=12, ~length=2) == "" @@ -770,7 +844,9 @@ but not including finish from `str`. See [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN. -```res example +## Examples + +```rescript Js.String2.substring("playground", ~from=3, ~to_=6) == "ygr" Js.String2.substring("playground", ~from=6, ~to_=3) == "ygr" Js.String2.substring("playground", ~from=4, ~to_=12) == "ground" @@ -787,7 +863,9 @@ position `start` to the end. See [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN. -```res example +## Examples + +```rescript Js.String2.substringToEnd("playground", ~from=4) == "ground" Js.String2.substringToEnd("playground", ~from=-3) == "playground" Js.String2.substringToEnd("playground", ~from=12) == "" @@ -806,7 +884,9 @@ character in a string and another when it is not. See [`String.toLowerCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) on MDN. -```res example +## Examples + +```rescript Js.String2.toLowerCase("ABC") == "abc" Js.String2.toLowerCase(`ΣΠ`) == `σπ` Js.String2.toLowerCase(`ΠΣ`) == `πς` @@ -832,7 +912,9 @@ capitalizes to two Ses in a row. See [`String.toUpperCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) on MDN. -```res example +## Examples + +```rescript Js.String2.toUpperCase("abc") == "ABC" Js.String2.toUpperCase(`Straße`) == `STRASSE` Js.String2.toUpperCase(`πς`) == `ΠΣ` @@ -856,7 +938,9 @@ ends. Internal whitespace is not removed. See [`String.trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trim) on MDN. -```res example +## Examples + +```rescript Js.String2.trim(" abc def ") == "abc def" Js.String2.trim("\n\r\t abc def \n\n\t\r ") == "abc def" ``` @@ -874,7 +958,9 @@ not use this method, as it has been removed from the relevant web standards. See [`String.anchor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor) on MDN. -```res example +## Examples + +```rescript Js.String2.anchor("Page One", "page1") == "Page One" ``` */ @@ -888,7 +974,9 @@ use this method, as it has been removed from the relevant web standards. See [`String.link`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link) on MDN. -```res example +## Examples + +```rescript Js.String2.link("Go to page two", "page2.html") == "Go to page two" ``` */ @@ -902,7 +990,9 @@ external link: (t, t) => t = "link" Casts its argument to an `array_like` entity that can be processed by functions such as `Js.Array2.fromMap()` -```res example +## Examples + +```rescript let s = "abcde" let arr = Js.Array2.fromMap(Js.String2.castToArrayLike(s), x => x) arr == ["a", "b", "c", "d", "e"] diff --git a/jscomp/others/js_typed_array.res b/jscomp/others/js_typed_array.res index e9785c4e20..21b010b1a0 100644 --- a/jscomp/others/js_typed_array.res +++ b/jscomp/others/js_typed_array.res @@ -23,9 +23,9 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - JavaScript Typed Array API +JavaScript Typed Array API - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) +**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) */ @@warning("-103") @@ -38,9 +38,9 @@ module type Type = { } module ArrayBuffer = { /*** - The underlying buffer that the typed arrays provide views of + The underlying buffer that the typed arrays provide views of - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) + **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) */ type t = array_buffer @@ -272,18 +272,19 @@ module Int8Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Int8Array" - @new /** - **raise** Js.Exn.Error raise Js exception + /** + raise Js.Exn.Error raise Js exception - **param** offset is in bytes + param offset is in bytes */ + @new external fromBufferOffset: (array_buffer, int) => t = "Int8Array" @new /** - **raise** Js.Exn.Error raises Js exception + raise Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + param offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Int8Array" @@ -394,18 +395,19 @@ module Uint8Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint8Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint8Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint8Array" @@ -516,18 +518,19 @@ module Uint8ClampedArray = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint8ClampedArray" - @new /** - **raise** Js.Exn.Error raise Js exception + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ + @new external fromBufferOffset: (array_buffer, int) => t = "Uint8ClampedArray" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint8ClampedArray" @@ -638,18 +641,19 @@ module Int16Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Int16Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Int16Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Int16Array" @@ -760,18 +764,19 @@ module Uint16Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint16Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint16Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint16Array" @@ -882,18 +887,19 @@ module Int32Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Int32Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Int32Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Int32Array" @@ -1007,18 +1013,19 @@ module Uint32Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint32Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint32Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint32Array" @@ -1132,18 +1139,19 @@ module Float32Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Float32Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Float32Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Float32Array" @@ -1258,18 +1266,19 @@ module Float64Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Float64Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Float64Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Float64Array" @@ -1283,10 +1292,10 @@ module Float64Array = { module Float64_array = Float64Array /** - The DataView view provides a low-level interface for reading and writing - multiple number types in an ArrayBuffer irrespective of the platform's endianness. +The DataView view provides a low-level interface for reading and writing +multiple number types in an ArrayBuffer irrespective of the platform's endianness. - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) +**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) */ module DataView = { type t = Js_typed_array2.DataView.t diff --git a/jscomp/others/js_typed_array2.res b/jscomp/others/js_typed_array2.res index bc00395f7f..93bae0e0bc 100644 --- a/jscomp/others/js_typed_array2.res +++ b/jscomp/others/js_typed_array2.res @@ -23,9 +23,9 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - JavaScript Typed Array API +JavaScript Typed Array API - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) +**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) */ type array_buffer @@ -33,9 +33,9 @@ type array_like<'a> /* should be shared with js_array */ module ArrayBuffer = { /*** - The underlying buffer that the typed arrays provide views of + The underlying buffer that the typed arrays provide views of - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) + **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) */ type t = array_buffer @@ -160,18 +160,19 @@ module Int8Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Int8Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Int8Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Int8Array" @@ -281,18 +282,19 @@ module Uint8Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint8Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint8Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint8Array" @@ -402,18 +404,19 @@ module Uint8ClampedArray = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint8ClampedArray" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint8ClampedArray" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint8ClampedArray" @@ -523,18 +526,19 @@ module Int16Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Int16Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Int16Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Int16Array" @@ -644,18 +648,19 @@ module Uint16Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint16Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint16Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint16Array" @@ -765,18 +770,19 @@ module Int32Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Int32Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Int32Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Int32Array" @@ -886,18 +892,19 @@ module Uint32Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Uint32Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Uint32Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Uint32Array" @@ -1010,18 +1017,19 @@ module Float32Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Float32Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Float32Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Float32Array" @@ -1131,18 +1139,19 @@ module Float64Array = { @new /** can throw */ external fromBuffer: array_buffer => t = "Float64Array" - @new /** - **raise** Js.Exn.Error raise Js exception + @new + /** + **raise** Js.Exn.Error raise Js exception - **param** offset is in bytes + **param** offset is in bytes */ external fromBufferOffset: (array_buffer, int) => t = "Float64Array" @new /** - **raise** Js.Exn.Error raises Js exception + **raise** Js.Exn.Error raises Js exception - **param** offset is in bytes, length in elements + **param** offset is in bytes, length in elements */ external fromBufferRange: (array_buffer, ~offset: int, ~length: int) => t = "Float64Array" @@ -1152,10 +1161,10 @@ module Float64Array = { } /** - The DataView view provides a low-level interface for reading and writing - multiple number types in an ArrayBuffer irrespective of the platform's endianness. +The DataView view provides a low-level interface for reading and writing +multiple number types in an ArrayBuffer irrespective of the platform's endianness. - **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) +**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) */ module DataView = { type t diff --git a/jscomp/others/js_types.resi b/jscomp/others/js_types.resi index c85898e19e..f267cd2c79 100644 --- a/jscomp/others/js_types.resi +++ b/jscomp/others/js_types.resi @@ -52,14 +52,16 @@ type rec t<_> = | BigInt: t /** - `test(value, t)` returns `true` if `value` is `typeof t`, otherwise `false`. - This is useful for doing runtime reflection on any given value. +`test(value, t)` returns `true` if `value` is `typeof t`, otherwise `false`. +This is useful for doing runtime reflection on any given value. - ```res example - test("test", String) == true - test(() => true, Function) == true - test("test", Boolean) == false - ``` +## Examples + +```rescript +test("test", String) == true +test(() => true, Function) == true +test("test", Boolean) == false +``` */ let test: ('a, t<'b>) => bool diff --git a/jscomp/others/js_undefined.resi b/jscomp/others/js_undefined.resi index f1eace9f42..cfa08b6671 100644 --- a/jscomp/others/js_undefined.resi +++ b/jscomp/others/js_undefined.resi @@ -53,7 +53,9 @@ If `Js.undefined<'a>` contains a value, that value is unwrapped, mapped to a `'b` using the given function `a' => 'b`, then wrapped back up and returned as `Js.undefined<'b>`. -```res example +## Examples + +```rescript let maybeGreetWorld = (maybeGreeting: Js.undefined) => Js.Undefined.bind(maybeGreeting, (. greeting) => greeting ++ " world!") ``` @@ -65,7 +67,9 @@ Iterates over the contained value with the given function. If `Js.undefined<'a>` contains a value, that value is unwrapped and applied to the given function. -```res example +## Examples + +```rescript let maybeSay = (maybeMessage: Js.undefined) => Js.Undefined.iter(maybeMessage, (. message) => Js.log(message)) ``` diff --git a/jscomp/others/js_vector.res b/jscomp/others/js_vector.res index 00d3433871..15b1ff0945 100644 --- a/jscomp/others/js_vector.res +++ b/jscomp/others/js_vector.res @@ -31,9 +31,10 @@ external make: (int, 'a) => array<'a> = "?make_vect" external unsafe_get: (t<'a>, int) => 'a = "%array_unsafe_get" external unsafe_set: (t<'a>, int, 'a) => unit = "%array_unsafe_set" -/** **param** a array +/** +**param** a array - **param** p predicate +**param** p predicate */ let filterInPlace = (p, a) => { let i = ref(0) diff --git a/jscomp/others/map.cppo.resi b/jscomp/others/map.cppo.resi index dd720d3299..61cfec2b03 100644 --- a/jscomp/others/map.cppo.resi +++ b/jscomp/others/map.cppo.resi @@ -21,54 +21,56 @@ let cmp: (t<'v>, t<'v>, ('v, 'v) => int) => int let eqU: (t<'v>, t<'v>, (. 'v, 'v) => bool) => bool /** - `eq m1 m2` tests whether the maps `m1` and `m2` are - equal, that is, contain equal keys and associate them with - equal data. +`eq(m1, m2)` tests whether the maps `m1` and `m2` are +equal, that is, contain equal keys and associate them with +equal data. */ let eq: (t<'v>, t<'v>, ('v, 'v) => bool) => bool let findFirstByU: (t<'v>, (. key, 'v) => bool) => option<(key, 'v)> /** - `findFirstBy m p` uses funcion `f` to find the first key value pair - to match predicate `p`. +`findFirstBy(m, p)` uses funcion `f` to find the first key value pair +to match predicate `p`. - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");; - ``` +```rescript +let s0 = fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2,"(3, ""))]) +findFirstBy(s0, (k, v) => k == 4) == option((4, "4")) +``` */ let findFirstBy: (t<'v>, (key, 'v) => bool) => option<(key, 'v)> let forEachU: (t<'v>, (. key, 'v) => unit) => unit /** - `forEach m f` applies `f` to all bindings in map `m`. - `f` receives the key as first argument, and the associated value - as second argument. The bindings are passed to `f` in increasing - order with respect to the ordering over the type of the keys. +`forEach(m, f)` applies `f` to all bindings in map `m`. +`f` receives the key as first argument, and the associated value +as second argument. The bindings are passed to `f` in increasing +order with respect to the ordering over the type of the keys. */ let forEach: (t<'v>, (key, 'v) => unit) => unit let reduceU: (t<'v>, 'v2, (. 'v2, key, 'v) => 'v2) => 'v2 /** - `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`, - where `k1 ... kN` are the keys of all bindings in `m` - (in increasing order), and `d1 ... dN` are the associated data. +`reduce(m, a, f)` computes `(f kN dN ... (f k1 d1 a)...)`, +where `k1 ... kN` are the keys of all bindings in `m` +(in increasing order), and `d1 ... dN` are the associated data. */ let reduce: (t<'v>, 'v2, ('v2, key, 'v) => 'v2) => 'v2 let everyU: (t<'v>, (. key, 'v) => bool) => bool -/** `every m p` checks if all the bindings of the map - satisfy the predicate `p`. Order unspecified */ +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +Order unspecified */ let every: (t<'v>, (key, 'v) => bool) => bool let someU: (t<'v>, (. key, 'v) => bool) => bool -/** `some m p` checks if at least one binding of the map - satisfy the predicate `p`. Order unspecified */ +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate +`p`. Order unspecified */ let some: (t<'v>, (key, 'v) => bool) => bool let size: t<'v> => int @@ -109,7 +111,7 @@ let getWithDefault: (t<'v>, key, 'v) => 'v let getExn: (t<'v>, key) => 'v /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t<_> => unit @@ -120,9 +122,9 @@ let remove: (t<'v>, key) => t<'v> let removeMany: (t<'v>, array) => t<'v> /** - `set m x y` returns a map containing the same bindings as - `m`, plus a binding of `x` to `y`. If `x` was already bound - in `m`, its previous binding disappears. +`set(m, x, y)` returns a map containing the same bindings as +`m`, plus a binding of `x` to `y`. If `x` was already bound +in `m`, its previous binding disappears. */ let set: (t<'v>, key, 'v) => t<'v> @@ -132,9 +134,9 @@ let update: (t<'v>, key, option<'v> => option<'v>) => t<'v> let mergeU: (t<'v>, t<'v2>, (. key, option<'v>, option<'v2>) => option<'c>) => t<'c> /** - `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1` - and of `m2`. The presence of each such binding, and the corresponding - value, is determined with the function `f`. +`merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1` +and of `m2`. The presence of each such binding, and the corresponding +value, is determined with the function `f`. */ let merge: (t<'v>, t<'v2>, (key, option<'v>, option<'v2>) => option<'c>) => t<'c> @@ -142,39 +144,36 @@ let mergeMany: (t<'v>, array<(key, 'v)>) => t<'v> let keepU: (t<'v>, (. key, 'v) => bool) => t<'v> -/** `keep m p` returns the map with all the bindings in `m` - that satisfy predicate `p`. */ +/** +`keep(m, p)` returns the map with all the bindings in `m` that satisfy predicate +`p`. +*/ let keep: (t<'v>, (key, 'v) => bool) => t<'v> let partitionU: (t<'v>, (. key, 'v) => bool) => (t<'v>, t<'v>) /** - `partition m p` returns a pair of maps `(m1, m2)`, where - `m1` contains all the bindings of `s` that satisfy the - predicate `p`, and `m2` is the map with all the bindings of - `s` that do not satisfy `p`. +`partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains all the +bindings of `s` that satisfy the predicate `p`, and `m2` is the map with all the +bindings of `s` that do not satisfy `p`. */ let partition: (t<'v>, (key, 'v) => bool) => (t<'v>, t<'v>) /** - `split x m` returns a triple `(l, data, r)`, where - `l` is the map with all the bindings of `m` whose key - is strictly less than `x`; - `r` is the map with all the bindings of `m` whose key - is strictly greater than `x`; - `data` is `None` if `m` contains no binding for `x`, - or `Some v` if `m` binds `v` to `x`. +`split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with all the +bindings of `m` whose key is strictly less than `x`; `r` is the map with all the +bindings of `m` whose key is strictly greater than `x`; `data` is `None` if `m` +contains no binding for `x`, or `Some(v)` if `m` binds `v` to `x`. */ let split: (key, t<'v>) => (t<'v>, option<'v>, t<'v>) let mapU: (t<'v>, (. 'v) => 'v2) => t<'v2> /** - `map m f` returns a map with same domain as `m`, where the - associated value `a` of all bindings of `m` has been - replaced by the result of the application of `f` to `a`. - The bindings are passed to `f` in increasing order - with respect to the ordering over the type of the keys. +`map(m, f)` returns a map with same domain as `m`, where the associated value `a` +of all bindings of `m` has been replaced by the result of the application of `f` +to `a`. The bindings are passed to `f` in increasing order with respect to the +ordering over the type of the keys. */ let map: (t<'v>, 'v => 'v2) => t<'v2> diff --git a/jscomp/others/mapm.cppo.resi b/jscomp/others/mapm.cppo.resi index 4d1fb481e5..c4f15560fe 100644 --- a/jscomp/others/mapm.cppo.resi +++ b/jscomp/others/mapm.cppo.resi @@ -40,45 +40,46 @@ let has: (t<'a>, key) => bool let cmpU: (t<'a>, t<'a>, (. 'a, 'a) => int) => int -/** `cmp m1 m2 cmp` - First compare by size, if size is the same, - compare by key, value pair +/** +`cmp(m1, m2, cmp)`. First compare by size, if size is the same, compare by key, +value pair */ let cmp: (t<'a>, t<'a>, ('a, 'a) => int) => int let eqU: (t<'a>, t<'a>, (. 'a, 'a) => bool) => bool -/** `eq m1 m2 cmp` */ +/** `eq(m1, m2, cmp)` */ let eq: (t<'a>, t<'a>, ('a, 'a) => bool) => bool let forEachU: (t<'a>, (. key, 'a) => unit) => unit -/** `forEach m f` applies `f` to all bindings in map `m`. - `f` receives the key as first argument, and the associated value - as second argument. - The application order of `f` is in increasing order. */ +/** +`forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the key as +first argument, and the associated value as second argument. The application +order of `f` is in increasing order. */ let forEach: (t<'a>, (key, 'a) => unit) => unit let reduceU: (t<'a>, 'b, (. 'b, key, 'a) => 'b) => 'b -/** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`, - where `k1 ... kN` are the keys of all bindings in `m` - (in increasing order), and `d1 ... dN` are the associated data. */ +/** +`reduce(m, a, f)` computes `(f kN dN ... (f k1 d1 a)...)`, where `k1 ... kN` are +the keys of all bindings in `m` (in increasing order), and `d1 ... dN` are the +associated data. */ let reduce: (t<'a>, 'b, ('b, key, 'a) => 'b) => 'b let everyU: (t<'a>, (. key, 'a) => bool) => bool -/** `every m p` checks if all the bindings of the map - satisfy the predicate `p`. - The application order of `p` is unspecified. +/** +`every(m, p)` checks if all the bindings of the map satisfy the predicate `p`. +The application order of `p` is unspecified. */ let every: (t<'a>, (key, 'a) => bool) => bool let someU: (t<'a>, (. key, 'a) => bool) => bool -/** `some m p` checks if at least one binding of the map - satisfy the predicate `p`. - The application order of `p` is unspecified. +/** +`some(m, p)` checks if at least one binding of the map satisfy the predicate `p`. +The application order of `p` is unspecified. */ let some: (t<'a>, (key, 'a) => bool) => bool @@ -115,14 +116,15 @@ let checkInvariantInternal: t<_> => unit /* TODO: add functional `merge, partition, keep, split` */ -/** `remove m x` do the in-place modification */ +/** `remove(m, x)` do the in-place modification */ let remove: (t<'a>, key) => unit let removeMany: (t<'a>, array) => unit -/** `set m x y` do the in-place modification, return - `m` for chaining. If `x` was already bound - in `m`, its previous binding disappears. */ +/** +`set(m, x, y)` do the in-place modification, return `m` for chaining. If `x` was +already bound in `m`, its previous binding disappears. +*/ let set: (t<'a>, key, 'a) => unit let updateU: (t<'a>, key, (. option<'a>) => option<'a>) => unit @@ -130,11 +132,11 @@ let update: (t<'a>, key, option<'a> => option<'a>) => unit let mapU: (t<'a>, (. 'a) => 'b) => t<'b> -/** `map m f` returns a map with same domain as `m`, where the - associated value `a` of all bindings of `m` has been - replaced by the result of the application of `f` to `a`. - The bindings are passed to `f` in increasing order - with respect to the ordering over the type of the keys. */ +/** +`map(m, f)` returns a map with same domain as `m`, where the associated value `a` +of all bindings of `m` has been replaced by the result of the application of `f` +to `a`. The bindings are passed to `f` in increasing order with respect to the +ordering over the type of the keys. */ let map: (t<'a>, 'a => 'b) => t<'b> let mapWithKeyU: (t<'a>, (. key, 'a) => 'b) => t<'b> diff --git a/jscomp/others/setm.cppo.resi b/jscomp/others/setm.cppo.resi index 7ae45b3205..c51fd0a3f8 100644 --- a/jscomp/others/setm.cppo.resi +++ b/jscomp/others/setm.cppo.resi @@ -23,12 +23,12 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /*** - This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type. +This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type. - It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, - and identity is not needed(using the built-in one) +It is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed, +and identity is not needed(using the built-in one) - **See** [`Belt.MutableSet`]() +**See** [`Belt.MutableSet`]() */ #ifdef TYPE_STRING @@ -80,28 +80,34 @@ let reduce: (t, 'a, ('a, value) => 'a) => 'a let everyU: (t, (. value) => bool) => bool -/** `every p s` checks if all elements of the set - satisfy the predicate `p`. Order unspecified. */ +/** +`every(p, s)` checks if all elements of the set satisfy the predicate `p`. +Order unspecified. */ let every: (t, value => bool) => bool let someU: (t, (. value) => bool) => bool -/** `some p s` checks if at least one element of - the set satisfies the predicate `p`. Oder unspecified. */ +/** +`some(p, s)` checks if at least one element of the set satisfies the predicate +`p`. Oder unspecified. +*/ let some: (t, value => bool) => bool let keepU: (t, (. value) => bool) => t -/** `keep s p` returns a fresh copy of the set of all elements in `s` - that satisfy predicate `p`. */ +/** +`keep(s, p)` returns a fresh copy of the set of all elements in `s` that satisfy +predicate `p`. +*/ let keep: (t, value => bool) => t let partitionU: (t, (. value) => bool) => (t, t) -/** `partition s p` returns a fresh copy pair of sets `(s1, s2)`, where - `s1` is the set of all the elements of `s` that satisfy the - predicate `p`, and `s2` is the set of all the elements of - `s` that do not satisfy `p`. */ +/** +`partition(s, p)` returns a fresh copy pair of sets `(s1, s2)`, where `s1` is +the set of all the elements of `s` that satisfy the predicate `p`, and `s2` is +the set of all the elements of `s` that do not satisfy `p`. +*/ let partition: (t, value => bool) => (t, t) let size: t => int @@ -122,11 +128,11 @@ let getUndefined: (t, value) => Js.undefined let getExn: (t, value) => value /** - `split s key` return a fresh copy of each +`split(s, key)` return a fresh copy of each */ let split: (t, value) => ((t, t), bool) /** - **raise** when invariant is not held +**raise** when invariant is not held */ let checkInvariantInternal: t => unit diff --git a/jscomp/others/sort.cppo.resi b/jscomp/others/sort.cppo.resi index 3a3d9e1c82..8570da496f 100644 --- a/jscomp/others/sort.cppo.resi +++ b/jscomp/others/sort.cppo.resi @@ -22,8 +22,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ -/*** This is a specialized module for [`Belt_SortArray`](), the docs in that module also - applies here, except the comparator is fixed and inlined +/*** +This is a specialized module for [`Belt_SortArray`](), the docs in that module also +applies here, except the comparator is fixed and inlined */ #ifdef TYPE_INT @@ -35,42 +36,43 @@ type element = string #endif /** - The same as [`Belt_SortArray.strictlySortedLength`]() except the comparator is fixed +The same as [`Belt_SortArray.strictlySortedLength`]() except the comparator is fixed - **return** `+n` means increasing order `-n` means negative order +**return** `+n` means increasing order `-n` means negative order */ let strictlySortedLength: array => int -/** `sorted xs` return true if `xs` is in non strict increasing order */ +/** `sorted(xs)` return true if `xs` is in non strict increasing order */ let isSorted: array => bool /** - The same as [`Belt_SortArray.stableSortInPlaceBy`]() except the comparator is fixed +The same as [`Belt_SortArray.stableSortInPlaceBy`]() except the comparator is fixed */ let stableSortInPlace: array => unit -/** The same as [`Belt_SortArray.stableSortBy`]() except the comparator is fixed */ +/** +The same as [`Belt_SortArray.stableSortBy`]() except the comparator is fixed +*/ let stableSort: array => array /** - If value is not found and value is less than one or more elements in array, - the negative number returned is the bitwise complement of the index of the first element - that is larger than value. +If value is not found and value is less than one or more elements in array, +the negative number returned is the bitwise complement of the index of the first element +that is larger than value. - If value is not found and value is greater than all elements in array, - the negative number returned is the bitwise complement of - (the index of the last element plus 1) +If value is not found and value is greater than all elements in array, +the negative number returned is the bitwise complement of +(the index of the last element plus 1) - for example, if `key` is smaller than all elements return `-1` since `lnot (-1) = 0` - if `key` is larger than all elements return `- (len + 1)` since `lnot (-(len+1)) = len` +for example, if `key` is smaller than all elements return `-1` since `lnot (-1) = 0` +if `key` is larger than all elements return `- (len + 1)` since `lnot (-(len+1)) = len` */ let binarySearch: (array, element) => int /** - `union src src1ofs src1len src2 src2ofs src2len dst dstofs cmp` - assume `src` and `src2` is strictly sorted. - for equivalent elements, it is picked from `src` - also assume that `dst` is large enough to store all elements +`union(src, src1ofs, src1len, src2, src2ofs, src2len, dst, dstofs, cmp)` assume +`src` and `src2` is strictly sorted. for equivalent elements, it is picked from +`src` also assume that `dst` is large enough to store all elements */ let union: (array, int, int, array, int, int, array, int) => int