vendor/salsa/src/intern_id.rs

   1 use std::fmt;
   2 use 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)]
  50 pub struct InternId {
  51     value: NonZeroU32,
  52 }
  53
  54 impl 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     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
  93 impl From<InternId> for u32 {
  94     fn from(raw: InternId) -> u32 {
  95         raw.as_u32()
  96     }
  97 }
  98
  99 impl From<InternId> for usize {
 100     fn from(raw: InternId) -> usize {
 101         raw.as_usize()
 102     }
 103 }
 104
 105 impl From<u32> for InternId {
 106     fn from(id: u32) -> InternId {
 107         assert!(id < InternId::MAX);
 108         unsafe { InternId::new_unchecked(id) }
 109     }
 110 }
 111
 112 impl 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
 119 impl fmt::Debug for InternId {
 120     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 121         self.as_usize().fmt(f)
 122     }
 123 }
 124
 125 impl fmt::Display for InternId {
 126     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 127         self.as_usize().fmt(f)
 128     }
 129 }