]> git.proxmox.com Git - rustc.git/blame - src/doc/edition-guide/src/rust-2021/prelude.md
New upstream version 1.55.0+dfsg1
[rustc.git] / src / doc / edition-guide / src / rust-2021 / prelude.md
CommitLineData
17df50a5
XL
1# Additions to the prelude
2
3## Summary
4
136023e0
XL
5- The `TryInto`, `TryFrom` and `FromIterator` traits are now part of the prelude.
6- This might make calls to trait methods ambiguous which could make some code fail to compile.
7
17df50a5
XL
8## Details
9
10The [prelude of the standard library](https://doc.rust-lang.org/stable/std/prelude/index.html)
11is the module containing everything that is automatically imported in every module.
12It contains commonly used items such as `Option`, `Vec`, `drop`, and `Clone`.
13
14The Rust compiler prioritizes any manually imported items over those
15from the prelude, to make sure additions to the prelude will not break any existing code.
16For example, if you have a crate or module called `example` containing a `pub struct Option;`,
17then `use example::*;` will make `Option` unambiguously refer to the one from `example`;
18not the one from the standard library.
19
136023e0
XL
20However, adding a _trait_ to the prelude can break existing code in a subtle way.
21For example, a call to `x.try_into()` which comes from a `MyTryInto` trait might fail
22to compile if `std`'s `TryInto` is also imported, because the call to `try_into` is now
23ambiguous and could come from either trait. This is the reason we haven't added `TryInto`
24to the prelude yet, since there is a lot of code that would break this way.
17df50a5
XL
25
26As a solution, Rust 2021 will use a new prelude.
27It's identical to the current one, except for three new additions:
28
29- [`std::convert::TryInto`](https://doc.rust-lang.org/stable/std/convert/trait.TryInto.html)
30- [`std::convert::TryFrom`](https://doc.rust-lang.org/stable/std/convert/trait.TryFrom.html)
31- [`std::iter::FromIterator`](https://doc.rust-lang.org/stable/std/iter/trait.FromIterator.html)
32
136023e0
XL
33The tracking issue [can be found here](https://github.com/rust-lang/rust/issues/85684).
34
35## Migration to Rust 2021
36
37As a part of the 2021 edition a migration lint, `rust_2021_prelude_collisions`, has been added in order to aid in automatic migration of Rust 2018 codebases to Rust 2021.
38
39In order to have `rustfix` migrate your code to be Rust 2021 Edition compatible, run:
40
41```sh
42cargo fix --edition
43```
44
45The lint detects cases where functions or methods are called that have the same name as the methods defined in one of the new prelude traits. In some cases, it may rewrite your calls in various ways to ensure that you continue to call the same function you did before.
46
47If you'd like to migrate your code manually or better understand what `rustfix` is doing, below we've outlined the situations where a migration is needed along with a counter example of when it's not needed.
48
49### Migration needed
50
51#### Conflicting trait methods
52
53When two traits that are in scope have the same method name, it is ambiguous which trait method should be used. For example:
54
55```rust
56trait MyTrait<A> {
57 // This name is the same as the `from_iter` method on the `FromIterator` trait from `std`.
58 fn from_iter(x: Option<A>);
59}
60
61impl<T> MyTrait<()> for Vec<T> {
62 fn from_iter(_: Option<()>) {}
63}
64
65fn main() {
66 // Vec<T> implements both `std::iter::FromIterator` and `MyTrait`
67 // If both traits are in scope (as would be the case in Rust 2021),
68 // then it becomes ambiguous which `from_iter` method to call
69 <Vec<i32>>::from_iter(None);
70}
71```
72
73We can fix this by using fully qualified syntax:
74
75```rust,ignore
76fn main() {
77 // Now it is clear which trait method we're referring to
78 <Vec<i32> as MyTrait<i32>>::from_iter(None);
79}
80```
81
82#### Inherent methods on `dyn Trait` objects
83
84Some users invoke methods on a `dyn Trait` value where the method name overlaps with a new prelude trait:
85
86```rust
87mod submodule {
88 pub trait MyTrait {
89 // This has the same name as `TryInto::try_into`
90 fn try_into(&self) -> Result<u32, ()>;
91 }
92}
93
94// `MyTrait` isn't in scope here and can only be referred to through the path `submodule::MyTrait`
95fn bar(f: Box<dyn submodule::MyTrait>) {
96 // If `std::convert::TryInto` is in scope (as would be the case in Rust 2021),
97 // then it becomes ambiguous which `try_into` method to call
98 f.try_into();
99}
100```
101
102Unlike with static dispatch methods, calling a trait method on a trait object does not require that the trait be in scope. The code above works
103as long as there is no trait in scope with a conflicting method name. When the `TryInto` trait is in scope (which is the case in Rust 2021),
104this causes an ambiguity. Should the call be to `MyTrait::try_into` or `std::convert::TryInto::try_into`?
105
106In these cases, we can fix this by adding an additional dereferences or otherwise clarify the type of the method receiver. This ensures that
107the `dyn Trait` method is chosen, versus the methods from the prelude trait. For example, turning `f.try_into()` above into `(&*f).try_into()`
108ensures that we're calling `try_into` on the `dyn MyTrait` which can only refer to the `MyTrait::try_into` method.
109
110### No migration needed
111
112#### Inherent methods
113
114Many types define their own inherent methods with the same name as a trait method. For instance, below the struct `MyStruct` implements `from_iter` which shares the same name with the method from the trait `FromIterator` found in the standard library:
115
116```rust
117use std::iter::IntoIterator;
118
119struct MyStruct {
120 data: Vec<u32>
121}
122
123impl MyStruct {
124 // This has the same name as `std::iter::FromIterator::from_iter`
125 fn from_iter(iter: impl IntoIterator<Item = u32>) -> Self {
126 Self {
127 data: iter.into_iter().collect()
128 }
129 }
130}
131
132impl std::iter::FromIterator<u32> for MyStruct {
133 fn from_iter<I: IntoIterator<Item = u32>>(iter: I) -> Self {
134 Self {
135 data: iter.into_iter().collect()
136 }
137 }
138}
139```
140
141Inherent methods always take precedent over trait methods so there's no need for any migration.
142
143### Implementation Reference
144
145The lint needs to take a couple of factors into account when determining whether or not introducing 2021 Edition to a codebase will cause a name resolution collision (thus breaking the code after changing edition). These factors include:
146
147- Is the call a [fully-qualified call] or does it use [dot-call method syntax]?
148 - This will affect how the name is resolved due to auto-reference and auto-dereferencing on method call syntax. Manually dereferencing/referencing will allow specifying priority in the case of dot-call method syntax, while fully-qualified call requires specification of the type and the trait name in the method path (e.g. `<Type as Trait>::method`)
149- Is this an [inherent method] or [a trait method]?
150 - Inherent methods that take `self` will take priority over `TryInto::try_into` as inherent methods take priority over trait methods, but inherent methods that take `&self` or `&mut self` won't take priority due to requiring a auto-reference (while `TryInto::try_into` does not, as it takes `self`)
151- Is the origin of this method from `core`/`std`? (As the traits can't have a collision with themselves)
152- Does the given type implement the trait it could have a collision against?
153- Is the method being called via dynamic dispatch? (i.e. is the `self` type `dyn Trait`)
154 - If so, trait imports don't affect resolution, and no migration lint needs to occur
155
156[fully-qualified call]: https://doc.rust-lang.org/reference/expressions/call-expr.html#disambiguating-function-calls
157[dot-call method syntax]: https://doc.rust-lang.org/reference/expressions/method-call-expr.html
158[inherent method]: https://doc.rust-lang.org/reference/items/implementations.html#inherent-implementations
159[a trait method]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementations