The Base Zipper Trait

The Zipper trait forms the foundation of all zipper types in PathMap. It provides the minimal interface needed to inspect the structure of the trie at the zipper's focus. It is implemented on all zipper types.

The base trait defines three essential types of operations which are fundamental to all pathmap tries:

Path Existence

• path_exists returns whether the zipper's focus is positioned on a valid path within the trie. This is fundamental since zippers can be positioned on non-existent paths - locations that could potentially hold data but currently don't.

Value Presence

• is_val indicates whether there is a value stored at the current focus position. Note that a path can exist in the trie structure without necessarily having a value, and the trie may continue deeper from this point regardless of whether a value is present or not.

Child Branches

Two methods provide information about the trie structure below the current focus:

• child_count returns the number of child branches extending from the current node.
• child_mask returns a 256-bit mask indicating exactly which byte values have corresponding child branches.

ZipperConcrete

The ZipperConcrete trait is implemented on zippers that traverse in-memory trie structures, as opposed to virtual tries or abstract projections. It primarily provides the method to inspect structural sharing.

• is_shared returns whether the zipper's focus is at a location that may be accessed via multiple distinct paths (including from other maps). This information is useful for optimization but should never be relied upon for correctness, as sharing behavior can change due to internal operations like thread isolation or representation changes.

ZipperSubtries

The ZipperSubtries trait provides methods for zippers that can access concrete subtries within PathMaps. This trait is required to use a zipper as a source for graft or to provide arguments to the zipper algebraic operations

• make_map creates a new PathMap containing everything below the zipper's focus. This allows extraction of the subtrie as an independent data structures.

ZipperReadOnlySubtries

The ZipperReadOnlySubtries trait extends ZipperSubtries for read-only zippers, providing a mechanism to create TrieRef objects.

• trie_ref_at_path returns a TrieRef for a specified path relative to the current focus

ZipperForking

The ZipperForking trait enables creating temporary zippers from existing zippers.

• fork_read_zipper creates a new read-only zipper with its root at the current focus. The returned zipper implements ZipperAbsolutePath + ZipperIteration + ZipperValues. This is useful for constructing child zippers with different roots, creating read zippers from other zipper types, or creating zippers to pass to functions that take ownership. However, cloning the parent zipper is often preferable when you need to maintain the original zipper.