Skip to content

Commit 731db83

Browse files
illicitonionillicitonion
committed
Primitive enum conversion reform
This RFC proposes making it easier to use `From`, `Into`, and potentially `TryFrom` for conversions between enums with primitive representations, and their associated primitives. It optionally also proposes removing or restricting `as` conversion between these types. [Rendered](https://github.com/illicitonion/rfcs/blob/enum-as-to-into/text/0000-enum-as-to-into.md)
1 parent e45cb5f commit 731db83

File tree

1 file changed

+270
-0
lines changed

1 file changed

+270
-0
lines changed

‎text/3040-enum-as-to-into.md

+270
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
- Feature Name: `enum_as_to_into`
2+
- Start Date: 2020-12-18
3+
- RFC PR: [rust-lang/rfcs#3040](https://github.com/rust-lang/rfcs/pull/3040)
4+
- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
5+
6+
# Summary
7+
[summary]: #summary
8+
9+
To improve correctness and predictibility, deprecate converting primitive-repr enums to arbitrary integer primitives using `as`, and instead require that they be converted using `From`/`Into`. Make it trivial to do so without external crates.
10+
11+
This RFC contains multiple incremental steps to making conversions from enums more safe. It proposes that we implement them all, but we could also choose any reasonable subset.
12+
13+
# Motivation
14+
[motivation]: #motivation
15+
16+
## Conversions
17+
18+
Currently, Rust has two main forms of infallible conversion:
19+
* Primitives can be [cast using the `as` keyword](https://doc.rust-lang.org/stable/rust-by-example/types/cast.html). This may silently truncate when going from a larger type to a smaller one, e.g.
20+
```rust
21+
fn main() {
22+
let more_bits: u16 = u16::MAX;
23+
let fewer_bits: u8 = more_bits as u8;
24+
assert_eq!(fewer_bits, 255_u8);
25+
}
26+
```
27+
* Both primitives and non-primitives can be converted using an implementation of the [`From`](https://doc.rust-lang.org/std/convert/trait.From.html) and [`Into`](https://doc.rust-lang.org/std/convert/trait.Into.html) traits. e.g.
28+
```rust
29+
fn main() {
30+
let fewer_bits: u8 = u8::MAX;
31+
32+
let more_bits_into: u16 = fewer_bits.into();
33+
assert_eq!(more_bits_into, 255_u16);
34+
35+
let more_bits_from: u16 = u16::from(fewer_bits);
36+
assert_eq!(more_bits_from, 255_u16);
37+
}
38+
```
39+
40+
`as` casts can be assumed to be trivially cheap, whereas `From`/`Into` casts may be arbitrarily expensive.
41+
42+
## Enums
43+
44+
There are several different styles of [enum](https://doc.rust-lang.org/reference/items/enumerations.html) in Rust. This RFC only considers enums which use a [primitive representation](https://doc.rust-lang.org/reference/type-layout.html#primitive-representations). These enums, though represented as primitive number types, are distinct from them.
45+
46+
Enums currently support being cast to any numeric primitive type using `as`, e.g.
47+
```rust
48+
#[repr(u16)]
49+
enum Number {
50+
Zero,
51+
One,
52+
}
53+
54+
fn main() {
55+
let number_u8 = Number::Zero as u8;
56+
let number_u16 = Number::Zero as u16;
57+
let number_u32 = Number::Zero as u32;
58+
}
59+
```
60+
61+
As with all cases of integer primtive casts, this may silently truncate.
62+
63+
## Correctness issue
64+
65+
This silent truncation causes potential correctness issues. For example, if an enum changes its repr from a smaller type to a larger one, casts which used to be non-truncating may silently become truncating, with not even a warning raised.
66+
67+
There should be a way to convert an enum to its underlying representation without risk of truncation. Once it is converted to a primitive, it could then be cast to another primitive using `as`. But an enum itself should not be considered as a primitive, even if it happens to be backed by one, in much the same way that a newtype wrapping a primitive is not considered a primitive.
68+
69+
The natural candidate for this is an `Into` implementation, as is used for other types (and newtypes). There are [several crates](https://github.com/rust-lang/rfcs/issues/2783#issuecomment-679147876) which provide these implementations, but these require being aware of the potential problem, and taking non-trivial action to side-step it (finding and taking on a new dependency, and potentially significantly increasing compile times). Instead, we should make it trivial to derive an `Into` implementation for a primitive-repr enum in `core`/`std`, and phase out support for casting enums to primitives with `as`. The obvious, and easiest, option should be the correct option.
70+
71+
# Guide-level explanation
72+
[guide-level-explanation]: #guide-level-explanation
73+
74+
As this RFC proposes using existing, well-known features, little teaching is required. We will introduce the feature to users in two ways: Updates to documentation, and lints which may be upgraded to compile errors.
75+
76+
## Documentation updates
77+
78+
We will update [the enum documentation](https://doc.rust-lang.org/reference/items/enumerations.html#custom-discriminant-values-for-fieldless-enumerations). Initially, it will be updated the text along the lines of:
79+
80+
```diff
81+
--- a/src/items/enumerations.md
82+
+++ b/src/items/enumerations.md
83+
@@ -66,8 +66,18 @@ opaque reference to this discriminant can be obtained with the
84+
If there is no data attached to *any* of the variants of an enumeration,
85+
then the discriminant can be directly chosen and accessed.
86+
87+
-These enumerations can be cast to integer types with the `as` operator by a
88+
-[numeric cast]. The enumeration can optionally specify which integer each
89+
+If you wish to convert these enumerations to integer types, it is recommended
90+
+that you implement
91+
+[the `Into` trait](https://doc.rust-lang.org/std/convert/trait.Into.html) for
92+
+them. This can be done easily with `#[derive(Into)]`, supplied by the standard
93+
+library.
94+
+
95+
+For legacy reasons, these enumerations can also be cast to integer types with
96+
+the `as` operator by a [numeric cast], but this is not recommended as it can
97+
+have surprising and unsafe results, and may cease to be supported in a
98+
+future version of Rust.
99+
+
100+
+The enumeration can optionally specify which integer each
101+
discriminant gets by following the variant name with `=` followed by a [constant
102+
expression]. If the first variant in the declaration is unspecified, then it is
103+
set to zero. For every other unspecified discriminant, it is set to one higher
104+
```
105+
106+
In the future, if support is removed for `as` casts, the text may be further updated.
107+
108+
## Lints
109+
110+
Three new lints will be introduced to the language. They will start at `warn` level, and could independently be promoted to `error` level, or full compile errors:
111+
112+
### Likely incorrect casts
113+
114+
For casts where the value being cast is an enum, and the type being cast to is smaller than the enum's repr, a warning will be issued:
115+
116+
```rust
117+
#[repr(u16)]
118+
enum Number {
119+
Zero,
120+
One,
121+
}
122+
123+
fn main() {
124+
let bad = Number::Zero as u8;
125+
}
126+
```
127+
128+
```
129+
warning: unsafe cast
130+
--> src/main.rs:8:9
131+
|
132+
8 | let bad = Number::Zero as u8;
133+
| ^^^ This cast may truncate the value of `bad`, as it is represented by a `u16` which may not fit in a `u8`.
134+
|
135+
= note: `#[warn(enum_truncating_cast)]` on by default
136+
```
137+
138+
If `TryInto<u8>` or `TryFrom` is implemented for the enum, the lint may also suggest calling one of those traits:
139+
```
140+
Consider using `u8::try_from(Number::Zero)`
141+
```
142+
143+
If `Into<u16>` or `From` is implemented for the enum, the lint may also suggest calling it first:
144+
```
145+
Consider using `u16::from(Number::Zero) as u8` to make clear that this possible truncation is intended.
146+
```
147+
148+
If none of the above traits are implemented for the enum, the lint may suggest implementing them.
149+
150+
### Safe casts where Into is implemented
151+
152+
For casts where the value being cast is an enum, the type being cast to is the enum's repr, and `Into`/`From` _is_ implemented between the types, a rustfix-able warning will be issued:
153+
154+
```rust
155+
#[derive(Into)]
156+
#[repr(u16)]
157+
enum Number {
158+
Zero,
159+
One,
160+
}
161+
162+
fn main() {
163+
let ok = Number::Zero as u16;
164+
}
165+
```
166+
167+
```
168+
warning: cast used where From::from is preferred
169+
--> src/main.rs:9:9
170+
|
171+
9 | let ok = Number::Zero as u16;
172+
| ^^ Prefer to use `From` rather than `as` when casting enums. `as` may silently change in behavior if the enum's repr changes, but `From` provides compile-time safety.
173+
|
174+
= note: `#[warn(enum_prefer_from_over_as)]` on by default
175+
176+
Instead use `let ok = u16::from(Number::Zero);`
177+
```
178+
179+
In the case that the type being cast to is larger than the enum's repr, a nested call could be suggested:
180+
181+
```rust
182+
let ok = u64::from(u16::from(Number::Zero));
183+
```
184+
185+
### Safe casts where Into is not implemented
186+
187+
Like with the previous lint, but with a suggestion to implement `Into` (noting that it can be derived), and without the rustfix suggestion (because it would require updating both the definition site and call site).
188+
189+
# Reference-level explanation
190+
[reference-level-explanation]: #reference-level-explanation
191+
192+
We would implement this in several pieces:
193+
194+
## Derive macro for From/Into
195+
196+
`Into` would become a derivable macro, only for primitive-repr'd enums, in `core`.
197+
198+
This would be slightly unusual for a derive macro, as it would actualy derive `impl From<EnumType> for repr_type`, which in turn would provide `impl Into<repr_type> for EnumType`, but `#[derive(Into)]` reads much better on the definition site. It is also unusual for a derive macro in that it has an implicit type parameter, but this seems reasonable as primitive enums have natural types to convert to.
199+
200+
`Into` would not be derivable for any other type.
201+
202+
A sample implementation can be found [here](https://github.com/illicitonion/rust/tree/enum-into-derive-macro).
203+
204+
## Lints
205+
206+
The lints need only type information in very clear situations only around the `as` operator, and should not require noteworthy changes to the compiler. They could potentially also live in Clippy, were that preferred.
207+
208+
Eventually, we would remove support for `as` casts for enums, by moving support from the `as` implementation into the derive macro's generated code.
209+
210+
## Optional: Derive macro for TryFrom/Into
211+
212+
Though not directly related to this proposal, it would make some sense to allow a derive macro for a `TryFrom` implementation to go from a primitive to an enum, which would use [`std::num::TryFromIntError`](https://doc.rust-lang.org/std/num/struct.TryFromIntError.html) as its associated error type.
213+
214+
# Drawbacks
215+
[drawbacks]: #drawbacks
216+
217+
This causes churn in the language. Existing code will need to be updated, and dependees will need to rely on `Into` impls being added to their dependencies before they can migrate.
218+
219+
This also expands `core` and `std`, and introduces a slightly weird corner of `Derive`s whereby they have implicit associated types.
220+
221+
`as` casts also offer some properties that some users may find useful, which may lean towards leaving these lints as warnings rather than promoting them to errors by default. These are:
222+
1. `From` and `Into` are not currently usable in const contexts, whereas `as` is. [RFC 2632](https://github.com/rust-lang/rfcs/pull/2632) aims to solve this.
223+
2. `as` is guaranteed to be a cheap operation, whereas `Into` may be arbitrarily expensive, though it is cheap in this instance.
224+
225+
# Rationale and alternatives
226+
[rationale-and-alternatives]: #rationale-and-alternatives
227+
228+
## Alternatives considered
229+
230+
### Leaving the derive macros in external crates
231+
232+
Leaving the derive macros in external crates is worse because it makes the more correct thing (type-checked conversion safety) higher friction than the convenient thing (builtin `as` casts). There is a place for external crates here for doing non-standard things, such as having default enum variants in a `From` implementation (just as the [derivative](https://crates.io/crates/derivative) crate implements custom derives of many traits), but the core infallible conversion feels like it should be within easy reach.
233+
234+
### Not removing `as` support for enums
235+
236+
We could lint/warn against `as` usage, without removing support for it. This would force less churn in the language, but leaves a foot-gun in play.
237+
238+
### Only warn/error or potentially truncating casts
239+
240+
We could only warn/error, or even only remove language support, for casts from larger to smaller types. This leaves multiple ways to do the same thing, which leaves an increased cognitive space, but could avoid a feeling of churn.
241+
242+
### Do nothing
243+
244+
If we do nothing, we leave a footgun for our users. It's probably not the worst footgun, and it's possible to work around.
245+
246+
# Prior art
247+
[prior-art]: #prior-art
248+
249+
- This was proposed less formally in [RFC 2596](https://github.com/rust-lang/rfcs/issues/2596).
250+
251+
- There used to be `FromPrimitive` and `ToPrimitive` derive macros in `std` which could be applied to enums, but [these were removed](https://github.com/rust-lang/rust/commit/eeb94886adccb3f13003f92f117115d17846ce1f) as part of a sweeping reduction in num-related functionality. I believe that this RFC represents a limited and targeted enough subset of this to be worthwhile.
252+
253+
- [Example issue](https://github.com/rust-lang/rust/issues/45884) reporting this behaviour as surprising, and less well warned for than the integer equivalent. [And another](https://github.com/rust-lang/rust/issues/74588).
254+
255+
- Enums used to be castable to floats, [and this was removed](https://github.com/rust-lang/rust/pull/14874) with the explicit suggestion to cast via an integer if needed.
256+
257+
- [RFC 2308](https://github.com/rust-lang/rfcs/pull/2308) has some relevant discussion around the purpose of `as`, distinction between `as` and `Into`, and some confusion caused by the handling of `as` around enums. It was closed, partially because "The `as` operator is probably not something that we want to encourage people to use.", which this RFC helps to further.
258+
259+
- `Drop` has unclear semantics when enums are cast with `as` (see [motivational issue](https://github.com/rust-lang/rust/issues/35941) and [tracking issue](https://github.com/rust-lang/rust/issues/73333)) - this is an example of `as` being forbidden because of problematic semantics. This RFC proposes taking this a step further.
260+
261+
# Unresolved questions
262+
[unresolved-questions]: #unresolved-questions
263+
264+
- Should `as` casts be removed for primitive enums, or simply discouraged?
265+
- Should `Into` be derivable for primitive enums which don't have an explicit `repr`? These [are described](https://doc.rust-lang.org/reference/items/enumerations.html#custom-discriminant-values-for-fieldless-enumerations) as being `isize` values, though are not guaranteed to be represented as such.
266+
267+
# Future possibilities
268+
[future-possibilities]: #future-possibilities
269+
270+
- We may want to also remove `as` casts for primitives where they are non-truncating (e.g. casting a `u8` to a `u16`, preferring a call to `u16::from`) to make clear that `as` is always a potentially truncating operation of which the reader should be wary.

0 commit comments

Comments
 (0)