Modifying the Trie

The ZipperWriting trait provides methods to modify the trie structure and values. This trait provides comprehensive functionality for creating, updating, and removing data within the trie.

Direct Value Access

• get_val_mut returns a mutable reference to the value at the focus, or None if no value exists
• set_val sets the value at the focus, returning any previously existing value
• remove_val removes the value at the focus, optionally pruning dangling paths

Upsert Value Access (Create-Or-Update)

• get_val_or_set_mut returns a mutable reference to the value at the focus, inserting the provided default if no value exists
• get_val_or_set_mut_with similar to above, but uses a closure to generate the default value when needed

Path Creation and Removal

• create_path ensures a path exists to the current focus, creating intermediate nodes as needed
• prune_path removes dangling path segments above the focus that have no values or branches
• prune_ascend combines pruning with ascension, moving to the first non-dangling path

Subtrie Shifting

• insert_prefix adds a prefix to all downstream paths from the focus
• remove_prefix removes the specified number of bytes from paths above the focus

Subtrie Moving and Copying

• graft replaces the subtrie below the focus with content from another zipper's focus
• graft_map replaces the subtrie below the focus with the contents of a PathMap
• take_map extracts the subtrie below the focus into a new PathMap, removing it from the original

Branch Removal

• remove_branches removes all child branches below the focus
• remove_unmasked_branches selectively removes branches based on a byte mask

Pruning Behavior

Many operations accept a prune parameter that controls whether dangling paths should be automatically cleaned up. When prune is true, the operation will remove any path segments that become empty, aka "dangling" (no values, and no further downstream branches) as a result of the modification.

Automatic pruning helps maintain a compact trie structure by removing unnecessary nodes, but can be counter-productive when you plan to perform additional operations that might reuse those paths.