diff options
| -rw-r--r-- | src/doc/rustc-dev-guide/src/ty-fold.md | 56 |
1 files changed, 31 insertions, 25 deletions
diff --git a/src/doc/rustc-dev-guide/src/ty-fold.md b/src/doc/rustc-dev-guide/src/ty-fold.md index d4d0952fcc3..23253022ffe 100644 --- a/src/doc/rustc-dev-guide/src/ty-fold.md +++ b/src/doc/rustc-dev-guide/src/ty-fold.md @@ -1,26 +1,28 @@ +<!-- date-check: may 2024 --> # `TypeFoldable` and `TypeFolder` -In the previous chapter we discussed instantiating binders. This must involves looking at everything inside of a `Early/Binder` -to find any usages of the bound vars in order to replace them. Binders can wrap an arbitrary rust type `T` not just a `Ty` so -how do we implement the `instantiate` methods on the `Early/Binder` types. +In [a previous chapter], we discussed instantiating binders. +This involves looking at everything inside of a `Early(Binder)` +to find any usages of the bound vars in order to replace them. +Binders can wrap an arbitrary Rust type `T`, not just a `Ty`. +So, how do we implement the `instantiate` methods on the `Early/Binder` types? The answer is a couple of traits: -[`TypeFoldable`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/fold/trait.TypeFoldable.html) +[`TypeFoldable`] and -[`TypeFolder`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/fold/trait.TypeFolder.html). +[`TypeFolder`]. - `TypeFoldable` is implemented by types that embed type information. It allows you to recursively process the contents of the `TypeFoldable` and do stuff to them. - `TypeFolder` defines what you want to do with the types you encounter while processing the `TypeFoldable`. -For example, the `TypeFolder` trait has a method -[`fold_ty`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/fold/trait.TypeFolder.html#method.fold_ty) -that takes a type as input and returns a new type as a result. `TypeFoldable` invokes the -`TypeFolder` `fold_foo` methods on itself, giving the `TypeFolder` access to its contents (the -types, regions, etc that are contained within). +For example, the `TypeFolder` trait has a method [`fold_ty`] +that takes a type as input and returns a new type as a result. +`TypeFoldable` invokes the `TypeFolder` `fold_foo` methods on itself, +giving the `TypeFolder` access to its contents (the types, regions, etc that are contained within). -You can think of it with this analogy to the iterator combinators we have come to love in rust: +You can think of it with this analogy to the iterator combinators we have come to love in Rust: ```rust,ignore vec.iter().map(|e1| foo(e2)).collect() @@ -33,8 +35,7 @@ So to reiterate: - `TypeFolder` is a trait that defines a “map” operation. - `TypeFoldable` is a trait that is implemented by things that embed types. -In the case of `subst`, we can see that it is implemented as a `TypeFolder`: -[`ArgFolder`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/binder/struct.ArgFolder.html). +In the case of `subst`, we can see that it is implemented as a `TypeFolder`: [`ArgFolder`]. Looking at its implementation, we see where the actual substitutions are happening. However, you might also notice that the implementation calls this `super_fold_with` method. What is @@ -88,17 +89,22 @@ things. We only want to do something when we reach a type. That means there may `TypeFoldable` types whose implementations basically just forward to their fields’ `TypeFoldable` implementations. Such implementations of `TypeFoldable` tend to be pretty tedious to write by hand. For this reason, there is a `derive` macro that allows you to `#![derive(TypeFoldable)]`. It is -defined -[here](https://github.com/rust-lang/rust/blob/master/compiler/rustc_macros/src/type_foldable.rs). - -**`subst`** In the case of substitutions the [actual -folder](https://github.com/rust-lang/rust/blob/75ff3110ac6d8a0259023b83fd20d7ab295f8dd6/src/librustc_middle/ty/subst.rs#L440-L451) -is going to be doing the indexing we’ve already mentioned. There we define a `Folder` and call -`fold_with` on the `TypeFoldable` to process yourself. Then -[fold_ty](https://github.com/rust-lang/rust/blob/75ff3110ac6d8a0259023b83fd20d7ab295f8dd6/src/librustc_middle/ty/subst.rs#L512-L536) -the method that process each type it looks for a `ty::Param` and for those it replaces it for -something from the list of substitutions, otherwise recursively process the type. To replace it, -calls -[ty_for_param](https://github.com/rust-lang/rust/blob/75ff3110ac6d8a0259023b83fd20d7ab295f8dd6/src/librustc_middle/ty/subst.rs#L552-L587) +defined [here]. + +**`subst`** In the case of substitutions the [actual folder] +is going to be doing the indexing we’ve already mentioned. +There we define a `Folder` and call `fold_with` on the `TypeFoldable` to process yourself. +Then [fold_ty] the method that process each type it looks for a `ty::Param` and for those +it replaces it for something from the list of substitutions, otherwise recursively process the type. +To replace it, calls [ty_for_param] and all that does is index into the list of substitutions with the index of the `Param`. +[a previous chapter]: ty_module/instantiating_binders.md +[`TypeFoldable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/trait.TypeFoldable.html +[`TypeFolder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/trait.TypeFolder.html +[`fold_ty`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/trait.TypeFolder.html#method.fold_ty +[`ArgFolder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/binder/struct.ArgFolder.html +[here]: https://github.com/rust-lang/rust/blob/master/compiler/rustc_macros/src/type_foldable.rs +[actual folder]: https://github.com/rust-lang/rust/blob/75ff3110ac6d8a0259023b83fd20d7ab295f8dd6/src/librustc_middle/ty/subst.rs#L440-L451 +[fold_ty]: https://github.com/rust-lang/rust/blob/75ff3110ac6d8a0259023b83fd20d7ab295f8dd6/src/librustc_middle/ty/subst.rs#L512-L536 +[ty_for_param]: https://github.com/rust-lang/rust/blob/75ff3110ac6d8a0259023b83fd20d7ab295f8dd6/src/librustc_middle/ty/subst.rs#L552-L587 |