v11v9.1 - v10.1v8.2 - v9.0v6.0 - v8.1

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

Deprecated

Use cmp instead

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

Deprecated

Use eq instead

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

Deprecated

Use findFirstBy instead

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

s0->Belt.Map.findFirstBy((k, _) => k == 4) == Some(4, "4")

forEachU

Deprecated

Use forEach instead

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

Deprecated

Use reduce instead

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}) ==
  list{(4, "4"), (3, "3"), (2, "2"), (1, "1")}

everyU

Deprecated

Use every instead

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

Deprecated

Use some instead

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)), 4) == 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.get

throw when k not exist

getOrThrow

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

getOrThrow(s, k)

See Belt.Map.get

throw 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

Deprecated

Use update instead

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

Deprecated

Use merge instead

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

Deprecated

Use keep instead

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

Deprecated

Use partition instead

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

Deprecated

Use map instead

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

mapWithKeyU

Deprecated

Use mapWithKey instead

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

throw when invariant is not held