Trait VirtualNMap

pub trait VirtualNMap<For: Delimited, Discriminant: DiscriminantTag = ()> {
    type Key: Delimited + EncodeLikeTuple<<Self::KeyGen as KeyGenerator>::KArg> + TupleToEncodedIter;
    type Value: Delimited;
    type KeyGen: KeyGenerator + ReversibleKeyGenerator;
    type Map: StorageNMap<Self::KeyGen, Self::Value, Query = Self::Query> + IterableStorageNMap<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 as KeyGenerator>::Key, Self::Value)> { ... }
    fn iter_keys() -> impl Iterator<Item = <Self::KeyGen as KeyGenerator>::Key> { ... }
    fn iter_values() -> impl Iterator<Item = Self::Value> { ... }
    fn drain(    ) -> impl Iterator<Item = (<Self::KeyGen as KeyGenerator>::Key, Self::Value)> { ... }
    fn count() -> usize { ... }
    fn iter_prefix_values<P>(prefix: P) -> impl Iterator<Item = Self::Value>
       where Self::KeyGen: HasKeyPrefix<P> { ... }
    fn iter_prefix<P>(
        prefix: P,
    ) -> impl Iterator<Item = (<Self::KeyGen as HasKeyPrefix<P>>::Suffix, Self::Value)>
       where Self::KeyGen: HasReversibleKeyPrefix<P> { ... }
    fn iter_key_prefix<P>(
        prefix: P,
    ) -> impl Iterator<Item = <Self::KeyGen as HasKeyPrefix<P>>::Suffix>
       where Self::KeyGen: HasReversibleKeyPrefix<P> { ... }
    fn drain_prefix<P>(
        prefix: P,
    ) -> impl Iterator<Item = (<Self::KeyGen as HasKeyPrefix<P>>::Suffix, Self::Value)>
       where Self::KeyGen: HasReversibleKeyPrefix<P> { ... }
}

A storage-backed virtual n-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. [StorageNMap]).

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
• VirtualNMap - container-level map storage

These components are:

• logically part of the container
• but not required to share a single physical representation

Ownership and Delegation

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

• it defines the type context (e.g. 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 separation allows:

• lightweight container representations
• efficient handling of large or frequently mutated data
• independent evolution of storage and structure

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 [StorageNMap]
• keys are encoded using [KeyGenerator]
• iteration and prefix-based access 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 + EncodeLikeTuple<<Self::KeyGen as KeyGenerator>::KArg> + TupleToEncodedIter

Key used to address entries in the map.

Must:

• match the input shape expected by KeyGen::KArg
• support tuple-style encoding for multi-key storage
• allow iteration over encoded components

type Value: Delimited

Value stored in the map.

Typically represents externally stored data associated with the container.

type KeyGen: KeyGenerator + ReversibleKeyGenerator

Defines how Key is transformed into storage keys.

Supports:

• forward encoding into storage
• reverse decoding for iteration and prefix traversal

type Map: StorageNMap<Self::KeyGen, Self::Value, Query = Self::Query> + IterableStorageNMap<Self::KeyGen, Self::Value, Query = Self::Query> + StoragePrefixedMap<Self::Value>

Underlying storage map backing this abstraction.

Must support:

• basic CRUD operations
• full iteration
• prefix-based queries and draining

type Query

Return type for read operations.

Encodes presence/absence semantics (e.g. Option<Value>).

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.

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 both insert/update/remove cases.

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

Iterate over all (full_key, value) pairs.

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

Iterate over all full keys.

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

Iterate over all values.

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

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

fn count() -> usize

Count total number of entries.

fn iter_prefix_values<P>(prefix: P) -> impl Iterator<Item = Self::Value>

where Self::KeyGen: HasKeyPrefix<P>,

Iterate over values matching a prefix.

Prefix corresponds to a partial key (leading components).

fn iter_prefix<P>( prefix: P, ) -> impl Iterator<Item = (<Self::KeyGen as HasKeyPrefix<P>>::Suffix, Self::Value)>

where Self::KeyGen: HasReversibleKeyPrefix<P>,

Iterate over (suffix, value) under a prefix.

suffix = remaining key components after the prefix.

fn iter_key_prefix<P>( prefix: P, ) -> impl Iterator<Item = <Self::KeyGen as HasKeyPrefix<P>>::Suffix>

where Self::KeyGen: HasReversibleKeyPrefix<P>,

Iterate over suffix keys under a prefix.

fn drain_prefix<P>( prefix: P, ) -> impl Iterator<Item = (<Self::KeyGen as HasKeyPrefix<P>>::Suffix, Self::Value)>

where Self::KeyGen: HasReversibleKeyPrefix<P>,

Drain entries under a prefix, yielding (suffix, value).

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