Add capturing and precise capturing rules The Reference didn't include any description of capturing or capturing behavior for `impl Trait` opaque types. Let's describe briefly what capturing is and what the currently-stable automatic capturing rules are. Then let's describe the syntax and behavior of RFC 3617 precise capturing.
diff --git a/src/names/scopes.md b/src/names/scopes.md index 58ee99b..55ef159 100644 --- a/src/names/scopes.md +++ b/src/names/scopes.md
@@ -184,7 +184,7 @@ # // The `impl Trait2` here is not allowed to refer to 'b but it is allowed to // refer to 'a. -fn foo<'a>() -> impl for<'b> Trait1<Item = impl Trait2<'a>> { +fn foo<'a>() -> impl for<'b> Trait1<Item = impl Trait2<'a> + use<'a>> { // ... # Example }
diff --git a/src/trait-bounds.md b/src/trait-bounds.md index 96a8f8e..019a2f7 100644 --- a/src/trait-bounds.md +++ b/src/trait-bounds.md
@@ -5,7 +5,7 @@ > _TypeParamBound_ ( `+` _TypeParamBound_ )<sup>\*</sup> `+`<sup>?</sup> > > _TypeParamBound_ :\ -> _Lifetime_ | _TraitBound_ +> _Lifetime_ | _TraitBound_ | _UseBound_ > > _TraitBound_ :\ > `?`<sup>?</sup> @@ -19,6 +19,21 @@ > _Lifetime_ :\ > [LIFETIME_OR_LABEL]\ > | `'static` +> +> _UseBound_ :\ +> `use` _UseBoundGenericArgs_ +> +> _UseBoundGenericArgs_ :\ +> `<` `>` \ +> | `<` \ +> ( _UseBoundGenericArg_ `,`)<sup>\*</sup> \ +> _UseBoundGenericArg_ `,`<sup>?</sup> \ +> `>` +> +> _UseBoundGenericArg_ :\ +> _Lifetime_ \ +> | [IDENTIFIER][] \ +> | `Self` [Trait] and lifetime bounds provide a way for [generic items][generic] to restrict which types and lifetimes are used as their parameters. Bounds can be @@ -227,7 +242,11 @@ impl<'a, T> Trait<'a, T> for &'a T {} ``` +## Use bounds +Certain bounds lists may include a `use<..>` bound to control which generic parameters are captured by the `impl Trait` [abstract return type]. See [precise capturing] for more details. + +[IDENTIFIER]: identifiers.html [LIFETIME_OR_LABEL]: tokens.md#lifetimes-and-loop-labels [_GenericParams_]: items/generics.md [_TypePath_]: paths.md#paths-in-types @@ -235,12 +254,14 @@ [`Copy`]: special-types-and-traits.md#copy [`Sized`]: special-types-and-traits.md#sized +[abstract return type]: types/impl-trait.md#abstract-return-types [arrays]: types/array.md [associated types]: items/associated-items.md#associated-types [hrtb-scopes]: names/scopes.md#higher-ranked-trait-bound-scopes [supertraits]: items/traits.md#supertraits [generic]: items/generics.md [higher-ranked lifetimes]: #higher-ranked-trait-bounds +[precise capturing]: types/impl-trait.md#precise-capturing [slice]: types/slice.md [Trait]: items/traits.md#trait-bounds [trait object]: types/trait-object.md
diff --git a/src/types/impl-trait.md b/src/types/impl-trait.md index 0269098..7e99949 100644 --- a/src/types/impl-trait.md +++ b/src/types/impl-trait.md
@@ -91,7 +91,33 @@ Every `impl Trait` in the return type of an associated function in a trait is desugared to an anonymous associated type. The return type that appears in the implementation's function signature is used to determine the value of the associated type. -### Differences between generics and `impl Trait` in return position +## Capturing + +Behind each return-position `impl Trait` abstract type is some hidden concrete type. For this concrete type to use a generic parameter, that generic parameter must be *captured* by the abstract type. + +## Automatic capturing + +Return-position `impl Trait` abstract types automatically capture certain of the in-scope generic parameters. Everywhere, these automatically capture all in-scope type and const generic parameters. + +On items of trait impls and trait definitions, these types additionally automatically capture all in-scope generic lifetime parameters, including higher-ranked ones. On free functions and on associated functions and methods of inherent impls, only the generic lifetime parameters that appear in the bounds of abstract return type are captured. + +## Precise capturing + +The set of generic parameters captured by a return-position `impl Trait` abstract type may be explicitly controlled with a [`use<..>` bound]. If present, only the generic parameters listed in the `use<..>` bound will be captured. E.g.: + +```rust +fn capture<'a, 'b, T>(x: &'a (), y: T) -> impl Sized + use<'a, T> { + // ~~~~~~~~~~~~~~~~~~~~~~~ + // Captures `'a` and `T` only. + (x, y) +} +``` + +Currently, only one `use<..>` bound may be present in a bounds list, such bounds are not allowed in the signature of items of a trait definition, all in-scope type and const generic parameters must be included, and all lifetime parameters that appear in other bounds of the abstract type must be included. Within the `use<..>` bound, any lifetime parameters present must appear before all type and const generic parameters, and the elided lifetime (`'_`) may be present if it is otherwise allowed to appear within the `impl Trait` return type. + +Because all in-scope type parameters must be included by name, a `use<..>` bound may not be used in the signature of items that use argument-position `impl Trait`, as those items have anonymous type parameters in scope. + +## Differences between generics and `impl Trait` in return position In argument position, `impl Trait` is very similar in semantics to a generic type parameter. However, there are significant differences between the two in return position. @@ -127,9 +153,10 @@ `impl Trait` can only appear as a parameter or return type of a non-`extern` function. It cannot be the type of a `let` binding, field type, or appear inside a type alias. -[closures]: closure.md [_GenericArgs_]: ../paths.md#paths-in-expressions [_GenericParams_]: ../items/generics.md [_TraitBound_]: ../trait-bounds.md -[trait object]: trait-object.md [_TypeParamBounds_]: ../trait-bounds.md +[`use<..>` bound]: ../trait-bounds.md#use-bounds +[closures]: closure.md +[trait object]: trait-object.md