diff --git a/src/type-layout.md b/src/type-layout.md index 6df9a6095..be0311bb9 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -1,11 +1,30 @@ # Type Layout -The layout of a type is its size, alignment, and the relative offsets of its -fields. For enums, how the discriminant is laid out and interpreted is also part -of type layout. +The *layout* of a type is the combination of its: -Type layout can be changed with each compilation. Instead of trying to document -exactly what is done, we only document what is guaranteed today. +* size +* alignment +* relative offsets of its fields or elements +* relative offsets of padding +* for enums: how the discriminant is laid out and interpreted + +> **Note**: Type layout is allowed to change with each compilation. Instead of +> trying to document exactly how each type is laid out, we only document the +> properties that are guaranteed. + +## Padding + +Types may contain *padding*: bytes that have no semantic meaning that may take +on any bit pattern. When a type is [moved or copied], the value of padding bytes +may be changed. + +If a field can be accessed, its padding is also the padding of the containing +type. + +> **Note:**: Padding is usually added to make sure that fields and the type +> itself are properly aligned. As such, padding is usally only added to types +> with multiple fields. As an exception, [manually setting the +> alignment][alignment modifiers] can create padding for a type with one field. ## Size and Alignment @@ -32,7 +51,7 @@ the alignment of the type respectively. ## Primitive Data Layout -The size of most primitives is given in this table. +The size of most primitives is guaranteed and given in this table. | Type | `size_of::()`| |-- |-- | @@ -51,8 +70,8 @@ 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 -aligned to 32 bits. +platform-specific behavior. In particular, on `x86` targets, `u64` and `f64` are +only aligned to 32 bits. ## Pointers and References Layout @@ -82,7 +101,9 @@ Slices have the same layout as the section of the array they slice. > etc.) to slices. ## `str` Layout -String slices are a UTF-8 representation of characters that have the same layout as slices of type `[u8]`. + +String slices are a UTF-8 representation of characters that have the same layout +as slices of type `[u8]`. ## Tuple Layout @@ -557,9 +578,11 @@ used with any other representation. [`size_of`]: ../std/mem/fn.size_of.html [`Sized`]: ../std/marker/trait.Sized.html [`Copy`]: ../std/marker/trait.Copy.html +[alignment modifiers]: #the-alignment-modifiers [dynamically sized types]: dynamically-sized-types.md [field-less enums]: items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations [enumerations]: items/enumerations.md +[moved or copied]: expressions.md#moved-and-copied-types [zero-variant enums]: items/enumerations.md#zero-variant-enums [undefined behavior]: behavior-considered-undefined.md [27060]: https://github.com/rust-lang/rust/issues/27060