1use std::cmp::Ordering;
2use std::fmt::{self, Debug};
3use std::hash::{Hash, Hasher};
4use std::ops::Deref;
5use std::ptr;
67use crate::stable_hasher::{HashStable, StableHasher};
89mod private {
10#[derive(Clone, Copy, Debug)]
11pub struct PrivateZst;
12}
1314/// A reference to a value that is interned, and is known to be unique.
15///
16/// Note that it is possible to have a `T` and a `Interned<T>` that are (or
17/// refer to) equal but different values. But if you have two different
18/// `Interned<T>`s, they both refer to the same value, at a single location in
19/// memory. This means that equality and hashing can be done on the value's
20/// address rather than the value's contents, which can improve performance.
21///
22/// The `PrivateZst` field means you can pattern match with `Interned(v, _)`
23/// but you can only construct a `Interned` with `new_unchecked`, and not
24/// directly.
25#[rustc_pass_by_value]
26pub struct Interned<'a, T>(pub &'a T, pub private::PrivateZst);
2728impl<'a, T> Interned<'a, T> {
29/// Create a new `Interned` value. The value referred to *must* be interned
30 /// and thus be unique, and it *must* remain unique in the future. This
31 /// function has `_unchecked` in the name but is not `unsafe`, because if
32 /// the uniqueness condition is violated condition it will cause incorrect
33 /// behaviour but will not affect memory safety.
34#[inline]
35pub const fn new_unchecked(t: &'a T) -> Self {
36Interned(t, private::PrivateZst)
37 }
38}
3940impl<'a, T> Clonefor Interned<'a, T> {
41fn clone(&self) -> Self {
42*self43}
44}
4546impl<'a, T> Copyfor Interned<'a, T> {}
4748impl<'a, T> Dereffor Interned<'a, T> {
49type Target = T;
5051#[inline]
52fn deref(&self) -> &T {
53self.0
54}
55}
5657impl<'a, T> PartialEqfor Interned<'a, T> {
58#[inline]
59fn eq(&self, other: &Self) -> bool {
60// Pointer equality implies equality, due to the uniqueness constraint.
61ptr::eq(self.0, other.0)
62 }
63}
6465impl<'a, T> Eqfor Interned<'a, T> {}
6667impl<'a, T: PartialOrd> PartialOrdfor Interned<'a, T> {
68fn partial_cmp(&self, other: &Interned<'a, T>) -> Option<Ordering> {
69// Pointer equality implies equality, due to the uniqueness constraint,
70 // but the contents must be compared otherwise.
71if ptr::eq(self.0, other.0) {
72Some(Ordering::Equal)
73 } else {
74let res = self.0.partial_cmp(other.0);
75debug_assert_ne!(res, Some(Ordering::Equal));
76res77 }
78 }
79}
8081impl<'a, T: Ord> Ordfor Interned<'a, T> {
82fn cmp(&self, other: &Interned<'a, T>) -> Ordering {
83// Pointer equality implies equality, due to the uniqueness constraint,
84 // but the contents must be compared otherwise.
85if ptr::eq(self.0, other.0) {
86Ordering::Equal87 } else {
88let res = self.0.cmp(other.0);
89debug_assert_ne!(res, Ordering::Equal);
90res91 }
92 }
93}
9495impl<'a, T> Hashfor Interned<'a, T>
96where
97T: Hash,
98{
99#[inline]
100fn hash<H: Hasher>(&self, s: &mut H) {
101// Pointer hashing is sufficient, due to the uniqueness constraint.
102ptr::hash(self.0, s)
103 }
104}
105106impl<T, CTX> HashStable<CTX> for Interned<'_, T>
107where
108T: HashStable<CTX>,
109{
110fn hash_stable(&self, hcx: &mut CTX, hasher: &mut StableHasher) {
111self.0.hash_stable(hcx, hasher);
112 }
113}
114115impl<T: Debug> Debugfor Interned<'_, T> {
116fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
117self.0.fmt(f)
118 }
119}
120121#[cfg(test)]
122mod tests;