Trait VirtualMap

pub trait VirtualMap<For: Delimited, Discriminant: DiscriminantTag = ()> {
    type Key: Delimited + EncodeLike<Self::KeyGen> + TupleToEncodedIter;
    type Value: Delimited;
    type KeyGen: KeyGenerator + ReversibleKeyGenerator + EncodeLike;
    type Map: StorageMap<Self::KeyGen, Self::Value, Query = Self::Query> + IterableStorageMap<Self::KeyGen, Self::Value, Query = Self::Query> + StoragePrefixedMap<Self::Value>;
    type Query;

    // Provided methods
    fn get(key: Self::Key) -> Self::Query { ... }
    fn insert(key: Self::Key, value: Self::Value) { ... }
    fn remove(key: Self::Key) { ... }
    fn take(key: Self::Key) -> Self::Query { ... }
    fn contains_key(key: Self::Key) -> bool { ... }
    fn mutate<R>(
        key: Self::Key,
        f: impl FnOnce(&mut Option<Self::Value>) -> R,
    ) -> R { ... }
    fn iter() -> impl Iterator<Item = (Self::KeyGen, Self::Value)> { ... }
    fn iter_keys() -> impl Iterator<Item = Self::KeyGen> { ... }
    fn iter_values() -> impl Iterator<Item = Self::Value> { ... }
    fn drain() -> impl Iterator<Item = (Self::KeyGen, Self::Value)> { ... }
    fn count() -> usize { ... }
}

A storage-backed virtual map owned by a container in the virtual structure system.

This trait defines a map-like virtual component that is logically owned by a container (For), while its storage is delegated to an external implementation (e.g. [StorageMap]).

Virtual Structure Context

In the virtual system, a container (virtual struct) composes behavior through independent, type-driven components:

• VirtualDynField / VirtualStaticField - field-level abstraction over values and cardinality
• VirtualDynExtension / VirtualStaticExtension - externally defined field schemas
• VirtualMap - container-level map storage

These components are logically part of the container, but are not required to share a single physical representation.

Ownership and Delegation

The container (For) acts as the owner of the map:

• it provides the type context for the map (key/value via associated types)
• it determines how the map is used
• but it does not store the map directly

Instead, storage is delegated to a native map implementation.

This allows:

• avoiding encode/decode overhead from embedding maps in representations
• efficient handling of large or frequently mutated data
• separation of structure (types) from storage (runtime)

Type-Level Association

• For: the owning container (virtual struct)
• Discriminant: a type-level key identifying this map

This enables:

• multiple independent maps per container
• map definitions derived from container-level abstractions
• coherence-safe composition via distinct discriminants

Storage Model

• storage is provided by the implementor via [StorageMap]
• keys are encoded via [KeyGenerator]
• iteration and full traversal are supported

The map is external in storage, but internal in ownership and usage.

When to Use

Use this trait when:

• a container logically owns map-like data
• key/value types depend on container-level abstractions
• data is large, dynamic, or frequently mutated
• embedding the map in a virtual field or representation is inefficient

Default Discriminant

• Discriminant = (): defines a single default map, meaning one virtual map is assumed per container.

Required Associated Types

type Key: Delimited + EncodeLike<Self::KeyGen> + TupleToEncodedIter

Key used to address entries in the map.

Must:

• be encodable in the same form as KeyGen
• support iteration over encoded components (for uniform handling)

type Value: Delimited

Value stored in the map.

Represents externally stored data associated with the container.

type KeyGen: KeyGenerator + ReversibleKeyGenerator + EncodeLike

Defines how keys are encoded into storage and decoded back.

Supports:

• forward encoding into storage keys
• reverse decoding during iteration

type Map: StorageMap<Self::KeyGen, Self::Value, Query = Self::Query> + IterableStorageMap<Self::KeyGen, Self::Value, Query = Self::Query> + StoragePrefixedMap<Self::Value>

Underlying storage map backing this abstraction.

Must support:

• basic CRUD operations
• full iteration over keys and values
• prefixed storage layout

type Query

Return type for read operations.

Typically Option<Value> or a query wrapper.

Provided Methods

fn get(key: Self::Key) -> Self::Query

Fetch value associated with key.

fn insert(key: Self::Key, value: Self::Value)

Insert or overwrite value at key.

fn remove(key: Self::Key)

Remove value at key.

fn take(key: Self::Key) -> Self::Query

Remove and return value at key.

fn contains_key(key: Self::Key) -> bool

Check if key exists in the map.

fn mutate<R>(key: Self::Key, f: impl FnOnce(&mut Option<Self::Value>) -> R) -> R

Mutate value at key in-place.

Provides Option<Value> to handle insert/update/remove semantics.

fn iter() -> impl Iterator<Item = (Self::KeyGen, Self::Value)>

Iterate over all (key, value) pairs.

fn iter_keys() -> impl Iterator<Item = Self::KeyGen>

Iterate over all keys.

fn iter_values() -> impl Iterator<Item = Self::Value>

Iterate over all values.

fn drain() -> impl Iterator<Item = (Self::KeyGen, Self::Value)>

Drain entire map, yielding all (key, value) pairs.

fn count() -> usize

Count total number of entries.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors