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.

use overlay_map::Overlay;

let entry: Overlay<&str> = Overlay::new_empty();
assert!(entry.is_empty());
assert_eq!(entry.fg(), None);
assert_eq!(entry.bg(), None);

pub fn new_fg(val: T) -> Self

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

use overlay_map::Overlay;

let entry = Overlay::new_fg("fg");
assert_eq!(entry.fg(), Some(&"fg"));
assert_eq!(entry.bg(), None);

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

Creates a new Overlay with both foreground and background values.

use overlay_map::Overlay;

let entry = Overlay::new_both("fg", "bg");
assert_eq!(entry.fg(), Some(&"fg"));
assert_eq!(entry.bg(), Some(&"bg"));

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

use overlay_map::OverlayMap;

let mut map = OverlayMap::new();
map.push("x", 10);
map.push("x", 20);
assert_eq!(map.fg(&"x"), Some(&20));
assert_eq!(map.bg(&"x"), Some(&10));

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.

use overlay_map::Overlay;

let entry = Overlay::new_both("fg", "bg");
assert_eq!(entry.fg_unchecked(), &"fg");
assert_eq!(entry.bg_unchecked(), &"bg");

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.

use overlay_map::OverlayMap;

let mut map = OverlayMap::new();
map.push("x", 10);
map.push("x", 20);
assert_eq!(map.fg(&"x"), Some(&20));
assert_eq!(map.bg(&"x"), Some(&10));

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.

use overlay_map::Overlay;

let entry = Overlay::new_both("fg", "bg");
assert_eq!(entry.fg_unchecked(), &"fg");
assert_eq!(entry.bg_unchecked(), &"bg");

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.

use overlay_map::Overlay;

let mut entry = Overlay::new_fg("fg");
assert!(!entry.is_empty());
entry.pull();
assert!(entry.is_empty());

pub fn is_full(&self) -> bool

Returns true if both foreground and background values are currently present.

This is useful for determining whether clear_unchecked is safe to call.

Example

use overlay_map::Overlay;

let mut entry = Overlay::new_both("a", "b");
assert!(entry.is_full());

entry.pull();
assert!(!entry.is_full()); // background promoted, only one value remains

pub fn clear(&mut self)

Clears the overlay, dropping any foreground and background values.

This is the most efficient way to reset the overlay to an empty state. It avoids value movement or promotion and directly drops the contents of both slots (if present). After calling clear, the overlay will report as empty, and both fg() and bg() will return None.

Example

use overlay_map::Overlay;

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

entry.clear();

assert_eq!(entry.fg(), None);
assert_eq!(entry.bg(), None);
assert!(entry.is_empty());

pub fn clear_unchecked(&mut self)

Clears the overlay without checking which slots are present.

This is an unsafe, ultra-fast variant of Overlay::clear that skips all internal presence checks. It will unconditionally drop both slots, regardless of whether they are actually initialized.

Safety

You must guarantee that both the foreground and background values are currently present in the overlay. Calling this when either layer is missing will result in undefined behavior, such as memory corruption or double-drop.

This is intended for use in performance-critical contexts where you already know the exact slot state — for example, if you’ve just cloned from a known full overlay, or you’re clearing a batch of overlays all known to be full.

For a safe version, use clear.

Example

use overlay_map::Overlay;

let mut entry = Overlay::new_both("a", "b");
entry.clear_unchecked(); // caller guarantees both slots are present

assert!(entry.is_empty());

See Also

• Overlay::clear — safe version with slot checks
• Overlay::is_empty — to check for emptiness before clearing

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.

use overlay_map::Overlay;

let mut entry = Overlay::new_both("fg", "bg");
let pulled = entry.pull_unchecked();
assert_eq!(pulled, "fg");
assert_eq!(entry.fg(), Some(&"bg"));

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

pub fn iter(&self) -> impl Iterator<Item = &T>

Get an iterator over the foreground and background values.

use overlay_map::Overlay;

let entry = Overlay::new_both("fg", "bg");
let values: Vec<_> = entry.iter().cloned().collect();
assert_eq!(values, vec!["fg", "bg"]);

pub fn flip(&mut self)

Flips the foreground and background layers, if both are present.

This operation swaps the logical roles of the two slots:

• The foreground becomes the background
• The background becomes the foreground

If only one value is present, the overlay remains unchanged to preserve the guarantee that a foreground value is always present when the overlay is in use.

This is a zero-cost, branchless operation — no memory is moved, cloned, or reallocated. Internally, it simply toggles a bit flag only if both slots are occupied.

Example

use overlay_map::Overlay;

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

entry.flip();

assert_eq!(entry.fg(), Some(&"b"));
assert_eq!(entry.bg(), Some(&"a"));

// Flip has no effect when only one value is present
let mut single = Overlay::new_fg("only");
single.flip();
assert_eq!(single.fg(), Some(&"only"));
assert_eq!(single.bg(), None);

pub fn flip_unchecked(&mut self)

Flips the foreground and background slots without checking if both are present.

This is the unchecked, zero-cost variant of flip, intended for internal or performance-critical use when it is already known that both slots contain valid values.

This method does not perform any presence checks. If one of the slots is uninitialized, calling this method results in undefined behavior when those slots are later accessed.

Safety

The caller must guarantee that:

• Both slots (foreground and background) are currently initialized.
• A subsequent use of fg_unchecked or bg_unchecked will not access uninitialized memory.

Example

use overlay_map::Overlay;

let mut entry = Overlay::new_both("a", "b");
entry.flip_unchecked(); // swaps roles without checks
assert_eq!(entry.fg(), Some(&"b"));
assert_eq!(entry.bg(), Some(&"a"));

Trait Implementations

impl<T: Clone> Clone for Overlay<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T> Default for Overlay<T>

fn default() -> Self

Returns the “default value” for a type.

impl<V> Drop for Overlay<V>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<T> for Overlay<T>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T> IntoIterator for Overlay<T>

fn into_iter(self) -> Self::IntoIter

Creates an iterator over the values in the overlay.

use overlay_map::Overlay;

let entry = Overlay::new_both("fg", "bg");
let values: Vec<_> = entry.into_iter().collect();
assert_eq!(values, vec!["fg", "bg"]);

type Item = T

The type of the elements being iterated over.

type IntoIter = OverlayIntoIter<T>

Which kind of iterator are we turning this into?

impl<T: PartialEq> PartialEq for Overlay<T>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Eq> Eq for Overlay<T>