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.

type t('key, 'value, 'identity);

'key is the field type

'value is the element type

'identity the identity of the collection

type id('key, 'id) = Belt_Id.comparable('key, 'id);

The identity needed for making an empty map.

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

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

RE
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 isEmpty: t('a, 'b, 'c) => bool;

isEmpty(m) checks whether a map m is empty.

RE
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 has: (t('k, 'v, 'id), 'k) => bool;

has(m, k) checks whether m has the key k.

RE
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 cmpU: (t('k, 'v, 'id), t('k, 'v, 'id), [@bs] (('v, 'v) => int)) => int;

let cmp: (t('k, 'v, 'id), t('k, 'v, 'id), ('v, 'v) => int) => int;

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 eqU: (t('k, 'v, 'id), t('k, 'v, 'id), [@bs] (('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.

let eq: (t('k, 'v, 'id), t('k, 'v, 'id), ('v, 'v) => bool) => bool;

let findFirstByU: (t('k, 'v, 'id), [@bs] (('k, 'v) => bool)) => option(('k, 'v));

let findFirstBy: (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.

RE
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 forEachU: (t('k, 'v, 'id), [@bs] (('k, 'v) => unit)) => unit;

let forEach: (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.

RE
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([]);

Belt.Map.forEach(s0, (k, v) => acc := [(k, v), ...acc^]);

acc^ == [(4, "4"), (3, "3"), (2, "2"), (1, "1")];

let reduceU: (t('k, 'v, 'id), 'acc, [@bs] (('acc, 'k, 'v) => 'acc)) => 'acc;

let reduce: (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.

RE
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, [], (acc, k, v) => [(k, v), ...acc]); /* [(4, "4"), (3, "3"), (2, "2"), (1, "1"), 0] */

let everyU: (t('k, 'v, 'id), [@bs] (('k, 'v) => bool)) => bool;

let every: (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

let someU: (t('k, 'v, 'id), [@bs] (('k, 'v) => bool)) => bool;

let some: (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

let size: t('k, 'v, 'id) => int;

size(s)

RE
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 toArray: t('k, 'v, 'id) => array(('k, 'v));

toArray(s)

RE
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 toList: t('k, 'v, 'id) => list(('k, 'v));

In increasing order.

See Belt.Map.toArray

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

fromArray(kvs, ~id);

RE
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 keysToArray: t('k, 'v, 'id) => array('k);

keysToArray(s);

RE
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 valuesToArray: t('k, 'v, 'id) => array('v);

valuesToArray(s);

RE
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 minKey: t('k, 'a, 'b) => option('k);

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

let minKeyUndefined: t('k, 'a, 'b) => Js.undefined('k);

See Belt.Map.minKey

let maxKey: t('k, 'a, 'b) => option('k);

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

let maxKeyUndefined: t('k, 'a, 'b) => Js.undefined('k);

See Belt.Map.maxKey

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

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

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

See Belt.Map.minimum

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

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

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

See Belt.Map.maximum

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

get(s, k)

RE
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 getUndefined: (t('k, 'v, 'id), 'k) => Js.undefined('v);

See Belt.Map.get

Returns undefined when not found

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

getWithDefault(s, k, default)

See Belt.Map.get

Returns default when k is not found.

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

getExn(s, k)

See Belt.Map.getExn

raise when k not exist

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

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

RE
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 removeMany: (t('k, 'v, 'id), array('k)) => t('k, 'v, 'id);

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 set: (t('k, 'v, 'id), 'k, 'v) => 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.

RE
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 updateU: (t('k, 'v, 'id), 'k, [@bs] (option('v) => option('v))) => t('k, 'v, 'id);

let update: (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(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.

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

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 mergeU:
(t('k, 'v, 'id), t('k, 'v2, 'id), [@bs] (('k, option('v), option('v2)) => option('v3))) =>
t('k, 'v3, 'id);

let merge:
(t('k, 'v, 'id), 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.

let keepU: (t('k, 'v, 'id), [@bs] (('k, 'v) => bool)) => t('k, 'v, 'id);

let keep: (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.

let partitionU: (t('k, 'v, 'id), [@bs] (('k, 'v) => bool)) => (t('k, 'v, 'id), t('k, 'v, 'id));

let partition: (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.

let split: (t('k, 'v, 'id), 'k) => ((t('k, 'v, 'id), t('k, 'v, 'id)), option('v));

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 mapU: (t('k, 'v, 'id), [@bs] ('v => 'v2)) => t('k, 'v2, 'id);

let map: (t('k, 'v, 'id), 'v => 'v2) => t('k, 'v2, 'id);

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 mapWithKeyU: (t('k, 'v, 'id), [@bs] (('k, 'v) => 'v2)) => t('k, 'v2, 'id);

let mapWithKey: (t('k, 'v, 'id), ('k, 'v) => 'v2) => t('k, 'v2, 'id);

mapWithKey(m, f)

The same as Belt.Map.map except that f is supplied with one more argument: the key.

let getData: t('k, 'v, 'id) => Belt_MapDict.t('k, 'v, 'id);

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 getId: t('k, 'v, 'id) => id('k, 'id);

Advanced usage only

Returns the identity of s0.

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

packIdData(~id, ~data)

Advanced usage only

Returns the packed collection.