diff --git a/jscomp/others/belt_Map.mli b/jscomp/others/belt_Map.mli index ce9b7040d1..344c09ba4c 100644 --- a/jscomp/others/belt_Map.mli +++ b/jscomp/others/belt_Map.mli @@ -12,55 +12,26 @@ (* Adapted by authors of ReScript without using functors *) (***********************************************************************) -(** A _immutable_ sorted map module which allows customize _compare_ behavior. +(** The top level provides generic immutable map operations. - The implementation uses balanced binary trees, and therefore searching - and insertion take time logarithmic in the size of the map. + It also has three specialized inner modules `Belt.Map.Int`, + `Belt.Map.String` and `Belt.Map.Dict`. *) - 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: - - ``` - module PairComparator = Belt.Id.MakeComparable(struct - type t = int * int - let cmp (a0, a1) (b0, b1) = - match Pervasives.compare a0 b0 with - | 0 -> Pervasives.compare a1 b1 - | c -> c - end) - - let myMap = Belt.Map.make ~id:(module PairComparator) - let myMap2 = Belt.Map.set myMap (1, 2) "myValue" +(* ```res prelude + type t<'key, 'value, 'identity> + type id<'key, 'id> = Belt_Id.comparable<'key, 'id> ``` - - The API documentation below will assume a predeclared comparator module for integers, IntCmp *) - -(** Specalized when key type is `int`, more efficient - than the generic type, its compare behavior is fixed using the built-in comparison -*) module Int = Belt_MapInt -(** specalized when key type is `string`, more efficient - than the generic type, its compare behavior is fixed using the built-in comparison *) module String = Belt_MapString -(** This module seprate identity from data, it is a bit more verboe 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** -*) module Dict = Belt_MapDict type ('key, 'value, 'identity) t -(** `('key, 'identity) t` - - `'key` is the field type +(** `'key` is the field type `'value` is the element type @@ -69,51 +40,47 @@ type ('key, 'value, 'identity) t type ('key, 'id) id = ('key, 'id) Belt_Id.comparable -(** The identity needed for making an empty map*) +(** The identity needed for making an empty map. *) +val make: id:('k, 'id) id -> ('k, 'v, 'id) t +(** `make(~id)` creates a new map by taking in the comparator. -(* - How we retain soundness: - The only way to create a value of type `_ t` from scratch - is through `empty` which requires `_ Belt_Id.t` - The only way to create `_ Belt_Id.t` is using `Belt_Id.Make` which - will create a fresh type `id` per module - - Generic operations over tree without `cmp` are still exported - (for efficient reasons) so that `data` does not need be boxed and unboxed. - - The soundness is guaranteed in two aspects: - When create a value of `_ t` it needs both `_ Belt_Id.t` and `_ t0`. - `_ Belt_Id.t` is an abstract type. Note `add0` requires `_ Belt_Id.cmp` which - is also an abstract type which can only come from `_ Belt_Id.t` - - When destructing a value of `_ t`, the `'id` parameter is threaded. - -*) - -(* should not export `Belt_Id.compare`. - should only export `Belt_Id.t` or `Belt_Id.cmp` instead *) + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) + }) + let m = Belt.Map.make(~id=module(IntCmp)) -val make: id:('k, 'id) id -> ('k, 'v, 'id) t -(** `make ~id` creates a new map by taking in the comparator - ``` - let m = Belt.Map.make ~id:(module IntCmp) + Belt.Map.set(m, 0, "a") ``` *) val isEmpty: _ t -> bool -(** `isEmpty m` checks whether a map m is empty - ``` - isEmpty (fromArray [|1,"1"|] ~id:(module IntCmp)) = false +(** `isEmpty(m)` checks whether a map m is empty. + + ```res example + 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 ``` *) val has: ('k, 'v, 'id) t -> 'k -> bool -(** `has m k` checks whether m has the key k - ``` - has (fromArray [|1,"1"|] ~id:(module IntCmp)) 1 = true +(** `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) + }) + + Belt.Map.has(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp)), 1) == true ``` *) @@ -127,7 +94,7 @@ val cmp: ('k, 'v, 'id) t -> ('v -> 'v -> int ) -> int -(** `cmp m0 m1 vcmp` +(** `cmp(m0, m1, vcmp);` Total ordering of map given total ordering of value function. @@ -144,233 +111,294 @@ val eq: ('k, 'v, 'id) t -> ('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. *) val findFirstByU : ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) -> ('k * 'v) option val findFirstBy : ('k, 'v, 'id) t -> ('k -> 'v -> bool ) -> ('k * 'v) option -(** `findFirstBy m p` uses funcion `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`. - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");; + ```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, "")]) + + Belt.Map.findFirstBy(s0, (k, v) => k == 4) /* (4, "4") */ ``` *) val forEachU: ('k, 'v, 'id) t -> ('k -> 'v -> unit [@bs]) -> unit val forEach: ('k, 'v, 'id) t -> ('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. - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - let acc = ref [] ;; - forEach s0 (fun k v -> acc := (k,v) :: !acc);; + ```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, "")]) - !acc = [4,"4"; 3,"3"; 2,"2"; 1,"1"] + let acc = ref(list{}) + + Belt.Map.forEach(s0, (k, v) => acc := list{(k, v), ...acc.contents}) + + acc.contents == list{(4, "4"), (3, "3"), (2, "2"), (1, "1")} ``` *) val reduceU: ('k, 'v, 'id) t -> 'acc -> ('acc -> 'k -> 'v -> 'acc [@bs]) -> 'acc val reduce: ('k, 'v, 'id) t -> '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. - - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - reduce s0 [] (fun acc k v -> (k,v) acc ) = [4,"4";3,"3";2,"2";1,"1"];; +(** `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] */ ``` *) val everyU: ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) -> bool val every: ('k, 'v, 'id) t -> ('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 *) val someU: ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) -> bool val some: ('k, 'v, 'id) t -> ('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 *) val size: ('k, 'v, 'id) t -> int -(** `size s` +(** `size(s)` - ``` - size (fromArray [2,"2"; 2,"1"; 3,"3"] ~id:(module IntCmp)) = 2 ;; + ```res example + 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 ``` *) val toArray: ('k, 'v, 'id) t -> ('k * 'v) array -(** `toArray s` - +(** `toArray(s)` + + ```res example + 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"), + ] ``` - toArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) = [1,"1";2,"2";3,"3"] - ``` - *) val toList: ('k, 'v, 'id) t -> ('k * 'v) list -(** In increasing order +(** In increasing order. - **See** [`toArray`]() + See `Belt.Map.toArray` *) val fromArray: ('k * 'v) array -> id:('k,'id) id -> ('k,'v,'id) t -(** `fromArray kvs ~id` - ``` - toArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) = [1,"1";2,"2";3,"3"] +(** `fromArray(kvs, ~id);` + + ```res example + 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"), + ] ``` *) val keysToArray: ('k, 'v, 'id) t -> 'k array -(** `keysToArray s` - ``` - keysToArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) = - [|1;2;3|];; +(** `keysToArray(s);` + + ```res example + 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, + ] ``` *) val valuesToArray: ('k, 'v, 'id) t -> 'v array -(** `valuesToArray s` - ``` - valuesToArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) = - [|"1";"2";"3"|];; - ``` +(** `valuesToArray(s);` + ```res example + 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"] + ``` *) val minKey: ('k, _, _) t -> 'k option -(** `minKey s` - **return** the minimum key, None if not exist -*) +(** `minKey(s)` returns the minimum key, None if not exist. *) val minKeyUndefined: ('k, _, _) t -> 'k Js.undefined -(** **See** [`minKey`]()*) +(** See `Belt.Map.minKey` *) val maxKey: ('k, _, _) t -> 'k option -(** `maxKey s` - **return** the maximum key, None if not exist -*) +(** `maxKey(s)` returns the maximum key, None if not exist. *) val maxKeyUndefined: ('k, _, _) t -> 'k Js.undefined -(** **See** [`maxKey`]() *) +(** See `Belt.Map.maxKey` *) val minimum: ('k, 'v, _) t -> ('k * 'v) option -(** `minimum s` - **return** the minimum key value pair, None if not exist -*) +(** `minimum(s)` returns the minimum key value pair, None if not exist. *) val minUndefined: ('k, 'v, _) t -> ('k * 'v) Js.undefined -(** **See** [`minimum`]() *) +(** See `Belt.Map.minimum` *) val maximum: ('k, 'v, _) t -> ('k * 'v) option -(** `maximum s` - **return** the maximum key value pair, None if not exist -*) +(** `maximum(s)` returns the maximum key value pair, None if not exist. *) val maxUndefined:('k, 'v, _) t -> ('k * 'v) Js.undefined -(** **See** [`maximum`]() -*) +(** See `Belt.Map.maximum` *) val get: ('k, 'v, 'id) t -> 'k -> 'v option -(** `get s k` +(** `get(s, k)` - ``` - get (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) 2 = - Some "2";; - get (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) 2 = - None;; + ```res example + 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) == None ``` *) val getUndefined: ('k, 'v, 'id) t -> 'k -> 'v Js.undefined -(** **See** [`get`]() +(** See `Belt.Map.get` - **return** `undefined` when not found + Returns `undefined` when not found *) val getWithDefault: ('k, 'v, 'id) t -> 'k -> 'v -> 'v -(** `getWithDefault s k default` +(** `getWithDefault(s, k, default)` - **See** [`get`]() - - **return** `default` when `k` is not found + See `Belt.Map.get` + Returns default when `k` is not found. *) val getExn: ('k, 'v, 'id) t -> 'k -> 'v -(** `getExn s k` +(** `getExn(s, k)` - **See** [`getExn`]() + See `Belt.Map.getExn` - **raise** when `k` not exist + raise when `k` not exist *) (****************************************************************************) val remove: ('k, 'v, 'id) t -> 'k -> ('k, 'v, 'id) t -(** `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. - ``` - let s0 = (fromArray `2,"2"; 1,"1"; 3,"3"` ~id:(module IntCmp));; + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) + }) - let s1 = remove s0 1;; - let s2 = remove s1 1;; - s1 == s2 ;; - keysToArray s1 = [|2;3|];; - ``` + let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)) + + let s1 = Belt.Map.remove(s0, 1) + + let s2 = Belt.Map.remove(s1, 1) + + s1 === s2 + Belt.Map.keysToArray(s1) == [2, 3] + ``` *) val removeMany: ('k, 'v, 'id) t -> 'k array -> ('k, 'v, 'id) t -(** `removeMany s xs` +(** `removeMany(s, xs)` - Removing each of `xs` to `s`, note unlike [`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`. *) val set: ('k, 'v, 'id) t -> 'k -> 'v -> ('k, 'v, 'id) t -(** `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. - ``` - let s0 = (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp));; + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = (a, b) => Pervasives.compare(a, b) + }) - let s1 = set s0 2 "3";; + let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)) - valuesToArray s1 = ["1";"3";"3"];; + let s1 = Belt.Map.set(s0, 2, "3") + + Belt.Map.valuesToArray(s1) == ["1", "3", "3"] ``` *) val updateU: ('k, 'v, 'id) t -> 'k -> ('v option -> 'v option [@bs]) -> ('k, 'v, 'id) t val update: ('k, 'v, 'id) t -> 'k -> ('v option -> 'v option) -> ('k, 'v, 'id) t -(** `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 x m)`, 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. *) val mergeMany: ('k, 'v, 'id) t -> ('k * 'v) array -> ('k, 'v, 'id) t -(** `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`. *) val mergeU: @@ -383,10 +411,9 @@ val merge: ('k, 'v2, 'id) t -> ('k -> 'v option -> 'v2 option -> 'v3 option) -> ('k, 'v3, 'id) t -(** `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1` +(** `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`. -*) + value, is determined with the function `f`. *) val keepU: @@ -397,8 +424,8 @@ val keep: ('k, 'v, 'id) t -> ('k -> 'v -> bool) -> ('k, 'v, 'id) t -(** `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`. *) val partitionU: ('k, 'v, 'id) t -> @@ -408,65 +435,57 @@ val partition: ('k, 'v, 'id) t -> ('k -> 'v -> bool) -> ('k, 'v, 'id) t * ('k, 'v, 'id) t -(** `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`. *) val split: ('k, 'v, 'id) t -> 'k -> (('k, 'v, 'id) t * ('k, 'v, 'id) t )* 'v option -(** `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`. *) val mapU: ('k, 'v, 'id) t -> ('v -> 'v2 [@bs]) -> ('k, 'v2, 'id) t val map: ('k, 'v, 'id) t -> ('v -> 'v2) -> ('k, 'v2, 'id) t -(** `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 +(** `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. *) val mapWithKeyU: ('k, 'v, 'id) t -> ('k -> 'v -> 'v2 [@bs]) -> ('k, 'v2, 'id) t val mapWithKey: ('k, 'v, 'id) t -> ('k -> 'v -> 'v2) -> ('k, 'v2, 'id) t -(** `mapWithKey m f` +(** `mapWithKey(m, f)` - The same as [`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. *) val getData: ('k, 'v, 'id) t -> ('k, 'v, 'id) Belt_MapDict.t -(** `getData s0` +(** `getData(s0)` - **Advanced usage only** + Advanced usage only - **return** 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. *) val getId: ('k, 'v, 'id) t -> ('k, 'id) id -(** `getId s0` - - **Advanced usage only** +(** Advanced usage only - **return** the identity of `s0` + Returns the identity of s0. *) val packIdData: id:('k, 'id) id -> data:('k, 'v, 'id) Belt_MapDict.t -> ('k, 'v, 'id) t -(** `packIdData ~id ~data` +(** `packIdData(~id, ~data)` - **Advanced usage only** + Advanced usage only - **return** the packed collection + Returns the packed collection. *) (**/**) diff --git a/jscomp/others/belt_MapDict.mli b/jscomp/others/belt_MapDict.mli index f53a08031e..5eb0bd057f 100644 --- a/jscomp/others/belt_MapDict.mli +++ b/jscomp/others/belt_MapDict.mli @@ -22,6 +22,19 @@ * 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. + + **_Advanced usage only_** +*) + +(* ```res prelude + type t<'key, 'value, 'id> + type cmp<'key, 'id> = Belt_Id.cmp<'key, 'id> + ``` +*) + type ('key, 'value, 'id) t type ('key, 'id) cmp = ('key, 'id) Belt_Id.cmp @@ -60,44 +73,49 @@ val eq: kcmp:('k, 'id) cmp -> 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. *) val findFirstByU : ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) -> ('k * 'v) option val findFirstBy : ('k, 'v, 'id) t -> ('k -> 'v -> bool ) -> ('k * 'v) option -(** `findFirstBy m p` uses funcion `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`. - ``` - let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];; - findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");; + ```res example + module IntCmp = Belt.Id.MakeComparable({ + type t = int + let cmp = Pervasives.compare + }) + + 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")) ``` *) val forEachU: ('k, 'a, 'id) t -> ('k -> 'a -> unit [@bs]) -> unit val forEach: ('k, 'a, 'id) t -> ('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. *) val reduceU: ('k, 'a, 'id) t -> 'b -> ('b -> 'k -> 'a -> 'b [@bs]) -> 'b val reduce: ('k, 'a, 'id) t -> '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. *) val everyU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool val every: ('k, 'a, 'id) t -> ('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 *) val someU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool val some: ('k, 'a, 'id) t -> ('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 *) val size: ('k, 'a, 'id) t -> int @@ -150,16 +168,13 @@ val getExn: 'a val checkInvariantInternal: _ t -> unit -(** - **raise** when invariant is not held -*) val remove: ('a, 'b, 'id) t -> 'a -> cmp:('a, 'id) cmp -> ('a, 'b, 'id) t -(** `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. *) val removeMany: ('a, 'b, 'id) t -> @@ -171,9 +186,9 @@ val set: ('a, 'b, 'id) t -> 'a -> 'b -> cmp:('a, 'id) cmp -> ('a, 'b, 'id) t -(** `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. *) val updateU: ('a, 'b, 'id) t -> @@ -198,10 +213,9 @@ val merge: ('a, 'c, 'id) t -> ('a -> 'b option -> 'c option -> 'd option) -> cmp:('a, 'id) cmp -> ('a, 'd, 'id) t -(** `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1` +(** `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`. -*) + value, is determined with the function `f`. *) val mergeMany: ('a, 'b, 'id) t -> @@ -217,8 +231,8 @@ val keep: ('k, 'a, 'id) t -> ('k -> 'a -> bool) -> ('k, 'a, 'id) t -(** `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`. *) val partitionU: ('k, 'a, 'id) t -> @@ -228,33 +242,27 @@ val partition: ('k, 'a, 'id) t -> ('k -> 'a -> bool) -> ('k, 'a, 'id) t * ('k, 'a, 'id) t -(** `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`. *) val split: ('a, 'b, 'id) t -> 'a -> cmp:('a, 'id) cmp -> (('a,'b,'id) t * ('a, 'b, 'id) t) * 'b option -(** `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`. *) val mapU: ('k, 'a, 'id) t -> ('a -> 'b [@bs]) -> ('k ,'b,'id) t val map: ('k, 'a, 'id) t -> ('a -> 'b) -> ('k ,'b,'id) t -(** `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. *) val mapWithKeyU: ('k, 'a, 'id) t -> ('k -> 'a -> 'b [@bs]) -> ('k, 'b, 'id) t val mapWithKey: ('k, 'a, 'id) t -> ('k -> 'a -> 'b) -> ('k, 'b, 'id) t diff --git a/jscomp/others/belt_MapInt.mli b/jscomp/others/belt_MapInt.mli index e61bc83722..c1cc656f64 100644 --- a/jscomp/others/belt_MapInt.mli +++ b/jscomp/others/belt_MapInt.mli @@ -1,3 +1,12 @@ +(** Specalized when key type is `int`, more efficient than the generic type, + its compare behavior is fixed using the built-in comparison. *) + +(* ```res prelude + type key = int + type t<'value> + ``` +*) + # 4 "others/map.cppo.mli" type key = int # 8 "others/map.cppo.mli" @@ -15,50 +24,43 @@ val cmp: 'v t -> 'v t -> ('v -> 'v -> int) -> int val eqU: 'v t -> 'v t -> ('v -> 'v -> bool [@bs]) -> bool val eq: 'v t -> 'v t -> ('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. *) val findFirstByU : 'v t -> (key -> 'v -> bool [@bs]) -> (key * 'v) option val findFirstBy : 'v t -> (key -> 'v -> bool) -> (key * 'v) option -(** - `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");; - ``` +(** `findFirstBy(m, p)` uses function `f` to find the first key value pair to + match predicate `p`. + + ```res example + let s0 = Belt.Map.Int.fromArray([(4, "4"), (1, "1"), (2, "2"), (3, "3")]) + + Belt.Map.Int.findFirstBy(s0, (k, v) => k == 4) == Some((4, "4")) + ``` *) val forEachU: 'v t -> (key -> 'v -> unit [@bs]) -> unit val forEach: 'v t -> (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. *) val reduceU: 'v t -> 'v2 -> ('v2 -> key -> 'v -> 'v2 [@bs]) -> 'v2 val reduce: 'v t -> '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. *) val everyU: 'v t -> (key -> 'v -> bool [@bs]) -> bool val every: 'v t -> (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 *) val someU: 'v t -> (key -> 'v -> bool [@bs]) -> bool val some: 'v t -> (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 *) val size: 'v t -> int @@ -99,22 +101,18 @@ val getWithDefault: 'v t -> key -> 'v -> 'v val getExn: 'v t -> key -> 'v val checkInvariantInternal: _ t -> unit -(** - **raise** when invariant is not held -*) +(** **raise** when invariant is not held. *) val remove: 'v t -> key -> 'v t -(** `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. *) val removeMany: 'v t -> key array -> 'v t val set: 'v t -> key -> 'v -> 'v t -(** - `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. *) val updateU: 'v t -> key -> ('v option -> 'v option [@bs]) -> 'v t val update: 'v t -> key -> ('v option -> 'v option) -> 'v t @@ -127,11 +125,9 @@ val merge: 'v t -> 'v2 t -> (key -> 'v option -> 'v2 option -> 'c option) -> 'c t -(** - `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`. *) val mergeMany: 'v t -> (key * 'v) array -> 'v t @@ -144,8 +140,6 @@ val keep: 'v t -> (key -> 'v -> bool) -> 'v t -(** `keep m p` returns the map with all the bindings in `m` - that satisfy predicate `p`. *) val partitionU: 'v t -> @@ -155,33 +149,23 @@ val partition: 'v t -> (key -> 'v -> bool) -> 'v t * 'v t -(** - `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`. *) val split: key -> 'v t -> 'v t * 'v option * 'v t -(** - `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`. *) val mapU: 'v t -> ('v -> 'v2 [@bs]) -> 'v2 t val map: 'v t -> ('v -> 'v2) -> 'v2 t -(** - `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. *) val mapWithKeyU: 'v t -> (key -> 'v -> 'v2 [@bs]) -> 'v2 t val mapWithKey: 'v t -> (key -> 'v -> 'v2) -> 'v2 t diff --git a/jscomp/others/belt_MapString.mli b/jscomp/others/belt_MapString.mli index bb81370663..656b50d7ae 100644 --- a/jscomp/others/belt_MapString.mli +++ b/jscomp/others/belt_MapString.mli @@ -1,3 +1,13 @@ +(** Specalized when key type is `string`, more efficient than the generic type, + its compare behavior is fixed using the built-in comparison +*) + +(* ```res prelude + type key = string + type t<'value> + ``` +*) + # 2 "others/map.cppo.mli" type key = string # 8 "others/map.cppo.mli" @@ -15,50 +25,43 @@ val cmp: 'v t -> 'v t -> ('v -> 'v -> int) -> int val eqU: 'v t -> 'v t -> ('v -> 'v -> bool [@bs]) -> bool val eq: 'v t -> 'v t -> ('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. *) val findFirstByU : 'v t -> (key -> 'v -> bool [@bs]) -> (key * 'v) option val findFirstBy : 'v t -> (key -> 'v -> bool) -> (key * 'v) option -(** - `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");; - ``` +(** `findFirstBy(m, p)` uses function `f` to find the first key value pair to + match predicate `p`. + + ```res example + let s0 = Belt.Map.String.fromArray([("4", 4), ("1", 1), ("2", 2), ("3", 3)]) + + Belt.Map.String.findFirstBy(s0, (k, _) => k == "4") == Some(("4", 4)) + ``` *) val forEachU: 'v t -> (key -> 'v -> unit [@bs]) -> unit val forEach: 'v t -> (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. *) val reduceU: 'v t -> 'v2 -> ('v2 -> key -> 'v -> 'v2 [@bs]) -> 'v2 val reduce: 'v t -> '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. *) val everyU: 'v t -> (key -> 'v -> bool [@bs]) -> bool val every: 'v t -> (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 *) val someU: 'v t -> (key -> 'v -> bool [@bs]) -> bool val some: 'v t -> (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 *) val size: 'v t -> int @@ -99,22 +102,18 @@ val getWithDefault: 'v t -> key -> 'v -> 'v val getExn: 'v t -> key -> 'v val checkInvariantInternal: _ t -> unit -(** - **raise** when invariant is not held -*) +(** **raise** when invariant is not held *) val remove: 'v t -> key -> 'v t -(** `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. *) val removeMany: 'v t -> key array -> 'v t val set: 'v t -> key -> 'v -> 'v t -(** - `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. *) val updateU: 'v t -> key -> ('v option -> 'v option [@bs]) -> 'v t val update: 'v t -> key -> ('v option -> 'v option) -> 'v t @@ -127,11 +126,9 @@ val merge: 'v t -> 'v2 t -> (key -> 'v option -> 'v2 option -> 'c option) -> 'c t -(** - `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`. *) val mergeMany: 'v t -> (key * 'v) array -> 'v t @@ -144,8 +141,8 @@ val keep: 'v t -> (key -> 'v -> bool) -> 'v t -(** `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`. *) val partitionU: 'v t -> @@ -155,33 +152,23 @@ val partition: 'v t -> (key -> 'v -> bool) -> 'v t * 'v t -(** - `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`. *) val split: key -> 'v t -> 'v t * 'v option * 'v t -(** - `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`. *) val mapU: 'v t -> ('v -> 'v2 [@bs]) -> 'v2 t val map: 'v t -> ('v -> 'v2) -> 'v2 t -(** - `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. *) val mapWithKeyU: 'v t -> (key -> 'v -> 'v2 [@bs]) -> 'v2 t val mapWithKey: 'v t -> (key -> 'v -> 'v2) -> 'v2 t diff --git a/jscomp/others/belt_MutableMap.mli b/jscomp/others/belt_MutableMap.mli index c2d7960398..99f39f208a 100644 --- a/jscomp/others/belt_MutableMap.mli +++ b/jscomp/others/belt_MutableMap.mli @@ -27,9 +27,15 @@ 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> + ``` *) type ('k,'v,'id) t @@ -50,52 +56,46 @@ val cmp: ('k, 'a, 'id) t -> ('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. *) val eqU: ('k, 'a, 'id) t -> ('k, 'a, 'id) t -> ('a -> 'a -> bool [@bs]) -> bool val eq: ('k, 'a, 'id) t -> ('k, 'a, 'id) t -> ('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. *) val forEachU: ('k, 'a, 'id) t -> ('k -> 'a -> unit [@bs]) -> unit val forEach: ('k, 'a, 'id) t -> ('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. *) val reduceU: ('k, 'a, 'id) t -> 'b -> ('b -> 'k -> 'a -> 'b [@bs]) -> 'b val reduce: ('k, 'a, 'id) t -> '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. *) val everyU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool val every: ('k, 'a, 'id) t -> ('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`. *) val someU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool val some: ('k, 'a, 'id) t -> ('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`. *) val size: ('k, 'a, 'id) t -> int val toList: ('k, 'a, 'id) t -> ('k * 'a) list -(** In increasing order*) +(** In increasing order. *) val toArray: ('k, 'a, 'id) t -> ('k * 'a) array -(** In increasing order*) val fromArray: ('k * 'a) array -> id:('k,'id) id -> ('k,'a,'id) t val keysToArray: ('k, _, _) t -> 'k array @@ -114,9 +114,7 @@ val getWithDefault: ('k, 'a, 'id) t -> 'k -> 'a -> 'a val getExn: ('k, 'a, 'id) t -> 'k -> 'a val checkInvariantInternal: _ t -> unit -(** - **raise** when invariant is not held -*) +(** Raise when invariant is not held. *) (****************************************************************************) @@ -124,13 +122,12 @@ val checkInvariantInternal: _ t -> unit (*TODO: add functional `merge, partition, keep, split`*) val remove: ('k, 'a, 'id) t -> 'k -> unit -(** `remove m x` do the in-place modification, -*) +(** `remove(m, x)` do the in-place modification. *) val removeMany: ('k, 'a, 'id) t -> 'k array -> unit val set: ('k, 'a, 'id) t -> 'k -> 'a -> unit -(** `set m x y ` do the in-place modification *) +(** `set(m, x, y)` do the in-place modification *) val updateU: ('k, 'a, 'id) t -> 'k -> ('a option -> 'a option [@bs]) -> unit val update: ('k, 'a, 'id) t -> 'k -> ('a option -> 'a option) -> unit @@ -139,14 +136,10 @@ val mergeMany: ('k, 'a, 'id) t -> ('k * 'a) array -> unit val mapU: ('k, 'a, 'id) t -> ('a -> 'b [@bs]) -> ('k ,'b,'id ) t val map: ('k, 'a, 'id) t -> ('a -> 'b) -> ('k ,'b,'id ) t -(** `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. *) val mapWithKeyU: ('k, 'a, 'id) t -> ('k -> 'a -> 'b [@bs]) -> ('k, 'b, 'id) t val mapWithKey: ('k, 'a, 'id) t -> ('k -> 'a -> 'b) -> ('k, 'b, 'id) t - - - diff --git a/jscomp/others/belt_MutableMapInt.mli b/jscomp/others/belt_MutableMapInt.mli index 432f036946..dbb4128edf 100644 --- a/jscomp/others/belt_MutableMapInt.mli +++ b/jscomp/others/belt_MutableMapInt.mli @@ -23,6 +23,12 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) +(* ```res prelude + type key = int + type t<'a> + ``` +*) + # 28 "others/mapm.cppo.mli" type key = int # 32 "others/mapm.cppo.mli" @@ -37,41 +43,34 @@ val has: 'a t -> key -> bool val cmpU: 'a t -> 'a t -> ('a -> 'a -> int [@bs]) -> int val cmp: 'a t -> 'a t -> ('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. *) val eqU: 'a t -> 'a t -> ('a -> 'a -> bool [@bs]) -> bool val eq: 'a t -> 'a t -> ('a -> 'a -> bool ) -> bool -(** `eq m1 m2 cmp` *) +(** `eq(m1, m2, cmp)` *) val forEachU: 'a t -> (key -> 'a -> unit [@bs]) -> unit val forEach: 'a t -> (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. *) val reduceU: 'a t -> 'b -> ('b -> key -> 'a -> 'b [@bs]) -> 'b val reduce: 'a t -> '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. *) val everyU: 'a t -> (key -> 'a -> bool [@bs]) -> bool val every: 'a t -> (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. *) val someU: 'a t -> (key -> 'a -> bool [@bs]) -> bool val some: 'a t -> (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. *) @@ -81,7 +80,6 @@ val toList: 'a t -> (key * 'a) list (** In increasing order *) val toArray: 'a t -> (key * 'a) array -(** In increasing order *) val fromArray: (key * 'a) array -> 'a t val keysToArray: 'a t -> key array @@ -99,9 +97,7 @@ val getUndefined: 'a t -> key -> 'a Js.undefined val getWithDefault: 'a t -> key -> 'a -> 'a val getExn: 'a t -> key -> 'a val checkInvariantInternal: _ t -> unit -(** - **raise** when invariant is not held -*) +(** Raise when invariant is not held. *) @@ -110,14 +106,13 @@ val checkInvariantInternal: _ t -> unit (*TODO: add functional `merge, partition, keep, split`*) val remove: 'a t -> key -> unit -(** `remove m x` do the in-place modification *) +(** `remove(m, x)` do the in-place modification. *) val removeMany: 'a t -> key array -> unit val set: 'a t -> key -> 'a -> 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. *) val updateU: 'a t -> key -> ('a option -> 'a option [@bs]) -> unit val update: 'a t -> key -> ('a option -> 'a option) -> unit @@ -125,11 +120,10 @@ val update: 'a t -> key -> ('a option -> 'a option) -> unit val mapU: 'a t -> ('a -> 'b [@bs]) -> 'b t val map: 'a t -> ('a -> 'b) -> 'b t -(** `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. *) val mapWithKeyU: 'a t -> (key -> 'a -> 'b [@bs]) -> 'b t val mapWithKey: 'a t -> (key -> 'a -> 'b) -> 'b t diff --git a/jscomp/others/belt_MutableMapString.mli b/jscomp/others/belt_MutableMapString.mli index 3223a496ac..a93530bb77 100644 --- a/jscomp/others/belt_MutableMapString.mli +++ b/jscomp/others/belt_MutableMapString.mli @@ -23,8 +23,15 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) +(* ```res prelude + type key = string + type t<'a> + ``` +*) + # 26 "others/mapm.cppo.mli" type key = string + # 32 "others/mapm.cppo.mli" type 'a t @@ -37,41 +44,34 @@ val has: 'a t -> key -> bool val cmpU: 'a t -> 'a t -> ('a -> 'a -> int [@bs]) -> int val cmp: 'a t -> 'a t -> ('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. *) val eqU: 'a t -> 'a t -> ('a -> 'a -> bool [@bs]) -> bool val eq: 'a t -> 'a t -> ('a -> 'a -> bool ) -> bool -(** `eq m1 m2 cmp` *) +(** `eq(m1, m2, cmp)` *) val forEachU: 'a t -> (key -> 'a -> unit [@bs]) -> unit val forEach: 'a t -> (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. *) val reduceU: 'a t -> 'b -> ('b -> key -> 'a -> 'b [@bs]) -> 'b val reduce: 'a t -> '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. *) val everyU: 'a t -> (key -> 'a -> bool [@bs]) -> bool val every: 'a t -> (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. *) val someU: 'a t -> (key -> 'a -> bool [@bs]) -> bool val some: 'a t -> (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. *) @@ -81,7 +81,6 @@ val toList: 'a t -> (key * 'a) list (** In increasing order *) val toArray: 'a t -> (key * 'a) array -(** In increasing order *) val fromArray: (key * 'a) array -> 'a t val keysToArray: 'a t -> key array @@ -99,9 +98,7 @@ val getUndefined: 'a t -> key -> 'a Js.undefined val getWithDefault: 'a t -> key -> 'a -> 'a val getExn: 'a t -> key -> 'a val checkInvariantInternal: _ t -> unit -(** - **raise** when invariant is not held -*) +(** Raise when invariant is not held. *) @@ -110,14 +107,13 @@ val checkInvariantInternal: _ t -> unit (*TODO: add functional `merge, partition, keep, split`*) val remove: 'a t -> key -> unit -(** `remove m x` do the in-place modification *) +(** `remove(m, x)` do the in-place modification. *) val removeMany: 'a t -> key array -> unit val set: 'a t -> key -> 'a -> 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. *) val updateU: 'a t -> key -> ('a option -> 'a option [@bs]) -> unit val update: 'a t -> key -> ('a option -> 'a option) -> unit @@ -125,11 +121,10 @@ val update: 'a t -> key -> ('a option -> 'a option) -> unit val mapU: 'a t -> ('a -> 'b [@bs]) -> 'b t val map: 'a t -> ('a -> 'b) -> 'b t -(** `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. *) val mapWithKeyU: 'a t -> (key -> 'a -> 'b [@bs]) -> 'b t val mapWithKey: 'a t -> (key -> 'a -> 'b) -> 'b t