Crate overlay_map

A two-layered map structure where the foreground is mutable and the background is preserved.

OverlayMap lets you insert values without cloning, while keeping a single layer of historical context. Each key has a current value (foreground) and may have a previous value (background), which is automatically managed during updates.

use overlay_map::OverlayMap;

#[derive(Debug, Clone, PartialEq)]
struct QuantumBit {
    collapsed: bool,
    value: Option<bool>,
}

/// Simulates measurement collapse
fn collapse(mut qbit: QuantumBit) -> QuantumBit {
    qbit.collapsed = true;
    qbit.value = Some(rand::random());
    qbit
}

fn main() {
    let mut qstate = OverlayMap::<&str, QuantumBit>::new();

    // Push an uncollapsed qubit
    qstate.push(
        "qbit_1",
        QuantumBit {
            collapsed: false,
            value: None,
        },
    );

    // Observe the qubit: only collapse if it's not already
    let did_observe = qstate.push_if(&"qbit_1", |current| {
        if current.collapsed {
            None // already collapsed, don't change
        } else {
            Some(collapse(current.clone())) // clone *only* if needed
        }
    });

    println!("Was observed?       {}", did_observe);
    println!("After observation:  {:?}", qstate.fg(&"qbit_1"));
    println!("Before observation: {:?}", qstate.bg(&"qbit_1"));
}

Structs

OverlayMap

A two-layered map where each key has a mutable foreground and an optional background value.