PathMap Structure

The intro chapter described [PathMap] as a collection of values, but crucially it is actually a tree of paths. In other words, paths can exist by themselves in the absence of values.

A structure of paths is required to host values, but values are entirely optional. A path that terminates without any value or downstream children is still a valid path, and is known as a "dangling" path.

Creating and Removing Paths

PathMap provides several methods to manage path structure independently of values.

Creating Paths

[create_path] creates a dangling path (without a value) in the trie. This is useful when you need to establish path structure before adding values, or when you want to mark certain paths as existing without storing data at those locations.

#![allow(unused)]
fn main() {
extern crate pathmap;
use pathmap::PathMap;

let mut map = PathMap::<i32>::new();
assert!(!map.path_exists_at(b"path/to/data"));

// Create the path structure without a value
map.create_path(b"path/to/data");
assert!(map.path_exists_at(b"path/to/data"));
assert_eq!(map.get_val_at(b"path/to/data"), None); // No value stored
}

Checking Path Existence

[path_exists_at] checks whether a specific path exists in the trie, regardless of whether it has an associated value.

#![allow(unused)]
fn main() {
extern crate pathmap;
use pathmap::PathMap;

let mut map = PathMap::new();
map.insert(b"existing/path", 42);

assert!(map.path_exists_at(b"existing/path"));
assert!(map.path_exists_at(b"existing"));      // Parent path also exists
assert!(!map.path_exists_at(b"nonexistent"));
}

Removing Path Structure

[remove_branches_at] removes all child paths below the specified path. The prune parameter controls whether the path itself should be removed if it becomes dangling.

#![allow(unused)]
fn main() {
extern crate pathmap;
use pathmap::PathMap;

let mut map = PathMap::new();
map.insert(b"base/branch1/leaf", 1);
map.insert(b"base/branch2/leaf", 2);

// Remove all branches under "base", keeping "base" as dangling path
map.remove_branches_at(b"base", false);
assert!(map.path_exists_at(b"base"));
assert!(!map.path_exists_at(b"base/branch1"));
}

[prune_path] removes dangling path segments, working upward from the specified path until it reaches a path with a value or multiple children. This is useful for cleaning up empty path structure.

#![allow(unused)]
fn main() {
extern crate pathmap;
use pathmap::PathMap;

let mut map = PathMap::<()>::new();
map.create_path(b"long/dangling/path/chain");

// Prune the dangling path - removes the entire chain since no values exist
let removed_bytes = map.prune_path(b"long/dangling/path/chain");
assert_eq!(removed_bytes, 24); // Length of the entire path
assert!(!map.path_exists_at(b"long"));
}