package incr_map

unordered_fold i ~init ~add ~remove constructs a more incremental version of:

let%map m = i in
Map.fold m ~init ~f:add

assuming that remove is the inverse of add, and that the operations for different keys can be performed in any order. Note that data_equal defaults to phys_equal, but a more precise equality can be provided instead.

When the data for a key updates, by default remove is called on the old data and then add is called on the new data. update provides an alternative single function to call each time a key's data updates, and can be used to improve efficiency.

For the initial computation, by default add is called on all the elements in the map. As this can be inefficient, specialized_initial can be provided to perform the computation in a more effective way.

Like merge in Base.Map.merge. Note that f is called at most once per key in any given stabilization.

This is the "easy" version of join

The non-incremental semantics of this function is the identity function. Its purpose is to collapse the extra level of incrementality at the level of the data of the map.

subrange map (min, max) constructs an incremental submap that includes all of the keys and data from map between min and max, and none of the keys outside the range.

subrange map None is the empty map. range being None means no elements are chosen.

Note that incremental changes have a runtime of O((k + m) log n) where k is the size of the changes to the underlying map and m is the size of the changes to the elements contained by the range. The complexity of the initial computation is the same as the incremental computation, with some simplification. k = 0 because we have not made any changes to the underlying map yet, and m equals the size of the range, because the initial range is empty.

subrange_by_rank map (s, e) constructs an incremental submap that includes (e-s+1) keys between s-th and e-th, inclusive.

If s is greater or equal to map length, the result is empty. If e is greater or equal to map length, the result contains keys from s-th to the last one.

Raises for invalid indices - s < 0 or e < s.

Runtime of the initial computation is O(min(e, n-s) + log(n)), i.e. linear, but optimized for ranges close to beginning or end.

Runtime of the incremental computation is O(log(n) + k + (m+m') * log(n)) where:

• k is the size of the diff
• m is the total impact of map changes on the range, bounded by k (e.g. if we add 1001 keys and remove 1000 below s, then m = 1)
• m' = O( |new s - old s| + |new e - old e| ).

index_by map ~comparator ~index constructs an incremental map-of-maps where each key-data pair of the input map is present in one (or none) of the inner maps. index specifies the outer map key under which each original key-data pair is found.

All of the resulting inner maps are guaranteed to be non-empty.

An all-at-once version of index_by would look like:

let index_by map ~comparator ~index =
  Map.to_alist map
  |> List.filter_map ~f:(fun (key, data) ->
    match index data with
    | None -> None
    | Some index -> index, (key, data))
  |> Map.of_alist_multi comparator
  |> Map.map ~f:(Map.of_alist_exn (Map.comparator_s map))
;;

('k, 'v) Lookup.t provides a way to lookup keys in a map which uses symmetric diffs to trigger updates of the lookups.