Module paths 

Functionality around Willow Paths.

The central type of this module is the Path struct, which represents a single willow Path. Paths are immutable, which means any operation that would traditionally mutate paths (for example, appending a new component) returns a new, independent value instead.

The Path struct is generic over three const generic parameters, corresponding to the Willow parameters which limit the size of paths:

• the MCL parameter gives the (max_component_length),
• the MCC parameter gives the (max_component_count), and
• the MPL parameter gives the (max_path_length).

All (safely created) Pathsrespect those parameters. The functions in this module return PathErrors or PathFromComponentsErrors when those invariants would be violated.

The type-level docs of Path list all the ways in which you can build up paths dynamically.

The Path struct provides methods for checking various properties of paths: from simple properties (“how many components does this have”) to various comparisons (“is this path a prefix of some other”), the methods should have you covered.

Because path prefixes play such a central role for deletion in Willow, the functionality around prefixes is optimised. Creating a prefix or even iterating over all prefixes performs no memory allocations.

The Component type represents individual path Components. This type is a thin wrapper around [u8] (enforcing a maximal length of MCL bytes); like [u8] it must always be used as part of a pointer type — for example, &Component<MCL>. Alternatively, the OwnedComponent type can be used by itself — keeping an OwnedComponent alive will also keep around the heap allocation for the full Path from which it was constructed, though. Generally speaking, the more lightweight Component should be preferred over OwnedComponent where possible.

Modules

path_extends_path

Implementations of the EncodePathExtendsPath encoding relation.

Structs

Component

A slice of a Path Component.

InvalidComponentError

An error arising from trying to construct a Component of length strictly greater than the MCL (max_component_length).

OwnedComponent

An owned component of a Willow Path, using reference counting for cheap cloning. Typically obtained from a Path instead of being created independently.

Path

An immutable Willow Path. Thread-safe, cheap to clone, cheap to take prefixes of, expensive to append to (linear time complexity).

PathBuilder

A helper struct for creating a Path with exactly one memory allocation. Requires total length and component count to be known in advance.

Enums

PathError

An error arising from trying to construct an invalid Path.

PathFromComponentsError

An error arising from trying to construct an invalid Path from valid Components.