Docs / API / Belt / Map

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.

t

RESCRIPT

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

'key is the field type

'value is the element type

'identity the identity of the collection

id

RESCRIPT

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

The identity needed for making an empty map.

make

RESCRIPT

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

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

Examples

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

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

isEmpty

RESCRIPT

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

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

Examples

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

has

RESCRIPT

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

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

Examples

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

cmpU

RESCRIPT

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

cmp

RESCRIPT

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.

eqU

RESCRIPT

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

eq

RESCRIPT

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

eq(m1, m2, veq)tests whether the mapsm1andm2are 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.

findFirstByU

RESCRIPT

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

findFirstBy

RESCRIPT

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.

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

Belt.Map.findFirstBy(s0, (k, v) => k == 4) /* (4, "4") */

forEachU

RESCRIPT

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

forEach

RESCRIPT

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.

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

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

reduceU

RESCRIPT

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

reduce

RESCRIPT

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.

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

everyU

RESCRIPT

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

every

RESCRIPT

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

someU

RESCRIPT

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

some

RESCRIPT

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

size

RESCRIPT

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

size(s)

Examples

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

toArray

RESCRIPT

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

toArray(s)

Examples

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

toList

RESCRIPT

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

In increasing order. See Belt.Map.toArray

fromArray

RESCRIPT

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

fromArray(kvs, ~id);

Examples

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

keysToArray

RESCRIPT

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

keysToArray(s);

Examples

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

valuesToArray

RESCRIPT

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

valuesToArray(s);

Examples

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

minKey

RESCRIPT

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

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

minKeyUndefined

RESCRIPT

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

See Belt.Map.minKey

maxKey

RESCRIPT

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

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

maxKeyUndefined

RESCRIPT

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

See Belt.Map.maxKey

minimum

RESCRIPT

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

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

minUndefined

RESCRIPT

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

See Belt.Map.minimum

maximum

RESCRIPT

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

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

maxUndefined

RESCRIPT

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

See Belt.Map.maximum

get

RESCRIPT

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

get(s, k)

Examples

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

getUndefined

RESCRIPT

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

See Belt.Map.get. Returns undefined when not found

getWithDefault

RESCRIPT

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

getWithDefault(s, k, default)

See Belt.Map.get

Returns default when k is not found.

getExn

RESCRIPT

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

getExn(s, k)

See Belt.Map.getExn

raise when k not exist

remove

RESCRIPT

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.

Examples

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

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

s1 === s2

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

removeMany

RESCRIPT

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.

set

RESCRIPT

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.

Examples

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 s1 = Belt.Map.set(s0, 2, "3")

Belt.Map.valuesToArray(s1) == ["1", "3", "3"]

updateU

RESCRIPT

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

update

RESCRIPT

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

mergeMany

RESCRIPT

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.

mergeU

RESCRIPT

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

merge

RESCRIPT

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.

keepU

RESCRIPT

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

keep

RESCRIPT

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.

partitionU

RESCRIPT

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

partition

RESCRIPT

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.

split

RESCRIPT

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.

mapU

RESCRIPT

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

map

RESCRIPT

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.

mapWithKeyU

RESCRIPT

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

mapWithKey

RESCRIPT

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.

getData

RESCRIPT

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.

getId

RESCRIPT

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

Advanced usage only. Returns the identity of s0.

packIdData

RESCRIPT

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.

checkInvariantInternal

RESCRIPT

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

raise when invariant is not held