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 [PathMap]s. 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.