owned this note
owned this note
Published
Linked with GitHub
- Feature Name: arbitrary_enum_discriminant
- Start Date: 2018-03-11
- RFC PR: (leave this empty)
- Rust Issue: (leave this empty)
# Summary
[summary]: #summary
This RFC gives users a way to control the discriminants of variants of all enumerations, not just the ones that are shaped like C-like enums (i.e. where all the variants have no fields).
The change is minimal: allow any variant to be adorned with an explicit discriminant value, whether or not that variant has any field.
# Motivation
[motivation]: #motivation
Stylo, the style system of Servo, represents CSS properties with a large enumeration `PropertyDeclaration` where each variant has only one field which represents the value of a given CSS property. Here is a subset of it:
```rust
#[repr(u16)]
enum PropertyDeclaration {
Color(Color),
Height(Length),
InlineSize(Length),
TransformOrigin(TransformOrigin),
}
```
For various book-keeping reasons, Servo also generates a `LonghandId` enumeration with the same variants as `PropertyDeclaration` but without the fields, thus making `LonghandId` a C-like enumeration:
```rust
#[derive(Clone, Copy)]
#[repr(u16)]
enum LonghandId {
Color,
Height,
InlineSize,
TransformOrigin,
}
```
Given that rustc guarantees that `#[repr(u16)]` enumerations start with their discriminant stored as a `u16`, going from `&PropertyDeclaration` to `LonghandId` is then just a matter of unsafely coercing `&self` as a `&LonghandId`:
```rust
impl PropertyDeclaration {
fn id(&self) -> LonghandId {
unsafe { *(self as *const Self as *const LonghandId) }
}
}
```
This works great, but doesn't scale if we want to replicate this behaviour for an enumeration that is a subset of `PropertyDeclaration`, for example an enumeration `AnimationValue` that is limited to animatable properties:
```rust
#[repr(u16)]
enum AnimationValue {
Color(Color),
Height(Length),
TransformOrigin(TransformOrigin),
}
impl AnimationValue {
fn id(&self) -> LonghandId {
// We can't just unsafely read `&self` as a `&LonghandId` because
// the discriminant of `AnimationValue::TransformOrigin` isn't equal
// to `LonghandId::TransformOrigin` anymore.
match *self {
AnimationValue::Color(_) => LonghandId::Color,
AnimationValue::Height(_) => LonghandId::Height,
AnimationValue::TransformOrigin(_) => LonghandId::TransformOrigin,
}
}
}
```
This is not sustainable, as the jump table generated by rustc to compile this huge match expression is larger than 4KB in the final Gecko binary, when this operation could be a trivial `u16` copy. This is worked around in Servo by generating spurious `Void` variants for the non-animatable properties in `AnimationValue`:
```rust
enum Void {}
#[repr(u16)]
enum AnimationValue {
Color(Color),
Height(Length),
InlineSize(Void),
TransformOrigin(TransformOrigin),
}
impl AnimationValue {
fn id(&self) -> LonghandId
// We can use the unsafe trick again.
unsafe { *(self as *const Self as *const LonghandId) }
}
}
```
This is unfortunately quite painful to use, given now all methods matching against `AnimationValue` need to have dummy arms for all of these variants:
```rust
impl AnimationValue {
fn do_something(&self) {
match *self {
AnimationValue::Color(ref color) => {
do_something_with_color(color)
}
AnimationValue::Height(ref height) => {
do_something_with_height(height)
}
// This shouldn't be needed.
AnimationValue::InlineSize(ref void) => {
match *void {}
}
AnimationValue::TransformOrigin(ref origin) => {
do_something_with_transform_origin(origin)
}
}
}
}
```
We suggest generalising the explicit discriminant notation to all enums, regardless of whether their variants have fields or not:
```rust
#[repr(u16)]
enum AnimationValue {
Color(Color) = LonghandId::Color as u16,
Height(Length) = LonghandId::Height as u16,
TransformOrigin(TransformOrigin) = LonghandId::TransformOrigin as u16,
}
impl AnimationValue {
fn id(&self) -> LonghandId
// We can use the unsafe trick again.
unsafe { *(self as *const Self as *const LonghandId) }
}
fn do_something(&self) {
// No spurious variant anymore.
match *self {
AnimationValue::Color(ref color) => {
do_something_with_color(color)
}
AnimationValue::Height(ref height) => {
do_something_with_height(height)
}
AnimationValue::TransformOrigin(ref origin) => {
do_something_with_transform_origin(origin)
}
}
}
}
```
# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation
An enumeration with only field-less variants can currently have explicit discriminant values:
```rust
enum ForceFromage {
Emmental = 0,
Camembert = 1,
Roquefort = 2,
}
```
With this RFC, users are allowed to put explicit discriminant values on any variant of any enumeration, not just the ones where all variants are field-less:
```rust
enum ParisianSandwichIngredient {
Bread(BreadKind) = 0,
Ham(HamKind) = 1,
Butter(ButterKind) = 2,
}
```
# Reference-level explanation
[reference-level-explanation]: #reference-level-explanation
## Grammar
The production for enumeration items becomes:
```
EnumItem :
OuterAttribute*
IDENTIFIER ( EnumItemTuple | EnumItemStruct)? EnumItemDiscriminant?
```
## Semantics
The limitation that only field-less enumerations can have explicit discriminant values is lifted, and no other change is made to their semantics:
* enumerations with fields still can't be casted to numeric types with the `as` operator;
* if the first variant doesn't have an explicit discriminant, it is set to zero;
* any unspecified discriminant is set to one higher than the one from the previous variant;
* under the default representation, the specified discriminants are interpreted as `isize`;
* two variants cannot share the same discriminant.
# Drawbacks
[drawbacks]: #drawbacks
This introduces one more knob to the representation of enumerations.
# Rationale and alternatives
[alternatives]: #alternatives
Reusing the current syntax and semantics for explicit discriminants of field-less enumerations means that the changes to the grammar and semantics of the language are minimal. The alternative is to put the specified discriminants in variant attributes, but this would be at odds with the syntax for field-less enumerations.
```rust
enum ParisianSandwichIngredient {
#[discriminant = 0]
Bread(BreadKind),
#[discriminant = 1]
Ham(HamKind),
#[discriminant = 2]
Butter(ButterKind),
}
```
# Prior art
[prior-art]: #prior-art
No prior art.
# Unresolved questions
[unresolved]: #unresolved-questions
## Should discriminants of enumerations with fields be specified as variant attributes?
Should they?
## Should this apply only to enumerations with an explicit representation?
Should it?
# Thanks
Thanks to Mazdak Farrokhzad (@Centril) and Simon Sapin (@SimonSapin) for the reviews, and my local bakery for their delicious baguettes. 🥖