Struct ValueOverlay

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

A sparse overlay of rank ranges and values, used to assemble or patch a [ValueMesh] without materializing per-rank data.

Unlike ValueMesh, which always represents a complete, gap-free mapping over a [Region], a ValueOverlay is intentionally partial: it may describe only the ranks that have changed. This allows callers to build and merge small, incremental updates efficiently, while preserving the ValueMesh invariants after merge.

Invariants:

• Runs are sorted by (start, end).
• Runs are non-empty and non-overlapping.
• Adjacent runs with equal values are coalesced.
• Region bounds are validated when the overlay is merged, not on insert.

Note: serialization assumes identical pointer width between sender and receiver, as Range<usize> is not portable across architectures. TODO: introduce a wire‐stable run type.

Implementations

impl<T> ValueOverlay<T>

pub fn new() -> Self

Creates an empty overlay.

pub fn runs(&self) -> impl Iterator<Item = &(Range<usize>, T)>

Returns an iterator over the internal runs.

pub fn len(&self) -> usize

Current number of runs.

pub fn is_empty(&self) -> bool

Returns true if the overlay contains no runs. This indicates that no ranges have been added — i.e., the overlay represents an empty or no-op patch.

impl<T: PartialEq> ValueOverlay<T>

pub fn push_run( &mut self, range: Range<usize>, value: T, ) -> Result<(), BuildError>

Adds a (range, value) run while maintaining the overlay invariants.

Fast path:

• If range is after the last run (last.end <= range.start), this is an O(1) append. If it touches the last run and value is equal, the two runs are coalesced by extending end.

Slow path:

• If the input is unsorted or overlaps the last run, the method falls back to a full normalize (sort + coalesce + overlap check), making this call O(n log n) in the number of runs.

Errors:

• Returns BuildError::EmptyRange if range.is_empty().

Notes & guidance:

• Use this for already-sorted, non-overlapping appends to get the cheap fast path.
• For bulk or unsorted inserts, prefer ValueOverlay::try_from_runs (collect → sort → coalesce) to avoid repeated re-normalization.
• Adjacent equal-value runs are coalesced automatically.

Examples

let mut ov = ValueOverlay::new();
ov.push_run(0..3, 1).unwrap();      // append
ov.push_run(3..5, 1).unwrap();      // coalesces to (0..5, 1)

// Unsorted input triggers normalize (O(n log n)):
ov.push_run(1..2, 2).unwrap();      // re-sorts, checks overlaps, coalesces

pub fn try_from_runs<I>(runs: I) -> Result<Self, BuildError>

where I: IntoIterator<Item = (Range<usize>, T)>,

Builds an overlay from arbitrary runs, validating structure and coalescing equal-adjacent.

Trait Implementations

impl<T: Clone> Clone for ValueOverlay<T>

fn clone(&self) -> ValueOverlay<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for ValueOverlay<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for ValueOverlay<T>

fn default() -> ValueOverlay<T>

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for ValueOverlay<T>

where T: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Named> Named for ValueOverlay<T>

fn typename() -> &'static str

The globally unique type name for the type. This should typically be the fully qualified Rust name of the type.

fn typehash() -> u64

A globally unique hash for this type. TODO: actually enforce perfect hashing

fn typeid() -> TypeId

The TypeId for this type. TypeIds are unique only within a binary, and should not be used for global identification.

fn port() -> u64

The globally unique port for this type. Typed ports are in the range of 1<<63..1<<64-1.

fn arm(&self) -> Option<&'static str>

If the named type is an enum, this returns the name of the arm of the value self.

unsafe fn arm_unchecked(self_: *const ()) -> Option<&'static str>

An unsafe version of ‘arm’, accepting a pointer to the value, for use in type-erased settings.

impl<T: PartialEq> PartialEq for ValueOverlay<T>

fn eq(&self, other: &ValueOverlay<T>) -> 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> Serialize for ValueOverlay<T>

where T: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Eq> Eq for ValueOverlay<T>

impl<T> StructuralPartialEq for ValueOverlay<T>