Struct DeferredMap

Source

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

Expand description

DeferredMap is a high-performance map based on slotmap

Usage requires first obtaining a Handle via allocate_handle, then using the Handle to insert.

DeferredMap 是一个基于 slotmap 的高性能映射表

使用前需要先通过 allocate_handle 获取 Handle，然后使用 Handle 进行插入

§Features (特性)

O(1) insertion, lookup, and removal | O(1) 插入、查找和删除
Generational indices prevent use-after-free | 代数索引防止释放后使用
Handle-based deferred insertion | 基于 Handle 的延迟插入
Memory efficient with union-based slots | 使用 union 的内存高效 slot

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();

// Allocate handle first | 先分配 handle
let handle = map.allocate_handle();
let key = handle.key();

// Insert value later | 之后插入值
map.insert(handle, 42);

// Access value | 访问值
assert_eq!(map.get(key), Some(&42));

// Remove value | 删除值
assert_eq!(map.remove(key), Some(42));

Implementations§

Source §

impl<T> DeferredMap<T, DefaultKey>

Source

pub fn new() -> Self

Create a new empty DeferredMap

创建一个新的空 DeferredMap

§Examples (示例)

use deferred_map::DeferredMap;

let map: DeferredMap<i32> = DeferredMap::new();
assert!(map.is_empty());

Source §

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

Source

pub fn with_capacity(capacity: usize) -> Self

Create a DeferredMap with specified capacity

创建一个指定容量的 DeferredMap

§Parameters

capacity: Initial capacity (number of slots to pre-allocate)

§参数

capacity: 初始容量（预分配的 slot 数量）

§Examples (示例)

use deferred_map::DeferredMap;

let map: DeferredMap<i32> = DeferredMap::with_capacity(100);
assert!(map.capacity() >= 100);

Source

pub fn allocate_handle(&mut self) -> Handle<K>

Pre-allocate a Handle

This Handle can be used later to insert a value. The slot is immediately created in Reserved state.

预分配一个 Handle

这个 Handle 可以在之后用于插入值 slot 立即创建为 Reserved 状态

§Returns

A unique Handle for later insertion

§返回值

用于后续插入的唯一 Handle

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();
let handle = map.allocate_handle();
let key = handle.key();
map.insert(handle, "value");
assert_eq!(map.get(key), Some(&"value"));

Source

pub fn insert(&mut self, handle: Handle<K>, value: T)

Insert value using Handle

The Handle is consumed (moved), ensuring it can only be used once. The slot must be in Reserved state.

使用 Handle 插入值

Handle 会被消耗（move），确保只能使用一次 slot 必须处于 Reserved 状态

§Parameters

handle: The Handle obtained from allocate_handle
value: The value to insert

§参数

handle: 从 allocate_handle 获取的 Handle
value: 要插入的值

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();
let handle = map.allocate_handle();
let key = handle.key();
map.insert(handle, 42);
assert_eq!(map.get(key), Some(&42));

Source

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

Get immutable reference to value by u64 key

通过 u64 key 获取值的不可变引用

§Parameters

key: The key returned from insert

§Returns

Some(&T): Reference to the value if key is valid
None: If key is invalid or value has been removed

§参数

key: 从 insert 返回的 key

§返回值

Some(&T): 如果 key 有效则返回值的引用
None: 如果 key 无效或值已被删除

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();
let handle = map.allocate_handle();
let key = handle.key();
map.insert(handle, 42);
assert_eq!(map.get(key), Some(&42));

Source

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

Get mutable reference to value by u64 key

通过 u64 key 获取值的可变引用

§Parameters

key: The key returned from insert

§Returns

Some(&mut T): Mutable reference to the value if key is valid
None: If key is invalid or value has been removed

§参数

key: 从 insert 返回的 key

§返回值

Some(&mut T): 如果 key 有效则返回值的可变引用
None: 如果 key 无效或值已被删除

