Module Base.Map

Test if the invariants of the internal AVL search tree hold.

Returns a first-class module that can be used to build other map/set/etc. with the same notion of comparison.

The empty map.

A map with one (key, data) pair.

Creates a map from an association list with unique keys.

Creates a map from an association list with unique keys, returning an error if duplicate 'a keys are found.

Creates a map from an association list with unique keys, raising an exception if duplicate 'a keys are found.

Creates a map from an association list with possibly repeated keys. The values in the map for a given key appear in the same order as they did in the association list.

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

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

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.

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

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

of_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.

of_increasing_sequence c seq behaves like of_sorted_array c (Sequence.to_array seq), but does not allocate the intermediate array.

The sequence will be folded over once, and the additional time complexity is O(n).

Tests whether a map is empty.

length map returns the number of elements in map. O(1), but Tree.length is O(n).

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

add t ~key ~data adds a new entry to t mapping key to data and returns `Ok with the new map, or if key is already present in t, returns `Duplicate.

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

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

Returns the value bound to the given key, or the empty list if there is none.

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).

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

Returns the value bound to the given key, raising Caml.Not_found of Not_found_s if none exists.

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

mem map key tests whether map contains a binding for key.

Iterates two maps side by side. The 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)].

Returns a new map with bound values replaced by f applied to the bound values.

Like map, but the passed function takes both key and data as arguments.

Folds over keys and data in the map in increasing order of key.

Folds over keys and data in the map in decreasing order of key.

Folds over two maps side by side, like iter2.

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

Returns a new map with bound values filtered by f applied to the bound values.

Like filter_map, but the passed function takes both key and data as arguments.

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

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

       partitioni_tf t ~f
       =
       partition_mapi t ~f:(fun ~key ~data ->
         if f ~key ~data
         then `Fst data
         else `Snd data)

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

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

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.

equal cmp m1 m2 tests whether the maps m1 and m2 are equal, that is, contain the same keys and associate each key with the same value. cmp is the equality predicate used to compare the values associated with the keys.

Returns a list of the keys in the given map.

Returns a list of the data in the given map.

Creates an association list from the given map.

Merges two maps. The runtime is O(length(t1) + length(t2)). You shouldn't use this function to merge a list of maps; consider using merge_skewed instead.

A special case of merge, merge_skewed t1 t2 is a map containing all the bindings of t1 and t2. Bindings that appear in both t1 and t2 are combined into a single value using the combine function. In a call combine ~key v1 v2, the value v1 comes from t1 and v2 from t2.

The runtime of merge_skewed is O(l1 * log(l2)), where l1 is the length of the smaller map and l2 the length of the larger map. This is likely to be faster than merge when one of the maps is a lot smaller, or when you merge a list of maps.

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.

min_elt map returns Some (key, data) pair corresponding to the minimum key in map, or None if empty.

max_elt map returns Some (key, data) pair corresponding to the maximum key in map, or None if map is empty.

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.

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);

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.

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).

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.

closest_key t dir k returns the (key, value) pair in t with key closest to k that 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.

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.

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

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.