1. Functorized maps
Legend:
Library
Module
Module type
Parameter
Class
Class type

Association tables over ordered types.

This module implements applicative association tables, also known as finite maps or dictionaries, given a total ordering function over the keys. All operations over maps are purely applicative (no side-effects). The implementation uses balanced binary trees, and therefore searching and insertion take time logarithmic in the size of the map.

Note OCaml, Batteries Included, provides two implementations of maps: polymorphic maps and functorized maps. Functorized maps (see `S` and `Make`) are slightly more complex to use but offer stronger type-safety. Polymorphic maps make it easier to shoot yourself in the foot. In case of doubt, you should use functorized maps.

##### Functorized maps

The important part is the `Make` module which builds association maps from a user-provided datatype and comparison function. In the `Make` module (or its output signature `S`) are documentated all functions available on maps.

Here is a typical example of use:

``````module MyKeyType = struct
type t = my_type
let compare = my_compare_function
end
module MyMap = Map.Make(MyKeyType)

let some_map = MyMap.add something MyMap.empty
...``````

To define maps with integer/string keys:

``````module IntMap = Map.Make(Int)
module StringMap = Map.Make(String)``````
`type key`

The type of the map keys.

`type +'a t`

The type of maps from type `key` to type `'a`.

`val empty : 'a t`

The empty map.

`val is_empty : 'a t -> bool`

Test whether a map is empty or not.

`val cardinal : 'a t -> int`

Return the number of bindings of a map.

`val add : key -> 'a -> 'a t -> 'a t`

`add x y m` returns a map containing the same bindings as `m`, plus a binding of `x` to `y`. If `x` was already bound in `m`, its previous binding disappears. If `x` was already bound to some `z` that is physically equal to `y`, then the returned map is physically equal to `m`.

• before 3.3.0

physical equality was not ensured.

`val update_stdlib : key -> ('a option -> 'a option) -> 'a t -> 'a t`

`update_stdlib k f m` returns a map containing the same bindings as `m`, except `k` has a new binding as determined by `f`: First, calculate `y` as `f (find_opt k m)`. If `y = Some v` then `k` will be bound to `v` in the resulting map. Else `k` will not be bound in the resulting map. If `v` is physically equal to the value of the previous binding of `k` in `m`, then the returned map will be physically equal to `m`.

This function does the same thing as `update` in the stdlib, but has a different name for backwards compatibility reasons.

• since 3.3.0
`val update : key -> key -> 'a -> 'a t -> 'a t`

`update k1 k2 v2 m` replace the previous binding of `k1` in `m` by `k2` associated to `v2`. This is equivalent to `add k2 v2 (remove k1) m`, but more efficient in the case where `k1` and `k2` have the same key ordering. If `k1` and `k2` have the same key ordering and `v2` is physically equal to the value `k1` is bound to in `m` then the returned map will be physically equal to `m`

• raises Not_found

if `k1` is not bound in `m`.

• since 2.4.0
• before 3.3.0

physical equality was not ensured.

`val find : key -> 'a t -> 'a`

`find x m` returns the current binding of `x` in `m`, or raises `Not_found` if no such binding exists.

`val find_opt : key -> 'a t -> 'a option`

`find_opt x m` returns Some b where b is the current binding * of `x` in `m`, or None if no such binding exists.

`val find_default : 'a -> key -> 'a t -> 'a`

`find_default d x m` returns the current binding of `x` in `m`, or the default value `d` if no such binding exists.

`val find_first : (key -> bool) -> 'a t -> key * 'a`

`find_first f m` returns the first binding `(k, v)` for which `f k` is true or raises `Not_found` if there is no such binding. `f` must be monotonically increasing, i.e. if `k1 < k2 && f k1` is true then `f k2` must also be true.

• since 3.3.0
`val find_first_opt : (key -> bool) -> 'a t -> (key * 'a) option`

`find_first_opt f m` returns `Some (k, v)` for the first binding `(k, v)` for which `f k` is true or returns `None` if there is no such binding. `f` must be monotonically increasing, i.e. if `k1 < k2 && f k1` is true then `f k2` must also be true.

• since 3.3.0
`val find_last : (key -> bool) -> 'a t -> key * 'a`

`find_last f m` returns the last binding `(k, v)` for which `f k` is true or raises `Not_found` if there is no such binding. `f` must be monotonically decreasing, i.e. if `k1 < k2 && f k2` is true then `f k1` must also be true.

• since 3.3.0
`val find_last_opt : (key -> bool) -> 'a t -> (key * 'a) option`

`find_last_opt f m` returns `Some (k, v)` for the last binding `(k, v)` for which `f k` is true or returns `None` if there is no such binding. `f` must be monotonically decreasing, i.e. if `k1 < k2 && f k2` is true then `f k1` must also be true.

