package irmin-containers

empty is the empty tree. The empty tree does not have associated backend configuration values, as they can perform in-memory operation, independently of any given backend.

of_contents c is the subtree built from the contents c.

of_node n is the subtree built from the node n.

The type for tree elements.

General-purpose constructor for trees.

pruned h is a purely in-memory tree with the hash h. Such trees can be used as children of other in-memory tree nodes, for instance in order to compute the hash of the parent, but they cannot be dereferenced.

Any operation that would require loading the contents of a pruned node (e.g. calling find on one of its children) will instead raise a Pruned_hash exception. Attempting to export a tree containing pruned sub-trees to a repository will fail similarly.

kind t k is the type of s in t. It could either be a tree node or some file contents. It is None if k is not present in t.

is_empty t is true iff t is empty (i.e. a tree node with no children). Trees with kind = `Contents are never considered empty.

diff x y is the difference of contents between x and y.

The type for errors.

Operations on lazy nodes can fail if the underlying store does not contain the expected hash.

The exception raised by functions that can force lazy tree nodes but do not return an explicit or_error.

The exception raised by functions that attempt to load pruned tree nodes.

Operations on lazy tree contents.

mem t k is true iff k is associated to some contents in t.

find_all t k is Some (b, m) if k is associated to the contents b and metadata m in t and None if k is not present in t.

find n is the number of entries in n.

find is similar to find_all but it discards metadata.

Same as find_all but raise Invalid_arg if k is not present in t.

list t key is the list of files and sub-nodes stored under k in t. The result order is not specified but is stable.

offset and length are used for pagination.

cache defaults to true, see caching for an explanation of the parameter.

Same as get_all but ignore the metadata.

add t k c is the tree where the key k is bound to the contents c but is similar to t for other bindings.

update t k f is the tree t' that is the same as t for all keys except k, and whose binding for k is determined by f (find t k).

If k refers to an internal node of t, f is called with None to determine the value with which to replace it.

remove t k is the tree where k bindings has been removed but is similar to t for other bindings.

mem_tree t k is false iff find_tree k = None.

find_tree t k is Some v if k is associated to v in t. It is None if k is not present in t.

get_tree t k is v if k is associated to v in t. Raise Invalid_arg if k is not present in t.

add_tree t k v is the tree where the key k is bound to the non-empty tree v but is similar to t for other bindings.

If v is empty, this is equivalent to remove t k.

update_tree t k f is the tree t' that is the same as t for all subtrees except under k, and whose subtree at k is determined by f (find_tree t k).

f returning either None or Some empty causes the subtree at k to be unbound (i.e. it is equivalent to remove t k).

merge is the 3-way merge function for trees.

General-purpose destructor for trees.

The type for fold marks.

empty_marks () is an empty collection of marks.

The type for fold's force parameter. `True forces the fold to read the objects of the lazy nodes and contents. `False f is applying f on every lazy node and content value instead.

The type for fold's uniq parameters. `False folds over all the nodes. `True does not recurse on nodes already seen. `Marks m uses the collection of marks m to store the cache of keys: the fold will modify m. This can be used for incremental folds.

The type for fold's pre and post parameters.

The type for fold depths.

• Eq d folds over nodes and contents of depth exactly d.
• Lt d folds over nodes and contents of depth strictly less than d.
• Gt d folds over nodes and contents of depth strictly more than d.

Le d is Eq d and Lt d. Ge d is Eq d and Gt d.

fold f t acc folds f over t's leafs.

For every node n, ui n is a leaf node, call f path n. Otherwise:

• Call pre path n. By default pre is the identity;
• Recursively call fold on each children.
• Call post path n; By default post is the identity.

See force for details about the force parameters. By default it is `True.

See uniq for details about the uniq parameters. By default it is `False.

The fold depth is controlled by the depth parameter.

cache defaults to false, see caching for an explanation of the parameter.

If order is `Sorted (the default), the elements are traversed in lexicographic order of their keys. If `Random state, they are traversed in a random order. For large nodes, these two modes are memory-consuming, use `Undefined for a more memory efficient fold.

The type for tree stats.

stats ~force t are t's statistics. If force is true, this will force the reading of lazy nodes. By default it is false.

The type for concrete trees.

The value-type for concrete.

of_concrete c is the subtree equivalent of the concrete tree c.

• raises Invalid_argument

  if c contains duplicate bindings for a given path.

to_concrete t is the concrete tree equivalent of the subtree t.

clear ?depth t clears all caches in the tree t for subtrees with a depth higher than depth. If depth is not set, all of the subtrees are cleared.

A call to clear doesn't discard the subtrees of t, only their cache are discarded. Even the lazily loaded and unmodified subtrees remain.

hash r c it c's hash in the repository r.

Hashes in the Irmin store are tagged with the type of the value they reference (either contents or node). In the contents case, the hash is paired with corresponding metadata.

of_hash r h is the the tree object in r having h as hash, or None is no such tree object exists.

shallow r h is the shallow tree object with the hash h. No check is performed to verify if h actually exists in r.