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
type t<'key, 'value, 'identity>
'key
is the field type
'value
is the element type
'identity
the identity of the collection
id
type id<'key, 'id> = Belt_Id.comparable<'key, 'id>
The identity needed for making an empty map.
make
let make: (~id: id<'k, 'id>) => t<'k, 'v, 'id>
make(~id)
creates a new map by taking in the comparator.
Examples
RESCRIPTmodule 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
let isEmpty: t<'a, 'b, 'c> => bool
isEmpty(m)
checks whether a map m is empty.
Examples
RESCRIPTmodule 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
let has: (t<'k, 'v, 'id>, 'k) => bool
has(m, k)
checks whether m
has the key k
.
Examples
RESCRIPTmodule 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
let cmpU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ('v, 'v) => int) => int
cmp
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
let eqU: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ('v, 'v) => bool) => bool
eq
let eq: (t<'k, 'v, 'id>, t<'k, 'v, 'id>, ('v, 'v) => bool) => bool
eq(m1, m2, veq)tests whether the maps
m1and
m2are 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
let findFirstByU: (t<'k, 'v, 'id>, ('k, 'v) => bool) => option<('k, 'v)>
findFirstBy
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
RESCRIPTmodule 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
let forEachU: (t<'k, 'v, 'id>, ('k, 'v) => unit) => unit
forEach
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
RESCRIPTmodule 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
let reduceU: (t<'k, 'v, 'id>, 'acc, ('acc, 'k, 'v) => 'acc) => 'acc
reduce
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
RESCRIPTmodule 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
let everyU: (t<'k, 'v, 'id>, ('k, 'v) => bool) => bool
every
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
let someU: (t<'k, 'v, 'id>, ('k, 'v) => bool) => bool
some
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
let size: t<'k, 'v, 'id> => int
size(s)
Examples
RESCRIPTmodule 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
let toArray: t<'k, 'v, 'id> => array<('k, 'v)>
toArray(s)
Examples
RESCRIPTmodule 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
let toList: t<'k, 'v, 'id> => list<('k, 'v)>
In increasing order. See Belt.Map.toArray
fromArray
let fromArray: (array<('k, 'v)>, ~id: id<'k, 'id>) => t<'k, 'v, 'id>
fromArray(kvs, ~id);
Examples
RESCRIPTmodule 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
let keysToArray: t<'k, 'v, 'id> => array<'k>
keysToArray(s);
Examples
RESCRIPTmodule 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
let valuesToArray: t<'k, 'v, 'id> => array<'v>
valuesToArray(s);
Examples
RESCRIPTmodule 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
let minKey: t<'k, 'a, 'b> => option<'k>
minKey(s)
returns the minimum key, None if not exist.
minKeyUndefined
let minKeyUndefined: t<'k, 'a, 'b> => Js.undefined<'k>
See Belt.Map.minKey
maxKey
let maxKey: t<'k, 'a, 'b> => option<'k>
maxKey(s)
returns the maximum key, None if not exist.
maxKeyUndefined
let maxKeyUndefined: t<'k, 'a, 'b> => Js.undefined<'k>
See Belt.Map.maxKey
minimum
let minimum: t<'k, 'v, 'a> => option<('k, 'v)>
minimum(s)
returns the minimum key value pair, None if not exist.
minUndefined
let minUndefined: t<'k, 'v, 'a> => Js.undefined<('k, 'v)>
See Belt.Map.minimum
maximum
let maximum: t<'k, 'v, 'a> => option<('k, 'v)>
maximum(s)
returns the maximum key value pair, None if not exist.
maxUndefined
let maxUndefined: t<'k, 'v, 'a> => Js.undefined<('k, 'v)>
See Belt.Map.maximum
get
let get: (t<'k, 'v, 'id>, 'k) => option<'v>
get(s, k)
Examples
RESCRIPTmodule 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
let getUndefined: (t<'k, 'v, 'id>, 'k) => Js.undefined<'v>
See Belt.Map.get
. Returns undefined
when not found
getWithDefault
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
let getExn: (t<'k, 'v, 'id>, 'k) => 'v
getExn(s, k)
See Belt.Map.getExn
raise when k
not exist
remove
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
RESCRIPTmodule 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
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
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
RESCRIPTmodule 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
let updateU: (
t<'k, 'v, 'id>,
'k,
option<'v> => option<'v>,
) => t<'k, 'v, 'id>
update
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
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
let mergeU: (
t<'k, 'v, 'id>,
t<'k, 'v2, 'id>,
('k, option<'v>, option<'v2>) => option<'v3>,
) => t<'k, 'v3, 'id>
merge
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
let keepU: (t<'k, 'v, 'id>, ('k, 'v) => bool) => t<'k, 'v, 'id>
keep
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
let partitionU: (
t<'k, 'v, 'id>,
('k, 'v) => bool,
) => (t<'k, 'v, 'id>, t<'k, 'v, 'id>)
partition
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
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
let mapU: (t<'k, 'v, 'id>, 'v => 'v2) => t<'k, 'v2, 'id>
map
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
aof all bindings of
mhas been replaced by the result of the application of
fto
a. The bindings are passed to
f` in increasing order
with respect to the ordering over the type of the keys.
mapWithKeyU
let mapWithKeyU: (t<'k, 'v, 'id>, ('k, 'v) => 'v2) => t<'k, 'v2, 'id>
mapWithKey
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
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
let getId: t<'k, 'v, 'id> => id<'k, 'id>
Advanced usage only. Returns the identity of s0.
packIdData
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
let checkInvariantInternal: t<'a, 'b, 'c> => unit
raise when invariant is not held