blazemap 0.5.1

Implements a vector-based slab-like map with an interface similar to that of HashMap, and also provides tools for generating lightweight identifiers that can be type-safely used as keys for this map.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

use std::{hash::Hash, num::NonZeroUsize};

/// Holds and provides the `usize` offset.
///
/// Necessary to protect the internal `usize`, which, in the absence of this
/// wrapper, would be public in the module calling
/// the [`define_key_wrapper`](crate::define_key_wrapper).
///
/// Publicity of the internal `usize` may lead to:
/// * UB if the programmer of the downstream crate accidentally mutates it.
/// * Incorrect auto-derives of standard traits such as `Default`, `Debug`,
///   `Display`, `PartialOrd`, `Ord`, `serde::Serialize` and
///   `serde::Deserialize`.
#[derive(Clone, Copy, Eq, PartialEq, Hash)]
#[repr(transparent)]
#[doc(hidden)]
#[allow(missing_debug_implementations)]
pub struct OffsetProvider<T>(T);

impl OffsetProvider<usize> {
    #[inline]
    #[must_use]
    pub unsafe fn new(offset: usize) -> Self {
        Self(offset)
    }

    #[inline]
    #[must_use]
    pub fn into_offset(self) -> usize {
        self.0
    }
}

impl OffsetProvider<NonZeroUsize> {
    #[inline]
    #[must_use]
    pub unsafe fn new(offset: usize) -> Self {
        let inner = offset.checked_add(1).expect("usize overflow");
        Self(unsafe { NonZeroUsize::new_unchecked(inner) })
    }

    #[inline]
    #[must_use]
    pub fn into_offset(self) -> usize {
        self.0.get() - 1
    }
}

#[cfg(test)]
mod tests {
    use std::{
        fmt::{Debug, Display},
        num::NonZeroUsize,
    };

    #[cfg(feature = "serde")]
    use serde::{Deserialize, Serialize};
    use static_assertions::assert_not_impl_any;

    use crate::utils::offset_provider::OffsetProvider;

    // These assertions are needed to prevent standard traits
    // from being automatically derived for types
    // generated by the [`define_key_wrapper`](crate::define_plain_id) macro.
    assert_not_impl_any!(OffsetProvider<usize>: Default, Debug, Display, PartialOrd);
    assert_not_impl_any!(OffsetProvider<NonZeroUsize>: Default, Debug, Display, PartialOrd);

    #[cfg(feature = "serde")]
    assert_not_impl_any!(OffsetProvider<usize>: Serialize, Deserialize<'static>);
    #[cfg(feature = "serde")]
    assert_not_impl_any!(OffsetProvider<NonZeroUsize>: Serialize, Deserialize<'static>);
}