|
| 1 | +rustc_index::newtype_index! { |
| 2 | + /// A [De Bruijn index][dbi] is a standard means of representing |
| 3 | + /// regions (and perhaps later types) in a higher-ranked setting. In |
| 4 | + /// particular, imagine a type like this: |
| 5 | + /// ```ignore (illustrative) |
| 6 | + /// for<'a> fn(for<'b> fn(&'b isize, &'a isize), &'a char) |
| 7 | + /// // ^ ^ | | | |
| 8 | + /// // | | | | | |
| 9 | + /// // | +------------+ 0 | | |
| 10 | + /// // | | | |
| 11 | + /// // +----------------------------------+ 1 | |
| 12 | + /// // | | |
| 13 | + /// // +----------------------------------------------+ 0 |
| 14 | + /// ``` |
| 15 | + /// In this type, there are two binders (the outer fn and the inner |
| 16 | + /// fn). We need to be able to determine, for any given region, which |
| 17 | + /// fn type it is bound by, the inner or the outer one. There are |
| 18 | + /// various ways you can do this, but a De Bruijn index is one of the |
| 19 | + /// more convenient and has some nice properties. The basic idea is to |
| 20 | + /// count the number of binders, inside out. Some examples should help |
| 21 | + /// clarify what I mean. |
| 22 | + /// |
| 23 | + /// Let's start with the reference type `&'b isize` that is the first |
| 24 | + /// argument to the inner function. This region `'b` is assigned a De |
| 25 | + /// Bruijn index of 0, meaning "the innermost binder" (in this case, a |
| 26 | + /// fn). The region `'a` that appears in the second argument type (`&'a |
| 27 | + /// isize`) would then be assigned a De Bruijn index of 1, meaning "the |
| 28 | + /// second-innermost binder". (These indices are written on the arrows |
| 29 | + /// in the diagram). |
| 30 | + /// |
| 31 | + /// What is interesting is that De Bruijn index attached to a particular |
| 32 | + /// variable will vary depending on where it appears. For example, |
| 33 | + /// the final type `&'a char` also refers to the region `'a` declared on |
| 34 | + /// the outermost fn. But this time, this reference is not nested within |
| 35 | + /// any other binders (i.e., it is not an argument to the inner fn, but |
| 36 | + /// rather the outer one). Therefore, in this case, it is assigned a |
| 37 | + /// De Bruijn index of 0, because the innermost binder in that location |
| 38 | + /// is the outer fn. |
| 39 | + /// |
| 40 | + /// [dbi]: https://en.wikipedia.org/wiki/De_Bruijn_index |
| 41 | + #[derive(HashStable_Generic)] |
| 42 | + #[debug_format = "DebruijnIndex({})"] |
| 43 | + pub struct DebruijnIndex { |
| 44 | + const INNERMOST = 0; |
| 45 | + } |
| 46 | +} |
| 47 | + |
| 48 | +rustc_index::newtype_index! { |
| 49 | + /// A **ty**pe **v**ariable **ID**. |
| 50 | + #[debug_format = "?{}t"] |
| 51 | + pub struct TyVid {} |
| 52 | +} |
| 53 | + |
| 54 | +rustc_index::newtype_index! { |
| 55 | + /// An **int**egral (`u32`, `i32`, `usize`, etc.) type **v**ariable **ID**. |
| 56 | + #[debug_format = "?{}i"] |
| 57 | + pub struct IntVid {} |
| 58 | +} |
| 59 | + |
| 60 | +rustc_index::newtype_index! { |
| 61 | + /// A **float**ing-point (`f32` or `f64`) type **v**ariable **ID**. |
| 62 | + #[debug_format = "?{}f"] |
| 63 | + pub struct FloatVid {} |
| 64 | +} |
| 65 | + |
| 66 | +rustc_index::newtype_index! { |
| 67 | + /// "Universes" are used during type- and trait-checking in the |
| 68 | + /// presence of `for<..>` binders to control what sets of names are |
| 69 | + /// visible. Universes are arranged into a tree: the root universe |
| 70 | + /// contains names that are always visible. Each child then adds a new |
| 71 | + /// set of names that are visible, in addition to those of its parent. |
| 72 | + /// We say that the child universe "extends" the parent universe with |
| 73 | + /// new names. |
| 74 | + /// |
| 75 | + /// To make this more concrete, consider this program: |
| 76 | + /// |
| 77 | + /// ```ignore (illustrative) |
| 78 | + /// struct Foo { } |
| 79 | + /// fn bar<T>(x: T) { |
| 80 | + /// let y: for<'a> fn(&'a u8, Foo) = ...; |
| 81 | + /// } |
| 82 | + /// ``` |
| 83 | + /// |
| 84 | + /// The struct name `Foo` is in the root universe U0. But the type |
| 85 | + /// parameter `T`, introduced on `bar`, is in an extended universe U1 |
| 86 | + /// -- i.e., within `bar`, we can name both `T` and `Foo`, but outside |
| 87 | + /// of `bar`, we cannot name `T`. Then, within the type of `y`, the |
| 88 | + /// region `'a` is in a universe U2 that extends U1, because we can |
| 89 | + /// name it inside the fn type but not outside. |
| 90 | + /// |
| 91 | + /// Universes are used to do type- and trait-checking around these |
| 92 | + /// "forall" binders (also called **universal quantification**). The |
| 93 | + /// idea is that when, in the body of `bar`, we refer to `T` as a |
| 94 | + /// type, we aren't referring to any type in particular, but rather a |
| 95 | + /// kind of "fresh" type that is distinct from all other types we have |
| 96 | + /// actually declared. This is called a **placeholder** type, and we |
| 97 | + /// use universes to talk about this. In other words, a type name in |
| 98 | + /// universe 0 always corresponds to some "ground" type that the user |
| 99 | + /// declared, but a type name in a non-zero universe is a placeholder |
| 100 | + /// type -- an idealized representative of "types in general" that we |
| 101 | + /// use for checking generic functions. |
| 102 | + #[derive(HashStable_Generic)] |
| 103 | + #[debug_format = "U{}"] |
| 104 | + pub struct UniverseIndex {} |
| 105 | +} |
0 commit comments