Struct Overlay

pub struct Overlay<T> { /* private fields */ }

A two-layer value container used by OverlayMap to manage current and historical values.

Overlay<T> stores up to two values:

• A foreground value representing the current state.
• An optional background value representing the previous state.

When used through OverlayMap, each key maps to an Overlay<T> to track updates without requiring clones or reallocations. You can also use Overlay<T> standalone to manage two-layer state transitions for any value type.

Values are moved, never cloned. All operations (push, pull, swap) are zero-cost and memory-efficient.

Use Cases

• Managing current and previous state in UI or simulation logic
• Efficient delta tracking for configs, game state, etc.
• Avoiding Option<(T, T)> or custom wrappers with cloning overhead

Examples

use overlay_map::Overlay;

let mut entry = Overlay::new_fg("current");
entry.push("next"); // moves "current" into background

assert_eq!(entry.fg(), Some(&"next"));
assert_eq!(entry.bg(), Some(&"current"));

let pulled = entry.pull();
assert_eq!(pulled, Some("next"));
assert_eq!(entry.fg(), Some(&"current"));

Implementations

impl<T> Overlay<T>

pub fn new_empty() -> Self

Creates a new Overlay with no values.

pub fn new_fg(val: T) -> Self

Creates a new Overlay with a foreground value and no background.

pub fn new_both(fg: T, bg: T) -> Self

Creates a new Overlay with both foreground and background values.

pub fn fg(&self) -> Option<&T>

Returns a reference to the current foreground value, if present.

This returns Some(&T) only if the foreground slot contains a value. If the slot is logically empty, returns None. This is a safe version that checks the presence bits before accessing memory.

Safety

This function is fully safe and performs a presence check before dereferencing.

Returns

• Some(&T) if the foreground slot is initialized
• None if the foreground slot is uninitialized

pub fn fg_unchecked(&self) -> &T

Returns a reference to the foreground value without checking if it is present.

Safety

This function assumes the foreground slot is initialized. Calling this when the slot is uninitialized (i.e. after a pull() without a background, or after constructing an empty Overlay) results in undefined behavior.

Use fg if you are not certain the slot is populated.

Panics

Never panics, but causes UB if the foreground slot is not present.

pub fn bg(&self) -> Option<&T>

Returns a reference to the background value, if present.

Returns Some(&T) only if the background slot is initialized.

pub fn bg_unchecked(&self) -> &T

Returns a reference to the background value without checking if it is present.

Safety

This assumes the background slot is initialized. Calling this when it is not will cause undefined behavior.

Prefer bg if you’re unsure whether the background is set.

pub fn is_empty(&self) -> bool

Returns true if both slots are empty.

This is used to determine whether the entry contains any values at all. It does not consider which slot is foreground or background.

pub fn push(&mut self, val: T)

Push a value into the foreground layer, preserving the previous foreground in the background.

If the foreground slot already contains a value, it is moved into the background slot. The new value is then written into the foreground slot. Any previous background value will be dropped to make room—no cloning is performed at any point.

This operation is always safe, even if the entry is empty. If no foreground is currently present, the value will simply be inserted.

Example

use overlay_map::Overlay;
let mut entry = Overlay::new_fg("a");
entry.push("b");
assert_eq!(entry.fg(), Some(&"b"));
assert_eq!(entry.bg(), Some(&"a"));

pub fn pull(&mut self) -> Option<T>

Safely pull the current foreground value out, promoting the background to foreground if present.

If the foreground value is present, it is removed and returned. The background (if any) is promoted to the foreground. If neither value remains, the entry becomes empty.

Returns None if the foreground was not present.

Example

use overlay_map::Overlay;
let mut entry = Overlay::new_both("a", "b");
let pulled = entry.pull();
assert_eq!(pulled, Some("a"));
assert_eq!(entry.fg(), Some(&"b")); // background promoted

pub fn pull_unchecked(&mut self) -> T

Pull the current foreground value without checking if it is present.

Safety

The caller must ensure the foreground slot is present. If it is not, this will result in undefined behavior.

See Self::pull for a safe alternative.

pub fn swap(&mut self, val: T) -> Option<T>

Swap in a new foreground value, returning the old background if present.

If a background value exists, it is evicted and returned. The new value is written into the background slot, which is then promoted to become the new foreground. The current foreground is preserved in-place.

If no background was present, this behaves like a standard push operation, and None is returned.

Example

use overlay_map::Overlay;
let mut entry = Overlay::new_both("a", "b");
let evicted = entry.swap("c");
assert_eq!(evicted, Some("b"));
assert_eq!(entry.fg(), Some(&"c"));
assert_eq!(entry.bg(), Some(&"a"));

Trait Implementations

impl<T: Debug> Debug for Overlay<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<V> Drop for Overlay<V>

fn drop(&mut self)

Executes the destructor for this type.