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

Primitive bit validity and padding guarantees #1292

Closed
wants to merge 2 commits into from
Closed

Primitive bit validity and padding guarantees #1292

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e122ef
Primitive bit validity and padding guarantees
joshlf Nov 2, 2022
8a8077c
Clarify `char` bit validity
joshlf Nov 2, 2022
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
19 changes: 18 additions & 1 deletion src/type-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,25 @@ target platform. For example, on a 32 bit target, this is 4 bytes and on a 64
bit target, this is 8 bytes.

Most primitives are generally aligned to their size, although this is
platform-specific behavior. In particular, on x86 u64 and f64 are only
platform-specific behavior. In particular, on x86, `u64` and `f64` are only
Copy link
Member

Choose a reason for hiding this comment

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

Hm, this phrasing struck me as potentially confusing, since "x86" is often used as a shorthand to refer to "x86-64". (I did a brief double take, at least.) Per Wikipedia's chronology, "IA-32" might be a more appropriate term:

Suggested change
platform-specific behavior. In particular, on x86, `u64` and `f64` are only
platform-specific behavior. In particular, on IA-32, `u64` and `f64` are only

...but I think you're referring to target_arch value "x86" (which is distinct from x86_64). Rust inherits this shorthand from LLVM:

    x86,            // X86: i[3-9]86

...so you could instead disambiguate this by writing:

Suggested change
platform-specific behavior. In particular, on x86, `u64` and `f64` are only
platform-specific behavior. In particular, on `target_arch = x86` (which has a word size of 32 bits), `u64` and `f64` are only

aligned to 32 bits.

### Primitive Bit Validity and Padding

For each primitive type, `T`, in the preceding table other than `char`, any
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
For each primitive type, `T`, in the preceding table other than `char`, any
For each primitive type, `T`, in the preceding table other than `char` and `bool`, any

sequence of `size_of::<T>()` bytes is a valid instance of `T`. In other words,
`transmute::<[u8; size_of::<T>()], T>(...)` is guaranteed to be sound.

Similarly, for each primitive type, `T`, in the preceding table (including
`char`), `T` contains no padding or otherwise uninitialized bytes. In other
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
`char`), `T` contains no padding or otherwise uninitialized bytes. In other
`char` and `bool`), `T` contains no padding or otherwise uninitialized bytes. In other

words, `transmute::<T, [u8; size_of::<T>()]>(...)` is guaranteed to be sound.

Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
#### `bool` Bit Validity
A `bool`'s numerical value is guaranteed to be either 0x00 or 0x01,
It is undefined behavior to construct a `bool` with a value outside
this range. See the [`bool` docs][bool-docs] for more information.

#### `char` Bit Validity

A `char`'s numerical value is guaranteed to be in the range 0 to 0x10FFFF,
inclusive. It is undefined behavior to construct a `char` with a value outside
this range. See the [`char` docs][char-docs] for more information.

## Pointers and References Layout

Pointers and references have the same layout. Mutability of the pointer or
Expand Down Expand Up @@ -583,6 +599,7 @@ used with any other representation.
[`Sized`]: ../std/marker/trait.Sized.html
[`Copy`]: ../std/marker/trait.Copy.html
[dynamically sized types]: dynamically-sized-types.md
[char-docs]: ../std/primitive.char.html
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
[char-docs]: ../std/primitive.char.html
[bool-docs]: ../std/primitive.bool.html
[char-docs]: ../std/primitive.char.html

[field-less enums]: items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations
[enumerations]: items/enumerations.md
[zero-variant enums]: items/enumerations.md#zero-variant-enums
Expand Down