§Examples (示例)

use deferred_map::DeferredMap;

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

if let Some(value) = map.get_mut(key) {
    *value = 100;
}
assert_eq!(map.get(key), Some(&100));

Source

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

Remove value by u64 key

If successful, returns the removed value and adds the slot to the free list.

通过 u64 key 移除值

如果成功移除，返回被移除的值，并将该 slot 加入空闲列表

§Parameters

key: The key returned from insert

§Returns

Some(T): The removed value if key is valid
None: If key is invalid or value has already been removed

§参数

key: 从 insert 返回的 key

§返回值

Some(T): 如果 key 有效则返回被移除的值
None: 如果 key 无效或值已被删除

§Examples (示例)

use deferred_map::DeferredMap;

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

assert_eq!(map.remove(key), Some(42));
assert_eq!(map.get(key), None);

Source

pub fn release_handle(&mut self, handle: Handle<K>)

Release an unused Handle

Returns the reserved slot back to the free list. This is useful when you allocated a handle but decided not to use it.

释放未使用的 Handle

将预留的 slot 返回到空闲列表当你分配了 handle 但决定不使用时很有用

§Parameters

handle: The Handle to release

§参数

handle: 要释放的 Handle

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::<i32>::new();
let handle = map.allocate_handle();

// Decided not to use it
// 决定不使用它
map.release_handle(handle);

Source

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

Check if key exists

检查 key 是否存在

§Parameters

key: The key to check

§Returns

true if the key exists, false otherwise

§参数

key: 要检查的 key

§返回值

如果 key 存在则返回 true，否则返回 false

§Examples (示例)

use deferred_map::DeferredMap;

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

assert!(map.contains_key(key));
map.remove(key);
assert!(!map.contains_key(key));

Source

pub fn len(&self) -> usize

Return the number of valid elements

返回有效元素的数量

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();
assert_eq!(map.len(), 0);

let handle = map.allocate_handle();
map.insert(handle, 42);
assert_eq!(map.len(), 1);

Source

pub fn is_empty(&self) -> bool

Check if the map is empty

检查是否为空

§Examples (示例)

use deferred_map::DeferredMap;

let map: DeferredMap<i32> = DeferredMap::new();
assert!(map.is_empty());

Source

pub fn capacity(&self) -> usize

Return capacity (number of allocated slots, excluding sentinel)

返回容量（已分配的 slot 数量，不包括 sentinel）

§Examples (示例)

use deferred_map::DeferredMap;

let map: DeferredMap<i32> = DeferredMap::with_capacity(10);
assert!(map.capacity() >= 10);

Source

pub fn clear(&mut self)

Clear all elements

清空所有元素

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();
let handle = map.allocate_handle();
map.insert(handle, 42);

map.clear();
assert!(map.is_empty());

Source

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

Return an iterator over all (key, value) pairs

返回一个迭代器，遍历所有 (key, value) 对

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();

let h1 = map.allocate_handle();
map.insert(h1, 1);

let h2 = map.allocate_handle();
map.insert(h2, 2);

let sum: i32 = map.iter().map(|(_, v)| v).sum();
assert_eq!(sum, 3);

Source

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

Return a mutable iterator over all (key, value) pairs

返回一个可变迭代器，遍历所有 (key, value) 对

§Examples (示例)

use deferred_map::DeferredMap;

let mut map = DeferredMap::new();

let h1 = map.allocate_handle();
map.insert(h1, 1);

let h2 = map.allocate_handle();
map.insert(h2, 2);

for (_, value) in map.iter_mut() {
    *value *= 2;
}

let sum: i32 = map.iter().map(|(_, v)| v).sum();
assert_eq!(sum, 6);

Source

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the map. The map may reserve more space to speculatively avoid frequent reallocations.

预留至少能容纳 additional 个额外元素的空间。 Map 可能会预留更多空间以避免频繁的重新分配。