BatMap

# Module BatMap

    module BatMap: sig .. end

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 `BatMap.S` and `BatMap.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 `BatMap.Make` module which builds association maps from a user-provided datatype and comparison function. In the `BatMap.Make` module (or its output signature `BatMap.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
        ...

You can also use predefined maps such as `BatMap.IntMap` for maps with integer keys.
Author(s): Xavier Leroy (Base library), Nicolas Cannasse, Markus Mottl, David Rajchenbach-Teller, Gabriel Scherer

    module type S = sig .. end

    module StringMap: S  with type key = String.t

A map on strings.

    module IStringMap: S  with type key = String.t

A map on strings.

    module NumStringMap: S  with type key = String.t

A map on strings.

    module IntMap: S  with type key = BatInt.t

A map on integers.

    module Make: functor (Ord : BatInterfaces.OrderedType) -> S  with type key = Ord.t

Functor building an implementation of the map structure given a totally ordered type.

#### Polymorphic maps

The functions below present the manipulation of polymorphic maps, as were provided by the Extlib PMap module.

They are similar in functionality to the functorized `BatMap.Make` module, but the compiler cannot ensure that maps using different key ordering have different types: the responsibility of not mixing non-sensical comparison functions together is to the programmer. If in doubt, you should rather use the `BatMap.Make` functor for additional safety.

    type ('a, 'b) t

    val empty : ('a, 'b) t

The empty map, using `compare` as key comparison function.

    val is_empty : ('a, 'b) t -> bool

returns true if the map is empty.

    val create : ('a -> 'a -> int) -> ('a, 'b) t

creates a new empty map, using the provided function for key comparison.

    val singleton : ?cmp:('a -> 'a -> int) -> 'a -> 'b -> ('a, 'b) t

creates a new map with a single binding

    val cardinal : ('a, 'b) t -> int

Return the number of bindings of a map.

    val add : 'a -> 'b -> ('a, 'b) t -> ('a, 'b) 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.

    val find : 'a -> ('a, 'b) t -> 'b

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

    val remove : 'a -> ('a, 'b) t -> ('a, 'b) t

`remove x m` returns a map containing the same bindings as `m`, except for `x` which is unbound in the returned map.

    val mem : 'a -> ('a, 'b) t -> bool

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

    val exists : 'a -> ('a, 'b) t -> bool

