Struct SecondaryMap 

pub struct SecondaryMap<T, K: Key = DefaultKey> { /* private fields */ }

A secondary map that associates data with keys from a DeferredMap.

SecondaryMap allows you to store additional information for each key in a DeferredMap. It is separate from the primary map and does not affect the primary map’s memory layout.

Key Features:

• Sparse Storage: Efficiently handles cases where not all keys in the primary map have associated data.
• Generation Checking: Automatically validates compatibility with the primary map’s keys. Stale keys (from older generations) will be ignored or overwritten as appropriate.
• Automatic Expansion: The map automatically grows to accommodate keys with larger indices.

一个辅助映射（SecondaryMap），用于将数据与 DeferredMap 的 Key 关联。

SecondaryMap 允许你为 DeferredMap 中的每个 Key 存储额外信息。 它与主映射分离，不影响主映射的内存布局。

主要特性：

• 稀疏存储：高效处理主映射中并非所有 Key 都有关联数据的情况。
• 代数检查：自动验证与主映射 Key 的兼容性。过期的 Key（来自旧代数）将被忽略或覆盖。
• 自动扩展：映射会自动增长以适应具有更大索引的 Key。

Examples (示例)

use deferred_map::{DeferredMap, SecondaryMap};

let mut map = DeferredMap::new();
let handle = map.allocate_handle();
let key = handle.key();
map.insert(handle, "Primary Value");

let mut sec_map = SecondaryMap::new();
sec_map.insert(key, 100);

assert_eq!(sec_map.get(key), Some(&100));

Implementations

impl<T, K: Key> SecondaryMap<T, K>

pub fn new() -> Self

Create a new empty SecondaryMap

创建一个新的空 SecondaryMap

pub fn with_capacity(capacity: usize) -> Self

Create a SecondaryMap with specified capacity

创建一个指定容量的 SecondaryMap

pub fn insert(&mut self, key: K, value: T) -> Option<T>

Insert a value for a specific key

If the key belongs to an older generation than what is currently stored, the insertion is ignored. If the key is newer, it overwrites the existing value.

为特定 Key 插入值

如果 Key 的代数（generation）老于当前存储的代数，插入将被忽略。 如果 Key 是新的，它将覆盖现有值。

Returns

• Some(old_value) if a value existed for the EXACT same key (same index and generation).
• None otherwise.

pub fn remove(&mut self, key: K) -> Option<T>

Remove value by key

Only removes if both index and generation match.

通过 Key 移除值

仅当索引和代数都匹配时才移除。

pub fn get(&self, key: K) -> Option<&T>

Get reference to value by key

通过 Key 获取值的引用

pub fn get_mut(&mut self, key: K) -> Option<&mut T>

Get mutable reference to value by key

通过 Key 获取值的可变引用

pub fn contains_key(&self, key: K) -> bool

Check if key exists

检查 Key 是否存在

pub fn len(&self) -> usize

Return the number of elements

返回元素数量

pub fn is_empty(&self) -> bool

Check if empty

检查是否为空

pub fn capacity(&self) -> usize

Capacity of the underlying vector

底层 vector 的容量

pub fn clear(&mut self)

Clear all elements

Does not deallocate memory, but clears validity.

清空所有元素 不会释放内存，但会清除有效性。

pub fn retain<F>(&mut self, f: F)

where F: FnMut(K, &mut T) -> bool,

Retains only the elements specified by the predicate.

只保留满足谓词的元素。

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

Iterator over all (key, value) pairs

遍历所有 (key, value) 对的迭代器

pub fn iter_mut(&mut self) -> impl Iterator<Item = (K, &mut T)>

Mutable iterator over all (key, value) pairs

遍历所有 (key, value) 对的可变迭代器

Trait Implementations

impl<T: Clone, K: Clone + Key> Clone for SecondaryMap<T, K>

fn clone(&self) -> SecondaryMap<T, K>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for SecondaryMap<T>

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

Formats the value using the given formatter.

impl<T, K: Key> Default for SecondaryMap<T, K>

fn default() -> Self

Returns the “default value” for a type.