Module Base.Map

type ('key, +'value, 'cmp) t
type ('k, 'cmp) comparator = (module Comparator.S with type comparator_witness = 'cmp and type t = 'k)
val invariants : (___t ‑> bool

Test if invariants of internal AVL search tree hold.

val comparator : ('a_'cmpt ‑> ('a'cmpComparator.t
val empty : ('a'cmpcomparator ‑> ('a'b'cmpt

the empty map

val singleton : ('a'cmpcomparator ‑> 'a ‑> 'b ‑> ('a'b'cmpt

map with one key, data pair

val of_alist : ('a'cmpcomparator ‑> ('a * 'b) list ‑> [ `Ok of ('a'b'cmpt | `Duplicate_key of 'a ]

creates map from association list with unique keys

val of_alist_or_error : ('a'cmpcomparator ‑> ('a * 'b) list ‑> ('a'b'cmpt Or_error.t

creates map from association list with unique keys. Returns an error if duplicate 'a keys are found.

val of_alist_exn : ('a'cmpcomparator ‑> ('a * 'b) list ‑> ('a'b'cmpt

creates map from association list with unique keys. Raises an exception if duplicate 'a keys are found.

val of_alist_multi : ('a'cmpcomparator ‑> ('a * 'b) list ‑> ('a'b list, 'cmpt

creates map from association list with possibly repeated keys.

val of_alist_fold : ('a'cmpcomparator ‑> ('a * 'b) list ‑> init:'c ‑> f:('c ‑> 'b ‑> 'c) ‑> ('a'c'cmpt

combines an association list into a map, folding together bound values with common keys

val of_alist_reduce : ('a'cmpcomparator ‑> ('a * 'b) list ‑> f:('b ‑> 'b ‑> 'b) ‑> ('a'b'cmpt

combines an association list into a map, reducing together bound values with common keys

val of_iteri : ('a'cmpcomparator ‑> iteri:(f:(key:'a ‑> data:'b ‑> unit) ‑> unit) ‑> [ `Ok of ('a'b'cmpt | `Duplicate_key of 'a ]

of_iteri ~iteri behaves like of_alist, except that instead of taking a concrete datastruture, it takes an iteration function. For instance, to convert a string table into a map: of_iteri (module String) ~f:(Hashtbl.iteri table). It is faster than adding the elements one by one.

val of_sorted_array : ('a'cmpcomparator ‑> ('a * 'b) array ‑> ('a'b'cmpt Or_error.t

creates map from sorted array of key-data pairs. The input array must be sorted, as given by the relevant comparator (either in ascending or descending order), and must not contain any duplicate keys. If either of these conditions do not hold, an error is returned.

val of_sorted_array_unchecked : ('a'cmpcomparator ‑> ('a * 'b) array ‑> ('a'b'cmpt

Like of_sorted_array except it returns a map with broken invariants when an Error would have been returned.

val of_increasing_iterator_unchecked : ('a'cmpcomparator ‑> len:int ‑> f:(int ‑> 'a * 'b) ‑> ('a'b'cmpt

if_increasing_iterator_unchecked c ~len ~f behaves like of_sorted_array_unchecked c (Array.init len ~f), with the additional restriction that a decreasing order is not supported. The advantage is not requiring you to allocate an intermediate array. f will be called with 0, 1, ... len - 1, in order.

val is_empty : (___t ‑> bool

Test whether a map is empty or not.

val length : (___t ‑> int

length map

val add : ('k'v'cmpt ‑> key:'k ‑> data:'v ‑> ('k'v'cmpt

returns a new map with the specified new binding; if the key was already bound, its previous binding disappears.

val add_multi : ('k'v list, 'cmpt ‑> key:'k ‑> data:'v ‑> ('k'v list, 'cmpt

if key is not present then add a singleton list, otherwise, cons data on the head of the existing list.

val remove_multi : ('k'v list, 'cmpt ‑> 'k ‑> ('k'v list, 'cmpt

if key is present then remove its head element; if result is empty, remove the key.

val change : ('k'v'cmpt ‑> 'k ‑> f:('v option ‑> 'v option) ‑> ('k'v'cmpt

change t key ~f returns a new map m that is the same as t on all keys except for key, and whose value for key is defined by f, i.e. find m key = f (find t key).

val update : ('k'v'cmpt ‑> 'k ‑> f:('v option ‑> 'v) ‑> ('k'v'cmpt

update t key ~f is change t key ~f:(fun o -> Some (f o)).

val find : ('k'v'cmpt ‑> 'k ‑> 'v option

returns the value bound to the given key, raising Not_found if none such exists

val find_exn : ('k'v'cmpt ‑> 'k ‑> 'v
val remove : ('k'v'cmpt ‑> 'k ‑> ('k'v'cmpt

returns a new map with any binding for the key in question removed

val mem : ('k_'cmpt ‑> 'k ‑> bool

mem map key tests whether map contains a binding for key

val iter_keys : ('k__t ‑> f:('k ‑> unit) ‑> unit
val iter : (_'v_t ‑> f:('v ‑> unit) ‑> unit
val iteri : ('k'v_t ‑> f:(key:'k ‑> data:'v ‑> unit) ‑> unit
val iter2 : ('k'v1'cmpt ‑> ('k'v2'cmpt ‑> f:(key:'k ‑> data:[ `Left of 'v1 | `Right of 'v2 | `Both of 'v1 * 'v2 ] ‑> unit) ‑> unit

Iterate two maps side by side. Complexity of this function is O(M+N). If two inputs are (0, a); (1, a) and (1, b); (2, b), f will be called with (0, `Left a); (1, `Both (a, b)); (2, `Right b)

val map : ('k'v1'cmpt ‑> f:('v1 ‑> 'v2) ‑> ('k'v2'cmpt

returns new map with bound values replaced by f applied to the bound values

val mapi : ('k'v1'cmpt ‑> f:(key:'k ‑> data:'v1 ‑> 'v2) ‑> ('k'v2'cmpt

like map, but function takes both key and data as arguments

val fold : ('k'v_t ‑> init:'a ‑> f:(key:'k ‑> data:'v ‑> 'a ‑> 'a) ‑> 'a

folds over keys and data in map in increasing order of key.

val fold_right : ('k'v_t ‑> init:'a ‑> f:(key:'k ‑> data:'v ‑> 'a ‑> 'a) ‑> 'a

folds over keys and data in map in decreasing order of key.

val fold2 : ('k'v1'cmpt ‑> ('k'v2'cmpt ‑> init:'a ‑> f:(key:'k ‑> data:[ `Left of 'v1 | `Right of 'v2 | `Both of 'v1 * 'v2 ] ‑> 'a ‑> 'a) ‑> 'a

folds over two maps side by side, like iter2.

val filter_keys : ('k'v'cmpt ‑> f:('k ‑> bool) ‑> ('k'v'cmpt

filter, filteri, filter_keys, filter_map, and filter_mapi run in O(n * lg n) time; they simply accumulate each key & data retained by f into a new map using add.

val filter : ('k'v'cmpt ‑> f:('v ‑> bool) ‑> ('k'v'cmpt
val filteri : ('k'v'cmpt ‑> f:(key:'k ‑> data:'v ‑> bool) ‑> ('k'v'cmpt
val filter_map : ('k'v1'cmpt ‑> f:('v1 ‑> 'v2 option) ‑> ('k'v2'cmpt

returns new map with bound values filtered by f applied to the bound values

val filter_mapi : ('k'v1'cmpt ‑> f:(key:'k ‑> data:'v1 ‑> 'v2 option) ‑> ('k'v2'cmpt

like filter_map, but function takes both key and data as arguments

val partition_mapi : ('k'v1'cmpt ‑> f:(key:'k ‑> data:'v1 ‑> [ `Fst of 'v2 | `Snd of 'v3 ]) ‑> ('k'v2'cmpt * ('k'v3'cmpt

partition_mapi t ~f returns two new ts, with each key in t appearing in exactly one of the result maps depending on its mapping in f.

val partition_map : ('k'v1'cmpt ‑> f:('v1 ‑> [ `Fst of 'v2 | `Snd of 'v3 ]) ‑> ('k'v2'cmpt * ('k'v3'cmpt

partition_map t ~f = partition_mapi t ~f:(fun ~key:_ ~data -> f data)

val partitioni_tf : ('k'v'cmpt ‑> f:(key:'k ‑> data:'v ‑> bool) ‑> ('k'v'cmpt * ('k'v'cmpt

     partitioni_tf t ~f
     =
     partition_mapi t ~f:(fun ~key ~data ->
       if f ~key ~data
       then `Fst data
       else `Snd data)
   
val partition_tf : ('k'v'cmpt ‑> f:('v ‑> bool) ‑> ('k'v'cmpt * ('k'v'cmpt

partition_tf t ~f = partitioni_tf t ~f:(fun ~key:_ ~data -> f data)

val compare_direct : ('v ‑> 'v ‑> int) ‑> ('k'v'cmpt ‑> ('k'v'cmpt ‑> int

Total ordering between maps. The first argument is a total ordering used to compare data associated with equal keys in the two maps.

val hash_fold_direct : 'k Hash.folder ‑> 'v Hash.folder ‑> ('k'v'cmpt Hash.folder

Hash function: a building block to use when hashing data structures containing maps in them. hash_fold_direct hash_fold_key is compatible with compare_direct iff hash_fold_key is compatible with (comparator m).compare of the map m being hashed.

val equal : ('v ‑> 'v ‑> bool) ‑> ('k'v'cmpt ‑> ('k'v'cmpt ‑> bool

equal cmp m1 m2 tests whether the maps m1 and m2 are equal, that is, contain equal keys and associate them with equal data. cmp is the equality predicate used to compare the data associated with the keys.

val keys : ('k__t ‑> 'k list

returns list of keys in map

val data : (_'v_t ‑> 'v list

returns list of data in map

val to_alist : ?key_order:[ `Increasing | `Decreasing ] ‑> ('k'v_t ‑> ('k * 'v) list

creates association list from map.

val validate : name:('k ‑> string) ‑> 'v Validate.check ‑> ('k'v_t Validate.check
Additional operations on maps
val merge : ('k'v1'cmpt ‑> ('k'v2'cmpt ‑> f:(key:'k ‑> [ `Left of 'v1 | `Right of 'v2 | `Both of 'v1 * 'v2 ] ‑> 'v3 option) ‑> ('k'v3'cmpt

merges two maps

module Symmetric_diff_element : sig ... end
val symmetric_diff : ('k'v'cmpt ‑> ('k'v'cmpt ‑> data_equal:('v ‑> 'v ‑> bool) ‑> ('k'vSymmetric_diff_element.t Sequence.t

symmetric_diff t1 t2 ~data_equal returns a list of changes between t1 and t2. It is intended to be efficient in the case where t1 and t2 share a large amount of structure. The keys in the output sequence will be in sorted order.

val min_elt : ('k'v_t ‑> ('k * 'v) option

min_elt map

val min_elt_exn : ('k'v_t ‑> 'k * 'v
val max_elt : ('k'v_t ‑> ('k * 'v) option

max_elt map

val max_elt_exn : ('k'v_t ‑> 'k * 'v
val for_all : ('k'v_t ‑> f:('v ‑> bool) ‑> bool

same semantics as similar functions in List

val for_alli : ('k'v_t ‑> f:(key:'k ‑> data:'v ‑> bool) ‑> bool
val exists : ('k'v_t ‑> f:('v ‑> bool) ‑> bool
val existsi : ('k'v_t ‑> f:(key:'k ‑> data:'v ‑> bool) ‑> bool
val count : ('k'v_t ‑> f:('v ‑> bool) ‑> int
val counti : ('k'v_t ‑> f:(key:'k ‑> data:'v ‑> bool) ‑> int
val split : ('k'v'cmpt ‑> 'k ‑> ('k'v'cmpt * ('k * 'v) option * ('k'v'cmpt

split t key returns a map of keys strictly less than key, the mapping of key if any, and a map of keys strictly greater than key.

Runtime is O(m + log n) where n is the size of the input map, and m is the size of the smaller of the two output maps. The O(m) term is due to the need to calculate the length of the output maps. *

val append : lower_part:('k'v'cmpt ‑> upper_part:('k'v'cmpt ‑> [ `Ok of ('k'v'cmpt | `Overlapping_key_ranges ]

append ~lower_part ~upper_part returns `Ok map where map contains all the (key, value) pairs from the two input maps if all the keys from lower_part are less than all the keys from upper_part. Otherwise it returns `Overlapping_key_ranges.

Runtime is O(log n) where n is the size of the larger input map. This can be significantly faster than Map.merge or repeated Map.add.


      assert (match Map.append ~lower_part ~upper_part with
        | `Ok whole_map ->
          whole_map
          = Map.(of_alist_exn (List.append (to_alist lower_part) (to_alist upper_part)))
        | `Overlapping_key_ranges -> true);
    
val subrange : ('k'v'cmpt ‑> lower_bound:'k Maybe_bound.t ‑> upper_bound:'k Maybe_bound.t ‑> ('k'v'cmpt

subrange t ~lower_bound ~upper_bound returns a map containing all the entries from t whose keys lie inside the interval indicated by ~lower_bound and ~upper_bound. If this interval is empty, an empty map is returned.

Runtime is O(m + log n) where n is the size of the input map, and m is the size of the output map. The O(m) term is due to the need to calculate the length of the output map.

val fold_range_inclusive : ('k'v'cmpt ‑> min:'k ‑> max:'k ‑> init:'a ‑> f:(key:'k ‑> data:'v ‑> 'a ‑> 'a) ‑> 'a

fold_range_inclusive t ~min ~max ~init ~f folds f (with initial value ~init) over all keys (and their associated values) that are in the range min, max (inclusive).

val range_to_alist : ('k'v'cmpt ‑> min:'k ‑> max:'k ‑> ('k * 'v) list

range_to_alist t ~min ~max returns an associative list of the elements whose keys lie in min, max (inclusive), with the smallest key being at the head of the list.

val closest_key : ('k'v'cmpt ‑> [ `Greater_or_equal_to | `Greater_than | `Less_or_equal_to | `Less_than ] ‑> 'k ‑> ('k * 'v) option

closest_key t dir k returns the (key, value) pair in t with key closest to k, which satisfies the given inequality bound.

For example, closest_key t `Less_than k would be the pair with the closest key to k where key < k.

to_sequence can be used to get the same results as closest_key. It is less efficient for individual lookups but more efficient for finding many elements starting at some value.

val nth : ('k'v_t ‑> int ‑> ('k * 'v) option

nth t n finds the (key, value) pair of rank n (i.e. such that there are exactly n keys strictly less than the found key), if one exists. O(log(length t) + n) time.

val nth_exn : ('k'v_t ‑> int ‑> 'k * 'v
val rank : ('k'v'cmpt ‑> 'k ‑> int option

rank t k if k is in t, returns the number of keys strictly less than k in t, otherwise None

val to_sequence : ?order:[ `Increasing_key | `Decreasing_key ] ‑> ?keys_greater_or_equal_to:'k ‑> ?keys_less_or_equal_to:'k ‑> ('k'v'cmpt ‑> ('k * 'v) Sequence.t

to_sequence ?order ?keys_greater_or_equal_to ?keys_less_or_equal_to t gives a sequence of key-value pairs between keys_less_or_equal_to and keys_greater_or_equal_to inclusive, presented in order. If keys_greater_or_equal_to > keys_less_or_equal_to, the sequence is empty. Cost is O(log n) up front and amortized O(1) to produce each element.

module M : functor (K : sig ... end) -> sig ... end

M is meant to be used in combination with OCaml applicative functor types:

module type Sexp_of_m : sig ... end
module type M_of_sexp : sig ... end
module type Compare_m : sig ... end
module type Hash_fold_m = Hasher.S
val sexp_of_m__t : (module Sexp_of_m with type t = 'k) ‑> ('v ‑> Sexp.t) ‑> ('k'v'cmpt ‑> Sexp.t
val m__t_of_sexp : (module M_of_sexp with type comparator_witness = 'cmp and type t = 'k) ‑> (Sexp.t ‑> 'v) ‑> Sexp.t ‑> ('k'v'cmpt
val compare_m__t : (module Compare_m) ‑> ('v ‑> 'v ‑> int) ‑> ('k'v'cmpt ‑> ('k'v'cmpt ‑> int
val hash_fold_m__t : (module Hash_fold_m with type t = 'k) ‑> (Hash.state ‑> 'v ‑> Hash.state) ‑> Hash.state ‑> ('k'v_t ‑> Hash.state
module Using_comparator : sig ... end

Using comparator is a similar interface as the toplevel of Map, except the functions take a ~comparator:('k, 'cmp) Comparator.t where the functions at the toplevel of Map takes a ('k, 'cmp) comparator.