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"));
}