Deprecated.`mem` should be used instead, as `exists` conflicts with the function checking arbitrary predicates, which is instead named `exists_f`.
same as `mem`.

    val iter : ('a -> 'b -> unit) -> ('a, 'b) 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 order in which the bindings are passed to `f` is unspecified. Only current bindings are presented to `f`: bindings hidden by more recent bindings are not passed to `f`.

    val map : ('a -> 'b) -> ('c, 'a) t -> ('c, '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 order in which the associated values are passed to `f` is unspecified.

    val mapi : ('a -> 'b -> 'c) -> ('a, 'b) t -> ('a, 'c) t

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

    val fold : ('a -> 'b -> 'b) -> ('c, '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`, and `d0,d1..dN` are the associated data. The order in which the bindings are presented to `f` is unspecified.

    val foldi : ('a -> 'b -> 'c -> 'c) -> ('a, 'b) t -> 'c -> 'c

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

    val filter : ('a -> bool) -> ('b, 'a) t -> ('b, 'a) t

`filter 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 filteri : ('a -> 'b -> bool) -> ('a, 'b) t -> ('a, 'b) t

`filter f m` returns a map where only the (key, value) pairs `key`, `a` of `m` such that `f key 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_map : ('a -> 'b -> 'c option) -> ('a, 'b) t -> ('a, 'c) t

`filter_map f m` combines the features of `filteri` and `map`. It calls calls `f key0 a0`, `f key1 a1`, `f keyn an` where `a0..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 choose : ('a, 'b) t -> 'a * 'b

Return one binding of the given map, or raise `Not_found` if the map is empty. Which binding is chosen is unspecified, but equal bindings will be chosen for equal maps.

    val split : 'a -> ('a, 'b) t -> ('a, 'b) t * 'b option * ('a, 'b) 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 min_binding : ('a, 'b) t -> 'a * 'b

returns the binding with the smallest key

    val max_binding : ('a, 'b) t -> 'a * 'b

returns the binding with the largest key

    val enum : ('a, 'b) t -> ('a * 'b) BatEnum.t

creates an enumeration for this map, enumerating key,value pairs with the keys in increasing order.

    val backwards : ('a, 'b) t -> ('a * 'b) BatEnum.t

creates an enumeration for this map, enumerating key,value pairs with the keys in decreasing order.

    val keys : ('a, 'b) t -> 'a BatEnum.t

Return an enumeration of all the keys of a map.

    val values : ('a, 'b) t -> 'b BatEnum.t

Return an enumeration of al the values of a map.

    val of_enum : ?cmp:('a -> 'a -> int) -> ('a * 'b) BatEnum.t -> ('a, 'b) t

creates a map from an enumeration, using the specified function for key comparison or `compare` by default.

    val for_all : ('a -> 'b -> bool) -> ('a, 'b) t -> bool

Tests whether all key value pairs satisfy some predicate function

    val exists_f : ('a -> 'b -> bool) -> ('a, 'b) t -> bool

Tests whether some key value pair satisfies some predicate function

    val partition : ('a -> 'b -> bool) ->
           ('a, 'b) t -> ('a, 'b) t * ('a, 'b) 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`.

    val add_carry : 'a -> 'b -> ('a, 'b) t -> ('a, 'b) t * 'b option

`add_carry k v m` adds the binding `(k,v)` to `m`, returning the new map and optionally the previous value bound to `k`.

    val modify : 'a -> ('b -> 'b) -> ('a, 'b) t -> ('a, 'b) 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 -> 'b -> ('a -> 'a) -> ('b, 'a) t -> ('b, '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 extract : 'a -> ('a, 'b) t -> 'b * ('a, 'b) t

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

    val pop : ('a, 'b) t -> ('a * 'b) * ('a, 'b) t

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

    val union : ('a, 'b) t -> ('a, 'b) t -> ('a, 'b) t

`union m1 m2` merges two maps, using the comparison function of `m1`. In case of conflicted bindings, `m2`'s bindings override `m1`'s. Equivalent to `foldi add m2 m1`. The resulting map uses the comparison function of `m1`.

    val diff : ('a, 'b) t -> ('a, 'b) t -> ('a, 'b) t

`diff m1 m2` removes all bindings of keys found in `m2` from `m1`, using the comparison function of `m1`. Equivalent to `foldi (fun k _v m -> remove k m) m2 m1` The resulting map uses the comparison function of `m1`.

    val intersect : ('a -> 'b -> 'c) ->
           ('d, 'a) t -> ('d, 'b) t -> ('d, 'c) t

`intersect merge_f m1 m2` returns a map with bindings only for keys bound in both `m1` and `m2`, and with `k` bound to `merge_f v1 v2`, where `v1` and `v2` are `k`'s bindings in `m1` and `m2`. The resulting map uses the comparison function of `m1`.

    val merge : ('a -> 'b option -> 'c option -> 'd option) ->
           ('a, 'b) t -> ('a, 'c) t -> ('a, 'd) 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`. The resulting map uses the comparison function of `m1`.

    val merge_unsafe : ('a -> 'b option -> 'c option -> 'd option) ->
           ('a, 'b) t -> ('a, 'c) t -> ('a, 'd) t

Same as merge, but assumes the comparison function of both maps are equal. If it's not the case, the result is a map using the comparison function of its first parameter, but which `'b option` elements are passed to the function is unspecified.

    module Exceptionless: sig .. end

Exceptionless versions of functions

    module Infix: sig .. end

Infix operators over a `BatPMap`

    val bindings : ('a, 'b) t -> ('a * 'b) 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

###### Boilerplate code

Printing

    val print : ?first:string ->
           ?last:string ->
           ?sep:string ->
           ('a BatInnerIO.output -> 'b -> unit) ->
           ('a BatInnerIO.output -> 'c -> unit) ->
           'a BatInnerIO.output -> ('b, 'c) t -> unit