API / Belt / Belt_Map

Belt_Map

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`.

undefined

module Int = Belt_MapInt

undefined

module String = Belt_MapString

undefined

module Dict = Belt_MapDict

t

'key is the field type


`'value` is the element type

`'identity` the identity of the collection

type t<'key, 'value, 'identity>

id

The identity needed for making an empty map.

type id<'key, 'id> = Belt_Id.comparable<'key, 'id>

make

make(~id) creates a new map by taking in the comparator.


```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))

Belt.Map.set(m, 0, "a")
```

let make: (~id: id<'k, 'id>) => t<'k, 'v, 'id>

isEmpty

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
```

let isEmpty: t<'a, 'b, 'c> => bool

has

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
```

let has: (t<'k, 'v, 'id>, 'k) => bool

cmpU

let cmpU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, (. 'v, 'v) => int) => int

cmp

cmp(m0, m1, vcmp);


Total ordering of map given total ordering of value function.

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

eqU

let eqU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, (. 'v, 'v) => bool) => bool

eq

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

findFirstByU

let findFirstByU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => option<('k, 'v)>

findFirstBy

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)
})

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)>

forEachU

let forEachU: (t<'k, 'v, 'id>, (. 'k, 'v) => unit) => unit

forEach

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.


```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, "")])

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")}
```

let forEach: (t<'k, 'v, 'id>, ('k, 'v) => unit) => unit

reduceU

let reduceU: (t<'k, 'v, 'id>, 'acc, (. 'acc, 'k, 'v) => 'acc) => 'acc

reduce

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] */
```

let reduce: (t<'k, 'v, 'id>, 'acc, ('acc, 'k, 'v) => 'acc) => 'acc

everyU

let everyU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => bool

every

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

someU

let someU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => bool

some

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

size(s)


```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
```

let size: t<'k, 'v, 'id> => int

toArray

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"),
  ]
```

let toArray: t<'k, 'v, 'id> => array<('k, 'v)>

toList

In increasing order.


See `Belt.Map.toArray`

let toList: t<'k, 'v, 'id> => list<('k, 'v)>

fromArray

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"),
  ]
```

let fromArray: (array<('k, 'v)>, ~id: id<'k, 'id>) => t<'k, 'v, 'id>

keysToArray

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,
  ]
```

let keysToArray: t<'k, 'v, 'id> => array<'k>

valuesToArray

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"]
```

let valuesToArray: t<'k, 'v, 'id> => array<'v>

minKey

minKey(s) returns the minimum key, None if not exist.

let minKey: t<'k, 'a, 'b> => option<'k>

minKeyUndefined

See Belt.Map.minKey

let minKeyUndefined: t<'k, 'a, 'b> => Js.undefined<'k>

maxKey

maxKey(s) returns the maximum key, None if not exist.

let maxKey: t<'k, 'a, 'b> => option<'k>

maxKeyUndefined

See Belt.Map.maxKey

let maxKeyUndefined: t<'k, 'a, 'b> => Js.undefined<'k>

minimum

minimum(s) returns the minimum key value pair, None if not exist.

let minimum: t<'k, 'v, 'a> => option<('k, 'v)>

minUndefined

See Belt.Map.minimum

let minUndefined: t<'k, 'v, 'a> => Js.undefined<('k, 'v)>

maximum

maximum(s) returns the maximum key value pair, None if not exist.

let maximum: t<'k, 'v, 'a> => option<('k, 'v)>

maxUndefined

See Belt.Map.maximum

let maxUndefined: t<'k, 'v, 'a> => Js.undefined<('k, 'v)>

get

get(s, k)


```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
```

let get: (t<'k, 'v, 'id>, 'k) => option<'v>

getUndefined

See Belt.Map.get


Returns `undefined` when not found

let getUndefined: (t<'k, 'v, 'id>, 'k) => Js.undefined<'v>

getWithDefault

getWithDefault(s, k, default)


See `Belt.Map.get`

Returns default when `k` is not found.

let getWithDefault: (t<'k, 'v, 'id>, 'k, 'v) => 'v

getExn

getExn(s, k)


See `Belt.Map.getExn`

raise when `k` not exist

let getExn: (t<'k, 'v, 'id>, 'k) => 'v

remove

remove(m, x) when x is not in m, m is returned reference unchanged.


```res example
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 s1 = Belt.Map.remove(s0, 1)

let s2 = Belt.Map.remove(s1, 1)

s1 === s2

Belt.Map.keysToArray(s1) == [2, 3]
```

let remove: (t<'k, 'v, 'id>, 'k) => t<'k, 'v, 'id>

removeMany

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`.

let removeMany: (t<'k, 'v, 'id>, array<'k>) => t<'k, 'v, 'id>

set

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)
})

let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))

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>

updateU

let updateU: (t<'k, 'v, 'id>, 'k, (. option<'v>) => option<'v>) => t<'k, 'v, 'id>

update

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

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`.

let mergeMany: (t<'k, 'v, 'id>, array<('k, 'v)>) => t<'k, 'v, 'id>

mergeU

let mergeU: (
  t<'k, 'v, 'id>,
  t<'k, 'v2, 'id>,
  (. 'k, option<'v>, option<'v2>) => option<'v3>,
) => t<'k, 'v3, 'id>

merge

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>,
  ('k, option<'v>, option<'v2>) => option<'v3>,
) => t<'k, 'v3, 'id>

keepU

let keepU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => t<'k, 'v, 'id>

keep

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>

partitionU

let partitionU: (t<'k, 'v, 'id>, (. 'k, 'v) => bool) => (t<'k, 'v, 'id>, t<'k, 'v, 'id>)

partition

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

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>)

mapU

let mapU: (t<'k, 'v, 'id>, (. 'v) => 'v2) => t<'k, 'v2, 'id>

map

map(m, f) returns a map with same domain asm, where the associated valueaof all bindings ofmhas been replaced by the result of the application offtoa. The bindings are passed tof` 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>

mapWithKeyU

let mapWithKeyU: (t<'k, 'v, 'id>, (. 'k, 'v) => 'v2) => t<'k, 'v2, 'id>

mapWithKey

mapWithKey(m, f)


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

getData(s0)


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.

let getData: t<'k, 'v, 'id> => Belt_MapDict.t<'k, 'v, 'id>

getId

Advanced usage only


Returns the identity of s0.

let getId: t<'k, 'v, 'id> => id<'k, 'id>

packIdData

packIdData(~id, ~data)


Advanced usage only

Returns the packed collection.

let packIdData: (~id: id<'k, 'id>, ~data: Belt_MapDict.t<'k, 'v, 'id>) => t<'k, 'v, 'id>

checkInvariantInternal

raise when invariant is not held

let checkInvariantInternal: t<'a, 'b, 'c> => unit