on_unimplemented
The tracking issue for this feature is: #29628
The on_unimplemented
feature provides the #[rustc_on_unimplemented]
attribute, which allows trait definitions to add specialized notes to error
messages when an implementation was expected but not found. You can refer
to the trait's generic arguments by name and to the resolved type using
Self
.
For example:
#![feature(on_unimplemented)] #[rustc_on_unimplemented="an iterator over elements of type `{A}` \ cannot be built from a collection of type `{Self}`"] trait MyIterator<A> { fn next(&mut self) -> A; } fn iterate_chars<I: MyIterator<char>>(i: I) { // ... } fn main() { iterate_chars(&[1, 2, 3][..]); }
When the user compiles this, they will see the following;
error[E0277]: the trait bound `&[{integer}]: MyIterator<char>` is not satisfied
--> <anon>:14:5
|
14 | iterate_chars(&[1, 2, 3][..]);
| ^^^^^^^^^^^^^ an iterator over elements of type `char` cannot be built from a collection of type `&[{integer}]`
|
= help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
= note: required by `iterate_chars`
on_unimplemented
also supports advanced filtering for better targeting
of messages, as well as modifying specific parts of the error message. You
target the text of:
- the main error message (
message
) - the label (
label
) - an extra note (
note
)
For example, the following attribute
# #![allow(unused_variables)] #fn main() { #[rustc_on_unimplemented( message="message", label="label", note="note" )] trait MyIterator<A> { fn next(&mut self) -> A; } #}
Would generate the following output:
error[E0277]: message
--> <anon>:14:5
|
14 | iterate_chars(&[1, 2, 3][..]);
| ^^^^^^^^^^^^^ label
|
= note: note
= help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
= note: required by `iterate_chars`
To allow more targeted error messages, it is possible to filter the
application of these fields based on a variety of attributes when using
on
:
crate_local
: whether the code causing the trait bound to not be fulfilled is part of the user's crate. This is used to avoid suggesting code changes that would require modifying a dependency.- Any of the generic arguments that can be substituted in the text can be
referred by name as well for filtering, like
Rhs="i32"
, except forSelf
. _Self
: to filter only on a particular calculated trait resolution, likeSelf="std::iter::Iterator<char>"
. This is needed becauseSelf
is a keyword which cannot appear in attributes.direct
: user-specified rather than derived obligation.from_method
: usable both as boolean (whether the flag is present, likecrate_local
) or matching against a particular method. Currently used fortry
.from_desugaring
: usable both as boolean (whether the flag is present) or matching against a particular desugaring. The desugaring is identified with its variant name in theDesugaringKind
enum.
For example, the Iterator
trait can be annotated in the following way:
# #![allow(unused_variables)] #fn main() { #[rustc_on_unimplemented( on( _Self="&str", note="call `.chars()` or `.as_bytes()` on `{Self}" ), message="`{Self}` is not an iterator", label="`{Self}` is not an iterator", note="maybe try calling `.iter()` or a similar method" )] pub trait Iterator {} #}
Which would produce the following outputs:
error[E0277]: `Foo` is not an iterator
--> src/main.rs:4:16
|
4 | for foo in Foo {}
| ^^^ `Foo` is not an iterator
|
= note: maybe try calling `.iter()` or a similar method
= help: the trait `std::iter::Iterator` is not implemented for `Foo`
= note: required by `std::iter::IntoIterator::into_iter`
error[E0277]: `&str` is not an iterator
--> src/main.rs:5:16
|
5 | for foo in "" {}
| ^^ `&str` is not an iterator
|
= note: call `.chars()` or `.bytes() on `&str`
= help: the trait `std::iter::Iterator` is not implemented for `&str`
= note: required by `std::iter::IntoIterator::into_iter`
If you need to filter on multiple attributes, you can use all
, any
or
not
in the following way:
# #![allow(unused_variables)] #fn main() { #[rustc_on_unimplemented( on( all(_Self="&str", T="std::string::String"), note="you can coerce a `{T}` into a `{Self}` by writing `&*variable`" ) )] pub trait From<T>: Sized { /* ... */ } #}