• since 3.3.0
`val remove : key -> 'a t -> 'a t`

`remove x m` returns a map containing the same bindings as `m`, except for `x` which is unbound in the returned map. The returned map is physically equal to the passed one if `x` was already unbound.

• before 3.3.0

physical equality was not ensured

`val remove_exn : key -> 'a t -> 'a t`

`remove_exn x m` behaves like `remove x m` except that it raises an exception if `x` is unbound in `m`.

• raises Not_found

if `x` is unbound in `m`

• since 3.2.0
`val modify : key -> ('a -> 'a) -> 'a t -> 'a t`

`modify k f m` replaces the previous binding for `k` with `f` applied to that value. If `k` is unbound in `m` or `Not_found` is raised during the search, `Not_found` is raised.

• since 1.2.0
• raises Not_found

if `k` is unbound in `m` (or `f` raises `Not_found`)

`val modify_def : 'a -> key -> ('a -> 'a) -> 'a t -> 'a t`

`modify_def v0 k f m` replaces the previous binding for `k` with `f` applied to that value. If `k` is unbound in `m` or `Not_found` is raised during the search, `f v0` is inserted (as if the value found were `v0`).

• since 1.3.0
`val modify_opt : key -> ('a option -> 'a option) -> 'a t -> 'a t`

`modify_opt k f m` allows to modify the binding for `k` in `m` or absence thereof.

• since 2.1
`val extract : key -> 'a t -> 'a * 'a t`

`extract k m` removes the current binding of `k` from `m`, returning the value `k` was bound to and the updated `m`.

• raises Not_found

if `k` is unbound in `m`

• since 1.4.0
`val pop : 'a t -> (key * 'a) * 'a t`

`pop m` returns a binding from `m` and `m` without that binding.

• raises Not_found

if `m` is empty

• since 1.4.0
`val mem : key -> 'a t -> bool`

`mem x m` returns `true` if `m` contains a binding for `x`, and `false` otherwise.

`val iter : (key -> 'a -> unit) -> 'a t -> unit`

`iter f m` applies `f` to all bindings in map `m`. `f` receives the key 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. Only current bindings are presented to `f`: bindings hidden by more recent bindings are not passed to `f`.

`val map : ('a -> 'b) -> 'a t -> 'b t`

`map f m` 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.

`val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t`

Same as `Map.S.map`, but the function receives as arguments both the key and the associated value for each binding of the map.

`val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b`

`fold f m a` computes `(f kN dN ... (f k1 d1 (f k0 d0 a))...)`, where `k0,k1..kN` are the keys of all bindings in `m` (in increasing order), and `d1 ... dN` are the associated data.

`val filterv : ('a -> bool) -> 'a t -> 'a t`

`filterv f m` returns a map where only the values `a` of `m` such that `f a = true` remain. The bindings are passed to `f` in increasing order with respect to the ordering over the type of the keys.

`val filter : (key -> 'a -> bool) -> 'a t -> 'a t`

`filter f m` returns a map where only the `(key, value)` pairs of `m` such that `f key value = true` remain. The bindings are passed to `f` in increasing order with respect to the ordering over the type of the keys. If `f` returns `true` for all bindings of `m` the returned map is physically equal to `m`.

• before 3.3.0

physical equality was not ensured.

`val filter_map : (key -> 'a -> 'b option) -> 'a t -> 'b t`

`filter_map f m` combines the features of `filter` and `map`. It calls calls `f key0 a0`, `f key1 a1`, `f keyn an` where `a0,a1..an` are the elements of `m` and `key0..keyn` the respective corresponding keys. It returns the map of pairs `(keyi, bi)` such as `f keyi ai = Some bi` (when `f` returns `None`, the corresponding element of `m` is discarded).

`val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> 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 equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> 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 : _ t -> key BatEnum.t`

Return an enumeration of all the keys of a map. The returned enumeration is sorted in increasing key order.

`val values : 'a t -> 'a BatEnum.t`

Return an enumeration of all the values of a map. The returned enumeration is sorted in increasing key order.

`val min_binding : 'a t -> key * 'a`

Return the `(key, value)` pair with the smallest key.

• raises Not_found

if the map is empty.

`val min_binding_opt : 'a t -> (key * 'a) option`

Return `Some (key, value)` for the `key, value` pair with the smallest key, or `None` if the map is empty.

• since 3.3.0
`val pop_min_binding : 'a t -> (key * 'a) * 'a t`

Return the `(key, value)` pair with the smallest key along with the rest of the map.

`val max_binding : 'a t -> key * 'a`

Return the `(key, value)` pair with the largest key. Raises Not_found if the map is empty.

`val max_binding_opt : 'a t -> (key * 'a) option`

Return `Some (key, value)` for the `key, value` pair with the largest key, or `None` if the map is empty.

