rust-lang / rust-lang/reference

Document `repr(uN)` enum representation more concretely than just size and alignment

Open
#1,947 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-type-layout
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

The reference currently says about the layout of repr(uN) enums:

Primitive Representation of Field-less Enums

For field-less enums, primitive representations set the size and alignment to be the same as the primitive type of the same name. For example, a field-less enum with a u8 representation can only have discriminants between 0 and 255 inclusive.

This specifies that the enum is no larger than the chosen primitive integer, but it doesn't actually specify what the contents of the bytes within that size are. We can then consult the page for enums to find that:

If the enumeration specifies a primitive representation, then the discriminant may be reliably accessed via unsafe pointer casting:

This combined with Rust's overall approach to types then leaves no room for there to be any other option (such as, say, the discriminant gratuitously being stored bit-inverted) — if reading in this way is OK, then it must be the case that writing in this way is also OK. However, this is an unnecessarily roundabout way to reach this conclusion, and in general, the Reference seems to sort of assume but not state that the discriminant at the surface-syntax level equals the integer stored in the representation. I think that the Reference should directly state the following facts:

  • For a repr([ui]N) enum without fields:
    • The bytes of that enum store the discriminant
      • as an integer of the chosen type,
      • with the same numerical value as the discriminant value that is specified in the enum declaration and that is readable via casting the enum to integer.
    • A valid value of this enum type may be written by writing the discriminant value.
  • For a repr([ui]N) enum with fields:
    • A valid value of this enum type may be written by writing the discriminant as for a fieldless version, and writing a valid value of each field of that variant at the appropriate offsets.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked Reference sections on primitive representations and enumerations, and verify the proposed wording against Rust's documented layout and discriminant rules. Done means the Reference explicitly and accurately describes stored discriminants and valid writes for both field-less and field-bearing repr(uN) enums.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.