From 6e8047eb413de42ac3a165ad3480e94782774f38 Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Sat, 16 Jan 2021 21:52:37 -0800
Subject: [PATCH 1/2] Change type layout definition to a list.
Also a little bit of style cleanup including putting the other half
of the opening of the chapter into a note.
Also a bit of wording change. Removed "today"; Added in some of the
words that were implicit ("properties"), added "targets" after "x64".
---
src/type-layout.md | 24 +++++++++++++++---------
1 file changed, 15 insertions(+), 9 deletions(-)
diff --git a/src/type-layout.md b/src/type-layout.md
index 6df9a6095..88d557c87 100644
--- a/src/type-layout.md
+++ b/src/type-layout.md
@@ -1,11 +1,15 @@
# 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
+* 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.
## Size and Alignment
@@ -32,7 +36,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::<Type>()`|
|-- |-- |
@@ -51,8 +55,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 +86,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
From e275ae74d257599866522d6378a68ca9d0eafd8a Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Sat, 16 Jan 2021 23:50:09 -0800
Subject: [PATCH 2/2] Define padding.
Decided to go with the very washy "field or element can be accessed"
instead of tring to define a new term for the property since we don't
actually define what a field or element is yet.
---
src/type-layout.md | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/src/type-layout.md b/src/type-layout.md
index 88d557c87..be0311bb9 100644
--- a/src/type-layout.md
+++ b/src/type-layout.md
@@ -5,12 +5,27 @@ The *layout* of a type is the combination of its:
* 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
All values have an alignment and size.
@@ -563,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