Skip to content

Commit 4283e29

Browse files
m-ou-sem-ou-se
authored
Merge pull request #3129 from m-ou-se/prelude-2021-traits
Merge RFC 3114
2 parents 5869fb2 + 058c2f3 commit 4283e29

File tree

1 file changed

+132
-0
lines changed

1 file changed

+132
-0
lines changed

‎text/3114-prelude-2021.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
- Feature Name: `prelude_2021`
2+
- Start Date: 2021-02-16
3+
- RFC PR: [rust-lang/rfcs#3114](https://github.com/rust-lang/rfcs/pull/3114)
4+
- Rust Issue: [rust-lang/rust#85684](https://github.com/rust-lang/rust/issues/85684)
5+
6+
# Summary
7+
[summary]: #summary
8+
9+
A new prelude for the 2021 edition, featuring several extra traits.
10+
11+
# Motivation
12+
[motivation]: #motivation
13+
14+
While types and free functions can be added to the prelude independent of edition boundaries, the same is not true for traits. Adding a trait to the prelude can cause compatibility issues because calls to methods named the same as methods of the newly in scope traits can become ambiguous. While such changes are technically
15+
[minor][minor-change], such that some backwards compatibility breaks are potentially allowed, the possibility of relatively widespread breakage makes it less attractive to do so without an edition opt-in.
16+
17+
The expected outcome is to make the newly added traits more accessible to users, potentially stimulating their use compared to alternatives.
18+
19+
[minor-change]: https://rust-lang.github.io/rfcs/1105-api-evolution.html#minor-change-adding-a-defaulted-item
20+
21+
# Guide-level explanation
22+
[guide-level-explanation]: #guide-level-explanation
23+
24+
The compiler currently brings all items from `std::prelude::v1` into scope for each module (for code using `std`). Crates that declare usage of the 2021 edition will instead get items from `std::prelude::rust_2021` imported into scope. With the implementation of this RFC, we will add `rust_2015` and `rust_2018` modules in `std::prelude`, and a crate configuring a particular edition will get the prelude appropriate for its edition. The `v1` module will stick around for compatibility reasons, although it might be deprecated in the future.
25+
26+
The `core` prelude will parallel the `std` prelude, containing the same structure and the same items as far as they are available in `core`.
27+
28+
This RFC proposes to add the following traits to `std::prelude::rust_2021`, but not `std::prelude::v1`:
29+
30+
- `TryFrom`/`TryInto`
31+
- `FromIterator`
32+
33+
Except for newly added traits, the `v1` and `rust_2021` preludes should be kept in sync. Items that are added to the `rust_2021` prelude should also be added to the `v1` prelude if there is negligible risk for compatibility. On the other hand, newer edition preludes may decide not to include items from an older edition's prelude.
34+
35+
# Reference-level explanation
36+
[reference-level-explanation]: #reference-level-explanation
37+
38+
The new prelude will be named after the edition that introduces it to make the link to the edition more obvious. Each edition will have a separate prelude, whether the contents are actually different or not.
39+
40+
## Migration Lint
41+
42+
As for all edition changes, we will implement a migration lint to detect cases where code would break in the new edition. It includes a MachineApplicable suggestion for an alternative that will work in both the current and next edition.
43+
44+
The migration lint will be implemented as follows:
45+
46+
* Find method calls matching the name of one of the newly added traits' methods.
47+
This can be done either by hardcoding these method names or by setting up some
48+
kind of registry through the use of an attribute on the relevant traits.
49+
* After method resolution, if:
50+
* The method matches one of the newly added methods' names, and
51+
* The originating trait is not from `core` or `std` (and/or does not
52+
match the originating trait), and
53+
* The originating trait is also implemented for the receiver's type,
54+
* Suggest a rewrite to disambiguating syntax (such as `foo.try_into()` to `TryInto::try_into(foo)`). If necessary, additional levels of (de)referencing
55+
might be needed to match the implementing type of the target trait.
56+
57+
Currently, diagnostics for trait methods that are not in scope suggest importing the originating trait. For traits that have become part of the prelude in a newer edition, the diagnostics should be updated such that they suggest upgrading to the latest edition as an alternative to importing the relevant trait.
58+
59+
# Drawbacks
60+
[drawbacks]: #drawbacks
61+
62+
Making the prelude contents edition-dependent makes the difference between different editions larger, and could thus increase confusion especially in the early phase when older editions and newer ones are used in parallel.
63+
64+
Adding more traits to the prelude makes methods from other traits using the same names as prelude traits harder to access, requiring calls to explicitly disambiguate (`TryFrom::try_from(foo)`).
65+
66+
# Rationale and alternatives
67+
[rationale-and-alternatives]: #rationale-and-alternatives
68+
69+
## `TryFrom`/`TryInto`
70+
71+
The `TryFrom`/`TryInto` traits could not be added to the prelude without an edition boundary. This was [tried](https://github.com/rust-lang/rust/pull/49305) around the time of the 2018 edition, but failed due to breaking substantial parts of the ecosystem. However, `TryFrom`/`TryInto` offer a generic conversion mechanism that is more robust than `as` because the conversions are explicitly fallible. Their usage is more widely applicable than the `From`/`Into` traits because they account for fallibility of the conversions.
72+
73+
Without doing this, the `TryFrom`/`TryInto` traits remain less accessible than the infallible `From`/`Into` conversion traits, providing a disincentive to implement/use fallible conversions even where conversion operations are intrinsically fallible.
74+
75+
## `FromIterator`
76+
77+
The documentation for `FromIterator`'s `from_iter()` method currently reads:
78+
79+
> `FromIterator::from_iter()` is rarely called explicitly, and is instead used through `Iterator::collect()` method. See `Iterator::collect()`'s documentation for more examples.
80+
81+
However, it is reasonably common that type inferencing fails to infer the full type of the target type, in which case an explicit type annotation or turbofishing is needed (such as `iter.collect::<Vec<_, _>>()` -- the type of the iterator item is available, so wildcards can be used for this). In these cases, `Vec::from_iter(iter)` can be a more concise and readable way to spell this, which would be easier if the trait was in scope.
82+
83+
## Other traits that have been suggested for inclusion
84+
85+
Other traits that have been suggested as prelude candidates:
86+
87+
- `std::ops::Not`: for chaining purposes, it is sometimes useful to have an trailing `.not()` call rather than the prefix `!` operator. Therefore, [it has been suggested](https://internals.rust-lang.org/t/pre-rfc-adding-bool-not-method/13935) that the `Not` trait which brings that method in scope could be added to the prelude. This RFC author feels this use case is better served by adding an inherent impl to `bool`, since that serves the majority of the same use case with less complexity.
88+
- `std::fmt::Display`: users of this trait generally don't need to import it because the `ToString` trait which relies on the `Display` implementation is already in the prelude. Implementers of the `Display` trait however need several other items from `std::fmt` to do so; therefore, just importing `Display` into the prelude does not help much.
89+
- `std::fmt::Debug`: similar to `Display`, although there's no `to_debug()`. However, usage will usually go through `dbg!()` or the formatting mechanism (as a `{:?}` format string).
90+
- `std::future::Future`: `Future`'s `poll()` method is usually not called directly, but most often used via `async`/`await`, therefore including `Future` in the prelude does not seem as useful.
91+
- `std::error::Error`: while this is commonly implemented, calling its methods directly does not seem to be common enough that adding this is as useful.
92+
93+
(See [references](#references) below.)
94+
95+
# Prior art
96+
[prior-art]: #prior-art
97+
98+
Python currently has [~70 functions and types](https://docs.python.org/3/library/functions.html) in `__builtins__` (not counting exception types and some interpreter internals).
99+
100+
`std::prelude::v1` currently contains 5 types, 26 traits, 4 variants, 22 macros and 1 free function (not including primitive types like bool, char, integers, floating points and slices).
101+
102+
# Unresolved questions
103+
[unresolved-questions]: #unresolved-questions
104+
105+
* Should there be compatibility lints warning about methods named the same as proposed prelude edition trait methods?
106+
* How do per-prelude editions affect macro hygiene/resolution?
107+
108+
# Future possibilities
109+
[future-possibilities]: #future-possibilities
110+
111+
Future editions could add more items and/or remove some.
112+
113+
# Previous discussions
114+
[references]: #references
115+
116+
* [Rust Edition 2021](https://hackmd.io/3eG6OZWHRbSMxoRxzwNhGQ?view#-Prelude-changes)
117+
* [Zulip: Prelude 2021](https://rust-lang.zulipchat.com/#narrow/stream/268952-edition/topic/Prelude.202021)
118+
* [Zulip: T-lang asking T-libs for per-edition preludes coordination](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/T-lang.20asking.20T-libs.20for.20per-edition.20preludes.20coordination)
119+
* [GitHub: MCP: per-edition preludes](https://github.com/rust-lang/lang-team/issues/44)
120+
* [GitHub: Tracking issue for vNext edition prelude](https://github.com/rust-lang/rust/issues/65512)
121+
* [GitHub: Tracking issue for the 2018 edition’s prelude](https://github.com/rust-lang/rust/issues/51418)
122+
* [IRLO: Add `std::mem::{swap, replace, take}` to the prelude](https://internals.rust-lang.org/t/add-std-swap-replace-take-to-the-prelude/14035)
123+
* [IRLO: Propose additions to std::prelude](https://internals.rust-lang.org/t/propose-additions-to-std-prelude/7189)
124+
* [IRLO: `std::prelude::v2` with `TryFrom`/`TryInto` on edition 2021?](https://internals.rust-lang.org/t/std-v2-with-tryfrom-tryinto-on-edition-2021/12157)
125+
* [IRLO: Should the Future trait be part of the prelude](https://internals.rust-lang.org/t/should-the-future-trait-be-part-of-the-prelude/10669)
126+
* [IRLO: Random Idea: A new prelude for Rust 2018?](https://internals.rust-lang.org/t/random-idea-a-new-prelude-for-rust-2018/7158)
127+
* [IRLO: [pre-RFC] Adding `bool::not()` method](https://internals.rust-lang.org/t/pre-rfc-adding-bool-not-method/13935)
128+
* [IRLO: Pre-pre-RFC: syntactic sugar for `Default::default()`](https://internals.rust-lang.org/t/pre-pre-rfc-syntactic-sugar-for-default-default/13234/10)
129+
* [IRLO: Am I the only one confused by `a.min(b)` and `a.max(b)`?](https://internals.rust-lang.org/t/am-i-the-only-one-confused-by-a-min-b-and-a-max-b/13252)
130+
* [IRLO: The is_not_empty() method as more clearly alternative for !is_empty()](https://internals.rust-lang.org/t/the-is-not-empty-method-as-more-clearly-alternative-for-is-empty/10612)
131+
* [IRLO: Pre-RFC: Add FromIterator to the prelude](https://internals.rust-lang.org/t/pre-rfc-add-fromiterator-to-the-prelude/4324)
132+
* [IRLO: I analysed 5000 crates to find the most common standard library imports](https://internals.rust-lang.org/t/i-analysed-5000-crates-to-find-the-most-common-standard-library-imports/12218)

0 commit comments

Comments
 (0)