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