Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

unions have no active field #478

Merged
merged 10 commits into from
Jan 27, 2019
Merged

unions have no active field #478

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c3d23c2
unions have no active field
RalfJung Dec 9, 2018
20922ac
improve wording
RalfJung Dec 9, 2018
224303d
typo
RalfJung Dec 9, 2018
3135240
remove reference to unaccepted RFC
RalfJung Dec 10, 2018
3793103
clairification
RalfJung Dec 10, 2018
f1995cd
no more double space
RalfJung Dec 10, 2018
f85beb5
typos
RalfJung Dec 10, 2018
9f9313f
improve wording
RalfJung Dec 14, 2018
9ecb58d
de-parenthesize
RalfJung Dec 27, 2018
7276ea7
s/equivalent/analogous/
RalfJung Jan 9, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 15 additions & 10 deletions src/items/unions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,18 +29,22 @@ struct types, except that it must specify exactly one field:
let u = MyUnion { f1: 1 };
```

The expression above creates a value of type `MyUnion` with active field `f1`.
Active field of a union can be accessed using the same syntax as struct fields:
The expression above creates a value of type `MyUnion` and initializes the
storage using field `f1`. The union can be accessed using the same syntax as
RalfJung marked this conversation as resolved.
Show resolved Hide resolved
struct fields:

```rust,ignore
let f = u.f1;
```

Inactive fields can be accessed as well (using the same syntax) if they are
sufficiently layout compatible with the current value kept by the union.
Reading incompatible fields results in undefined behavior. However, the active
field is not generally known statically, so all reads of union fields have to
be placed in `unsafe` blocks.
Unions have no notion of an "active field". Instead, every union access just
interprets the storage at the type of the field used for the access. The effect
of reading a union with a different field than it was written to is that of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"field ... it was written to" here looks suspiciously similar to the "active field" that's intended to be removed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change compared to the previous semantics, I think, is that the "active field"/"field it was written to" doesn't necessarily exist with the new rules.
(While using the "active field" or some other wording for the field in question is a matter of terminology.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to improve the wording to make it more clear that there is nothing remembering which field was written to, just re-interpreting storage at different types. Does that help?

calling [`transmute`]. Reading data at a bad type results in undefined behavior
(for example, reading the value `3` at type `bool`).

However, which fields are safe to read and which not is generally not known
statically, so all reads of union fields have to be placed in `unsafe` blocks.

```rust
# union MyUnion { f1: u32, f2: f32 }
Expand All @@ -65,9 +69,9 @@ Commonly, code using unions will provide safe wrappers around unsafe union
field accesses.

Another way to access union fields is to use pattern matching. Pattern matching
on union fields uses the same syntax as struct patterns, except that the
pattern must specify exactly one field. Since pattern matching accesses
potentially inactive fields it has to be placed in `unsafe` blocks as well.
on union fields uses the same syntax as struct patterns, except that the pattern
must specify exactly one field. Since pattern matching is like reading the union
with a particular field, it has to be placed in `unsafe` blocks as well.

```rust
# union MyUnion { f1: u32, f2: f32 }
Expand Down Expand Up @@ -149,3 +153,4 @@ in [RFC 1897 "Unions v1.2"](https://github.com/rust-lang/rfcs/pull/1897).
[_Generics_]: items/generics.html
[_WhereClause_]: items/generics.html#where-clauses
[_StructFields_]: items/structs.html
[`transmute`]: ../../std/mem/fn.transmute.html