1 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Generalized type folding mechanism. The setup is a bit convoluted
12 //! but allows for convenient usage. Let T be an instance of some
13 //! "foldable type" (one which implements `TypeFoldable`) and F be an
14 //! instance of a "folder" (a type which implements `TypeFolder`). Then
15 //! the setup is intended to be:
17 //! T.fold_with(F) --calls--> F.fold_T(T) --calls--> T.super_fold_with(F)
19 //! This way, when you define a new folder F, you can override
20 //! `fold_T()` to customize the behavior, and invoke `T.super_fold_with()`
21 //! to get the original behavior. Meanwhile, to actually fold
22 //! something, you can just write `T.fold_with(F)`, which is
23 //! convenient. (Note that `fold_with` will also transparently handle
24 //! things like a `Vec<T>` where T is foldable and so on.)
26 //! In this ideal setup, the only function that actually *does*
27 //! anything is `T.super_fold_with()`, which traverses the type `T`.
28 //! Moreover, `T.super_fold_with()` should only ever call `T.fold_with()`.
30 //! In some cases, we follow a degenerate pattern where we do not have
31 //! a `fold_T` method. Instead, `T.fold_with` traverses the structure directly.
32 //! This is suboptimal because the behavior cannot be overridden, but it's
33 //! much less work to implement. If you ever *do* need an override that
34 //! doesn't exist, it's not hard to convert the degenerate pattern into the
37 //! A `TypeFoldable` T can also be visited by a `TypeVisitor` V using similar setup:
38 //! T.visit_with(V) --calls--> V.visit_T(T) --calls--> T.super_visit_with(V).
39 //! These methods return true to indicate that the visitor has found what it is looking for
40 //! and does not need to visit anything else.
45 use ty
::{self, Binder, Ty, TyCtxt, TypeFlags}
;
48 use util
::nodemap
::{FnvHashMap, FnvHashSet}
;
50 /// The TypeFoldable trait is implemented for every type that can be folded.
51 /// Basically, every type that has a corresponding method in TypeFolder.
52 pub trait TypeFoldable
<'tcx
>: fmt
::Debug
+ Clone
{
53 fn super_fold_with
<F
: TypeFolder
<'tcx
>>(&self, folder
: &mut F
) -> Self;
54 fn fold_with
<F
: TypeFolder
<'tcx
>>(&self, folder
: &mut F
) -> Self {
55 self.super_fold_with(folder
)
58 fn super_visit_with
<V
: TypeVisitor
<'tcx
>>(&self, visitor
: &mut V
) -> bool
;
59 fn visit_with
<V
: TypeVisitor
<'tcx
>>(&self, visitor
: &mut V
) -> bool
{
60 self.super_visit_with(visitor
)
63 fn has_regions_escaping_depth(&self, depth
: u32) -> bool
{
64 self.visit_with(&mut HasEscapingRegionsVisitor { depth: depth }
)
66 fn has_escaping_regions(&self) -> bool
{
67 self.has_regions_escaping_depth(0)
70 fn has_type_flags(&self, flags
: TypeFlags
) -> bool
{
71 self.visit_with(&mut HasTypeFlagsVisitor { flags: flags }
)
73 fn has_projection_types(&self) -> bool
{
74 self.has_type_flags(TypeFlags
::HAS_PROJECTION
)
76 fn references_error(&self) -> bool
{
77 self.has_type_flags(TypeFlags
::HAS_TY_ERR
)
79 fn has_param_types(&self) -> bool
{
80 self.has_type_flags(TypeFlags
::HAS_PARAMS
)
82 fn has_self_ty(&self) -> bool
{
83 self.has_type_flags(TypeFlags
::HAS_SELF
)
85 fn has_infer_types(&self) -> bool
{
86 self.has_type_flags(TypeFlags
::HAS_TY_INFER
)
88 fn needs_infer(&self) -> bool
{
89 self.has_type_flags(TypeFlags
::HAS_TY_INFER
| TypeFlags
::HAS_RE_INFER
)
91 fn needs_subst(&self) -> bool
{
92 self.has_type_flags(TypeFlags
::NEEDS_SUBST
)
94 fn has_closure_types(&self) -> bool
{
95 self.has_type_flags(TypeFlags
::HAS_TY_CLOSURE
)
97 fn has_erasable_regions(&self) -> bool
{
98 self.has_type_flags(TypeFlags
::HAS_RE_EARLY_BOUND
|
99 TypeFlags
::HAS_RE_INFER
|
100 TypeFlags
::HAS_FREE_REGIONS
)
102 /// Indicates whether this value references only 'global'
103 /// types/lifetimes that are the same regardless of what fn we are
104 /// in. This is used for caching. Errs on the side of returning
106 fn is_global(&self) -> bool
{
107 !self.has_type_flags(TypeFlags
::HAS_LOCAL_NAMES
)
111 /// The TypeFolder trait defines the actual *folding*. There is a
112 /// method defined for every foldable type. Each of these has a
113 /// default implementation that does an "identity" fold. Within each
114 /// identity fold, it should invoke `foo.fold_with(self)` to fold each
116 pub trait TypeFolder
<'tcx
> : Sized
{
117 fn tcx
<'a
>(&'a
self) -> &'a TyCtxt
<'tcx
>;
119 fn fold_binder
<T
>(&mut self, t
: &Binder
<T
>) -> Binder
<T
>
120 where T
: TypeFoldable
<'tcx
>
122 t
.super_fold_with(self)
125 fn fold_ty(&mut self, t
: Ty
<'tcx
>) -> Ty
<'tcx
> {
126 t
.super_fold_with(self)
129 fn fold_mt(&mut self, t
: &ty
::TypeAndMut
<'tcx
>) -> ty
::TypeAndMut
<'tcx
> {
130 t
.super_fold_with(self)
133 fn fold_trait_ref(&mut self, t
: &ty
::TraitRef
<'tcx
>) -> ty
::TraitRef
<'tcx
> {
134 t
.super_fold_with(self)
137 fn fold_impl_header(&mut self, imp
: &ty
::ImplHeader
<'tcx
>) -> ty
::ImplHeader
<'tcx
> {
138 imp
.super_fold_with(self)
141 fn fold_substs(&mut self,
142 substs
: &subst
::Substs
<'tcx
>)
143 -> subst
::Substs
<'tcx
> {
144 substs
.super_fold_with(self)
147 fn fold_fn_sig(&mut self,
148 sig
: &ty
::FnSig
<'tcx
>)
150 sig
.super_fold_with(self)
153 fn fold_output(&mut self,
154 output
: &ty
::FnOutput
<'tcx
>)
155 -> ty
::FnOutput
<'tcx
> {
156 output
.super_fold_with(self)
159 fn fold_bare_fn_ty(&mut self,
160 fty
: &ty
::BareFnTy
<'tcx
>)
161 -> ty
::BareFnTy
<'tcx
>
163 fty
.super_fold_with(self)
166 fn fold_closure_ty(&mut self,
167 fty
: &ty
::ClosureTy
<'tcx
>)
168 -> ty
::ClosureTy
<'tcx
> {
169 fty
.super_fold_with(self)
172 fn fold_region(&mut self, r
: ty
::Region
) -> ty
::Region
{
173 r
.super_fold_with(self)
176 fn fold_existential_bounds(&mut self, s
: &ty
::ExistentialBounds
<'tcx
>)
177 -> ty
::ExistentialBounds
<'tcx
> {
178 s
.super_fold_with(self)
181 fn fold_autoref(&mut self, ar
: &adjustment
::AutoRef
<'tcx
>)
182 -> adjustment
::AutoRef
<'tcx
> {
183 ar
.super_fold_with(self)
187 pub trait TypeVisitor
<'tcx
> : Sized
{
188 fn visit_binder
<T
: TypeFoldable
<'tcx
>>(&mut self, t
: &Binder
<T
>) -> bool
{
189 t
.super_visit_with(self)
192 fn visit_ty(&mut self, t
: Ty
<'tcx
>) -> bool
{
193 t
.super_visit_with(self)
196 fn visit_region(&mut self, r
: ty
::Region
) -> bool
{
197 r
.super_visit_with(self)
201 ///////////////////////////////////////////////////////////////////////////
202 // Some sample folders
204 pub struct BottomUpFolder
<'a
, 'tcx
: 'a
, F
> where F
: FnMut(Ty
<'tcx
>) -> Ty
<'tcx
> {
205 pub tcx
: &'a TyCtxt
<'tcx
>,
209 impl<'a
, 'tcx
, F
> TypeFolder
<'tcx
> for BottomUpFolder
<'a
, 'tcx
, F
> where
210 F
: FnMut(Ty
<'tcx
>) -> Ty
<'tcx
>,
212 fn tcx(&self) -> &TyCtxt
<'tcx
> { self.tcx }
214 fn fold_ty(&mut self, ty
: Ty
<'tcx
>) -> Ty
<'tcx
> {
215 let t1
= ty
.super_fold_with(self);
220 ///////////////////////////////////////////////////////////////////////////
223 impl<'tcx
> TyCtxt
<'tcx
> {
224 /// Collects the free and escaping regions in `value` into `region_set`. Returns
225 /// whether any late-bound regions were skipped
226 pub fn collect_regions
<T
>(&self,
228 region_set
: &mut FnvHashSet
<ty
::Region
>)
230 where T
: TypeFoldable
<'tcx
>
232 let mut have_bound_regions
= false;
233 self.fold_regions(value
, &mut have_bound_regions
,
234 |r
, d
| { region_set.insert(r.from_depth(d)); r }
);
238 /// Folds the escaping and free regions in `value` using `f`, and
239 /// sets `skipped_regions` to true if any late-bound region was found
241 pub fn fold_regions
<T
,F
>(&self,
243 skipped_regions
: &mut bool
,
246 where F
: FnMut(ty
::Region
, u32) -> ty
::Region
,
247 T
: TypeFoldable
<'tcx
>,
249 value
.fold_with(&mut RegionFolder
::new(self, skipped_regions
, &mut f
))
253 /// Folds over the substructure of a type, visiting its component
254 /// types and all regions that occur *free* within it.
256 /// That is, `Ty` can contain function or method types that bind
257 /// regions at the call site (`ReLateBound`), and occurrences of
258 /// regions (aka "lifetimes") that are bound within a type are not
259 /// visited by this folder; only regions that occur free will be
260 /// visited by `fld_r`.
262 pub struct RegionFolder
<'a
, 'tcx
: 'a
> {
263 tcx
: &'a TyCtxt
<'tcx
>,
264 skipped_regions
: &'a
mut bool
,
266 fld_r
: &'a
mut (FnMut(ty
::Region
, u32) -> ty
::Region
+ 'a
),
269 impl<'a
, 'tcx
> RegionFolder
<'a
, 'tcx
> {
270 pub fn new
<F
>(tcx
: &'a TyCtxt
<'tcx
>,
271 skipped_regions
: &'a
mut bool
,
272 fld_r
: &'a
mut F
) -> RegionFolder
<'a
, 'tcx
>
273 where F
: FnMut(ty
::Region
, u32) -> ty
::Region
277 skipped_regions
: skipped_regions
,
284 impl<'a
, 'tcx
> TypeFolder
<'tcx
> for RegionFolder
<'a
, 'tcx
>
286 fn tcx(&self) -> &TyCtxt
<'tcx
> { self.tcx }
288 fn fold_binder
<T
: TypeFoldable
<'tcx
>>(&mut self, t
: &ty
::Binder
<T
>) -> ty
::Binder
<T
> {
289 self.current_depth
+= 1;
290 let t
= t
.super_fold_with(self);
291 self.current_depth
-= 1;
295 fn fold_region(&mut self, r
: ty
::Region
) -> ty
::Region
{
297 ty
::ReLateBound(debruijn
, _
) if debruijn
.depth
< self.current_depth
=> {
298 debug
!("RegionFolder.fold_region({:?}) skipped bound region (current depth={})",
299 r
, self.current_depth
);
300 *self.skipped_regions
= true;
304 debug
!("RegionFolder.fold_region({:?}) folding free region (current_depth={})",
305 r
, self.current_depth
);
306 (self.fld_r
)(r
, self.current_depth
)
312 ///////////////////////////////////////////////////////////////////////////
313 // Late-bound region replacer
315 // Replaces the escaping regions in a type.
317 struct RegionReplacer
<'a
, 'tcx
: 'a
> {
318 tcx
: &'a TyCtxt
<'tcx
>,
320 fld_r
: &'a
mut (FnMut(ty
::BoundRegion
) -> ty
::Region
+ 'a
),
321 map
: FnvHashMap
<ty
::BoundRegion
, ty
::Region
>
324 impl<'tcx
> TyCtxt
<'tcx
> {
325 pub fn replace_late_bound_regions
<T
,F
>(&self,
328 -> (T
, FnvHashMap
<ty
::BoundRegion
, ty
::Region
>)
329 where F
: FnMut(ty
::BoundRegion
) -> ty
::Region
,
330 T
: TypeFoldable
<'tcx
>,
332 debug
!("replace_late_bound_regions({:?})", value
);
333 let mut replacer
= RegionReplacer
::new(self, &mut f
);
334 let result
= value
.skip_binder().fold_with(&mut replacer
);
335 (result
, replacer
.map
)
339 /// Replace any late-bound regions bound in `value` with free variants attached to scope-id
341 pub fn liberate_late_bound_regions
<T
>(&self,
342 all_outlive_scope
: region
::CodeExtent
,
345 where T
: TypeFoldable
<'tcx
>
347 self.replace_late_bound_regions(value
, |br
| {
348 ty
::ReFree(ty
::FreeRegion{scope: all_outlive_scope, bound_region: br}
)
352 /// Flattens two binding levels into one. So `for<'a> for<'b> Foo`
353 /// becomes `for<'a,'b> Foo`.
354 pub fn flatten_late_bound_regions
<T
>(&self, bound2_value
: &Binder
<Binder
<T
>>)
356 where T
: TypeFoldable
<'tcx
>
358 let bound0_value
= bound2_value
.skip_binder().skip_binder();
359 let value
= self.fold_regions(bound0_value
, &mut false,
360 |region
, current_depth
| {
362 ty
::ReLateBound(debruijn
, br
) if debruijn
.depth
>= current_depth
=> {
363 // should be true if no escaping regions from bound2_value
364 assert
!(debruijn
.depth
- current_depth
<= 1);
365 ty
::ReLateBound(ty
::DebruijnIndex
::new(current_depth
), br
)
375 pub fn no_late_bound_regions
<T
>(&self, value
: &Binder
<T
>) -> Option
<T
>
376 where T
: TypeFoldable
<'tcx
>
378 if value
.0.has_escaping_regions() {
381 Some(value
.0.clone())
385 /// Replace any late-bound regions bound in `value` with `'static`. Useful in trans but also
386 /// method lookup and a few other places where precise region relationships are not required.
387 pub fn erase_late_bound_regions
<T
>(&self, value
: &Binder
<T
>) -> T
388 where T
: TypeFoldable
<'tcx
>
390 self.replace_late_bound_regions(value
, |_
| ty
::ReStatic
).0
393 /// Rewrite any late-bound regions so that they are anonymous. Region numbers are
394 /// assigned starting at 1 and increasing monotonically in the order traversed
395 /// by the fold operation.
397 /// The chief purpose of this function is to canonicalize regions so that two
398 /// `FnSig`s or `TraitRef`s which are equivalent up to region naming will become
399 /// structurally identical. For example, `for<'a, 'b> fn(&'a isize, &'b isize)` and
400 /// `for<'a, 'b> fn(&'b isize, &'a isize)` will become identical after anonymization.
401 pub fn anonymize_late_bound_regions
<T
>(&self, sig
: &Binder
<T
>) -> Binder
<T
>
402 where T
: TypeFoldable
<'tcx
>,
405 Binder(self.replace_late_bound_regions(sig
, |_
| {
407 ty
::ReLateBound(ty
::DebruijnIndex
::new(1), ty
::BrAnon(counter
))
412 impl<'a
, 'tcx
> RegionReplacer
<'a
, 'tcx
> {
413 fn new
<F
>(tcx
: &'a TyCtxt
<'tcx
>, fld_r
: &'a
mut F
) -> RegionReplacer
<'a
, 'tcx
>
414 where F
: FnMut(ty
::BoundRegion
) -> ty
::Region
425 impl<'a
, 'tcx
> TypeFolder
<'tcx
> for RegionReplacer
<'a
, 'tcx
>
427 fn tcx(&self) -> &TyCtxt
<'tcx
> { self.tcx }
429 fn fold_binder
<T
: TypeFoldable
<'tcx
>>(&mut self, t
: &ty
::Binder
<T
>) -> ty
::Binder
<T
> {
430 self.current_depth
+= 1;
431 let t
= t
.super_fold_with(self);
432 self.current_depth
-= 1;
436 fn fold_ty(&mut self, t
: Ty
<'tcx
>) -> Ty
<'tcx
> {
437 if !t
.has_regions_escaping_depth(self.current_depth
-1) {
441 t
.super_fold_with(self)
444 fn fold_region(&mut self, r
: ty
::Region
) -> ty
::Region
{
446 ty
::ReLateBound(debruijn
, br
) if debruijn
.depth
== self.current_depth
=> {
447 debug
!("RegionReplacer.fold_region({:?}) folding region (current_depth={})",
448 r
, self.current_depth
);
449 let fld_r
= &mut self.fld_r
;
450 let region
= *self.map
.entry(br
).or_insert_with(|| fld_r(br
));
451 if let ty
::ReLateBound(debruijn1
, br
) = region
{
452 // If the callback returns a late-bound region,
453 // that region should always use depth 1. Then we
454 // adjust it to the correct depth.
455 assert_eq
!(debruijn1
.depth
, 1);
456 ty
::ReLateBound(debruijn
, br
)
466 ///////////////////////////////////////////////////////////////////////////
469 impl<'tcx
> TyCtxt
<'tcx
> {
470 /// Returns an equivalent value with all free regions removed (note
471 /// that late-bound regions remain, because they are important for
472 /// subtyping, but they are anonymized and normalized as well)..
473 pub fn erase_regions
<T
>(&self, value
: &T
) -> T
474 where T
: TypeFoldable
<'tcx
>
476 let value1
= value
.fold_with(&mut RegionEraser(self));
477 debug
!("erase_regions({:?}) = {:?}",
481 struct RegionEraser
<'a
, 'tcx
: 'a
>(&'a TyCtxt
<'tcx
>);
483 impl<'a
, 'tcx
> TypeFolder
<'tcx
> for RegionEraser
<'a
, 'tcx
> {
484 fn tcx(&self) -> &TyCtxt
<'tcx
> { self.0 }
486 fn fold_ty(&mut self, ty
: Ty
<'tcx
>) -> Ty
<'tcx
> {
487 match self.tcx().normalized_cache
.borrow().get(&ty
).cloned() {
492 let t_norm
= ty
.super_fold_with(self);
493 self.tcx().normalized_cache
.borrow_mut().insert(ty
, t_norm
);
497 fn fold_binder
<T
>(&mut self, t
: &ty
::Binder
<T
>) -> ty
::Binder
<T
>
498 where T
: TypeFoldable
<'tcx
>
500 let u
= self.tcx().anonymize_late_bound_regions(t
);
501 u
.super_fold_with(self)
504 fn fold_region(&mut self, r
: ty
::Region
) -> ty
::Region
{
505 // because late-bound regions affect subtyping, we can't
506 // erase the bound/free distinction, but we can replace
507 // all free regions with 'static.
509 // Note that we *CAN* replace early-bound regions -- the
510 // type system never "sees" those, they get substituted
511 // away. In trans, they will always be erased to 'static
512 // whenever a substitution occurs.
514 ty
::ReLateBound(..) => r
,
519 fn fold_substs(&mut self,
520 substs
: &subst
::Substs
<'tcx
>)
521 -> subst
::Substs
<'tcx
> {
522 subst
::Substs
{ regions
: substs
.regions
.fold_with(self),
523 types
: substs
.types
.fold_with(self) }
529 ///////////////////////////////////////////////////////////////////////////
532 // Shifts the De Bruijn indices on all escaping bound regions by a
533 // fixed amount. Useful in substitution or when otherwise introducing
534 // a binding level that is not intended to capture the existing bound
535 // regions. See comment on `shift_regions_through_binders` method in
536 // `subst.rs` for more details.
538 pub fn shift_region(region
: ty
::Region
, amount
: u32) -> ty
::Region
{
540 ty
::ReLateBound(debruijn
, br
) => {
541 ty
::ReLateBound(debruijn
.shifted(amount
), br
)
549 pub fn shift_regions
<'tcx
, T
:TypeFoldable
<'tcx
>>(tcx
: &TyCtxt
<'tcx
>,
550 amount
: u32, value
: &T
) -> T
{
551 debug
!("shift_regions(value={:?}, amount={})",
554 value
.fold_with(&mut RegionFolder
::new(tcx
, &mut false, &mut |region
, _current_depth
| {
555 shift_region(region
, amount
)
559 /// An "escaping region" is a bound region whose binder is not part of `t`.
561 /// So, for example, consider a type like the following, which has two binders:
563 /// for<'a> fn(x: for<'b> fn(&'a isize, &'b isize))
564 /// ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ outer scope
565 /// ^~~~~~~~~~~~~~~~~~~~~~~~~~~~ inner scope
567 /// This type has *bound regions* (`'a`, `'b`), but it does not have escaping regions, because the
568 /// binders of both `'a` and `'b` are part of the type itself. However, if we consider the *inner
569 /// fn type*, that type has an escaping region: `'a`.
571 /// Note that what I'm calling an "escaping region" is often just called a "free region". However,
572 /// we already use the term "free region". It refers to the regions that we use to represent bound
573 /// regions on a fn definition while we are typechecking its body.
575 /// To clarify, conceptually there is no particular difference between an "escaping" region and a
576 /// "free" region. However, there is a big difference in practice. Basically, when "entering" a
577 /// binding level, one is generally required to do some sort of processing to a bound region, such
578 /// as replacing it with a fresh/skolemized region, or making an entry in the environment to
579 /// represent the scope to which it is attached, etc. An escaping region represents a bound region
580 /// for which this processing has not yet been done.
581 struct HasEscapingRegionsVisitor
{
585 impl<'tcx
> TypeVisitor
<'tcx
> for HasEscapingRegionsVisitor
{
586 fn visit_binder
<T
: TypeFoldable
<'tcx
>>(&mut self, t
: &Binder
<T
>) -> bool
{
588 let result
= t
.super_visit_with(self);
593 fn visit_ty(&mut self, t
: Ty
<'tcx
>) -> bool
{
594 t
.region_depth
> self.depth
597 fn visit_region(&mut self, r
: ty
::Region
) -> bool
{
598 r
.escapes_depth(self.depth
)
602 struct HasTypeFlagsVisitor
{
603 flags
: ty
::TypeFlags
,
606 impl<'tcx
> TypeVisitor
<'tcx
> for HasTypeFlagsVisitor
{
607 fn visit_ty(&mut self, t
: Ty
) -> bool
{
608 t
.flags
.get().intersects(self.flags
)
611 fn visit_region(&mut self, r
: ty
::Region
) -> bool
{
612 if self.flags
.intersects(ty
::TypeFlags
::HAS_LOCAL_NAMES
) {
613 // does this represent a region that cannot be named
614 // in a global way? used in fulfillment caching.
616 ty
::ReStatic
| ty
::ReEmpty
=> {}
620 if self.flags
.intersects(ty
::TypeFlags
::HAS_RE_INFER
) {
622 ty
::ReVar(_
) | ty
::ReSkolemized(..) => { return true }