• since 3.3.0
`val pop_max_binding : 'a t -> (key * 'a) * 'a t`

Return the (`key, value`) pair with the largest key along with the rest of the map.

`val choose : 'a t -> key * 'a`

Return one binding of the given map. Which binding is chosen is unspecified, but equal bindings will be chosen for equal maps.

• raises Not_found

if the map is empty

`val choose_opt : 'a t -> (key * 'a) option`

Return `Some (k, v)` for one binding `(k, v)` of the given map, if the map is not empty. Else, return None. Which binding is chosen is unspecified, but equal bindings will be chosen for equal maps.

• since 3.3.0
`val any : 'a t -> key * 'a`

Return one binding of the given map. The difference with choose is that there is no guarantee that equals elements will be picked for equal sets. This merely returns the quickest binding to get (O(1)).

• raises Not_found

if the map is empty.

`val split : key -> 'a t -> 'a t * 'a option * 'a t`

`split x m` returns a triple `(l, data, r)`, where `l` is the map with all the bindings of `m` whose key is strictly less than `x`; `r` is the map with all the bindings of `m` whose key is strictly greater than `x`; `data` is `None` if `m` contains no binding for `x`, or `Some v` if `m` binds `v` to `x`.

`val partition : (key -> 'a -> bool) -> 'a t -> 'a t * 'a t`

`partition p m` 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`.

• since 1.4.0
`val singleton : key -> 'a -> 'a t`

`singleton x y` returns the one-element map that contains a binding `y` for `x`.

`val bindings : 'a t -> (key * 'a) list`

Return the list of all bindings of the given map. The returned list is sorted in increasing key order.

Added for compatibility with stdlib 3.12

`val enum : 'a t -> (key * 'a) BatEnum.t`

Return an enumeration of `(key, value)` pairs of a map. The returned enumeration is sorted in increasing order with respect to the ordering `Ord.compare`, where `Ord` is the argument given to `Map.Make`.

`val backwards : 'a t -> (key * 'a) BatEnum.t`

Return an enumeration of `(key, value)` pairs of a map. The returned enumeration is sorted in decreasing order with respect to the ordering `Ord.compare`, where `Ord` is the argument given to `Map.Make`.

`val of_enum : (key * 'a) BatEnum.t -> 'a t`

Create a map from a (key, value) enumeration.

`val for_all : (key -> 'a -> bool) -> 'a t -> bool`

`for_all p m` checks if all the bindings of the map satisfy the predicate `p`.

`val exists : (key -> 'a -> bool) -> 'a t -> bool`

`exists p m` checks if at least one binding of the map satisfy the predicate `p`.

```val merge : (key -> 'a option -> 'b option -> 'c option) -> 'a t -> 'b t -> 'c t```

`merge f m1 m2` 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`.

`val union : (key -> 'a -> 'a -> 'a option) -> 'a t -> 'a t -> 'a t`

`union f m1 m2` computes a map whose keys are a subset of the keys of `m1` and of `m2`. When the same binding is defined in both arguments, the function f is used to combine them. This function is similar to `merge`, except `f` is only called if a key is present in both `m1` and `m2`. If a key is present in either `m1` or `m2` but not in both, it (and the corresponding value) will be present in the resulting map.

• since 3.3.0
`val to_seq : 'a t -> (key * 'a) BatSeq.t`

Iterate on the whole map, in ascending order of keys.

• since 3.3.0
`val to_rev_seq : 'a t -> (key * 'a) BatSeq.t`

Iterate on the whole map, in descending order of keys.

• since 3.3.0
`val to_seq_from : key -> 'a t -> (key * 'a) BatSeq.t`

`to_seq_from k m` iterates on a subset of the bindings in `m`, namely those bindings greater or equal to `k`, in ascending order.

• since 3.3.0
`val add_seq : (key * 'a) BatSeq.t -> 'a t -> 'a t`

add the given bindings to the map, in order.

• since 3.3.0
`val of_seq : (key * 'a) BatSeq.t -> 'a t`

build a map from the given bindings

• since 3.3.0
###### Printing
```val print : ?first:string -> ?last:string -> ?sep:string -> ?kvsep:string -> ('a BatInnerIO.output -> key -> unit) -> ('a BatInnerIO.output -> 'c -> unit) -> 'a BatInnerIO.output -> 'c t -> unit```

Output signature of the functor `Map.Make`.

###### Override modules

The following modules replace functions defined in `Map` with functions behaving slightly differently but having the same name. This is by design: the functions meant to override the corresponding functions of `Map`.

`module Exceptionless : sig ... end`

Operations on `Map` without exceptions.

`module Infix : sig ... end`

Infix operators over a `BatMap`

`module Labels : sig ... end`

Operations on `Map` with labels.