salsa/
intern_id.rs

1use std::fmt;
2use std::num::NonZeroU32;
3
4/// The "raw-id" is used for interned keys in salsa -- it is basically
5/// a newtype'd u32. Typically, it is wrapped in a type of your own
6/// devising. For more information about interned keys, see [the
7/// interned key RFC][rfc].
8///
9/// # Creating a `InternId`
10//
11/// InternId values can be constructed using the `From` impls,
12/// which are implemented for `u32` and `usize`:
13///
14/// ```
15/// # use salsa::InternId;
16/// let intern_id1 = InternId::from(22_u32);
17/// let intern_id2 = InternId::from(22_usize);
18/// assert_eq!(intern_id1, intern_id2);
19/// ```
20///
21/// # Converting to a u32 or usize
22///
23/// Normally, there should be no need to access the underlying integer
24/// in a `InternId`. But if you do need to do so, you can convert to a
25/// `usize` using the `as_u32` or `as_usize` methods or the `From` impls.
26///
27/// ```
28/// # use salsa::InternId;
29/// let intern_id = InternId::from(22_u32);
30/// let value = u32::from(intern_id);
31/// assert_eq!(value, 22);
32/// ```
33///
34/// ## Illegal values
35///
36/// Be warned, however, that `InternId` values cannot be created from
37/// *arbitrary* values -- in particular large values greater than
38/// `InternId::MAX` will panic. Those large values are reserved so that
39/// the Rust compiler can use them as sentinel values, which means
40/// that (for example) `Option<InternId>` is represented in a single
41/// word.
42///
43/// ```should_panic
44/// # use salsa::InternId;
45/// InternId::from(InternId::MAX);
46/// ```
47///
48/// [rfc]: https://github.com/salsa-rs/salsa-rfcs/pull/2
49#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
50pub struct InternId {
51    value: NonZeroU32,
52}
53
54impl InternId {
55    /// The maximum allowed `InternId`. This value can grow between
56    /// releases without affecting semver.
57    pub const MAX: u32 = 0xFFFF_FF00;
58
59    /// Creates a new InternId. Unsafe as `value` must be less than `MAX`
60    /// and this is not checked in release builds.
61    pub const unsafe fn new_unchecked(value: u32) -> Self {
62        debug_assert!(value < InternId::MAX);
63        InternId {
64            value: NonZeroU32::new_unchecked(value + 1),
65        }
66    }
67
68    /// Convert this raw-id into a u32 value.
69    ///
70    /// ```
71    /// # use salsa::InternId;
72    /// let intern_id = InternId::from(22_u32);
73    /// let value = intern_id.as_usize();
74    /// assert_eq!(value, 22);
75    /// ```
76    pub fn as_u32(self) -> u32 {
77        self.value.get() - 1
78    }
79
80    /// Convert this raw-id into a usize value.
81    ///
82    /// ```
83    /// # use salsa::InternId;
84    /// let intern_id = InternId::from(22_u32);
85    /// let value = intern_id.as_usize();
86    /// assert_eq!(value, 22);
87    /// ```
88    pub fn as_usize(self) -> usize {
89        self.as_u32() as usize
90    }
91}
92
93impl From<InternId> for u32 {
94    fn from(raw: InternId) -> u32 {
95        raw.as_u32()
96    }
97}
98
99impl From<InternId> for usize {
100    fn from(raw: InternId) -> usize {
101        raw.as_usize()
102    }
103}
104
105impl From<u32> for InternId {
106    fn from(id: u32) -> InternId {
107        assert!(id < InternId::MAX);
108        unsafe { InternId::new_unchecked(id) }
109    }
110}
111
112impl From<usize> for InternId {
113    fn from(id: usize) -> InternId {
114        assert!(id < (InternId::MAX as usize));
115        unsafe { InternId::new_unchecked(id as u32) }
116    }
117}
118
119impl fmt::Debug for InternId {
120    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
121        self.as_usize().fmt(f)
122    }
123}
124
125impl fmt::Display for InternId {
126    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
127        self.as_usize().fmt(f)
128    }
129}
salsa/intern_id.rs

salsa/
intern_id.rs
