Merge pull request #67 from gnzlbg/consistent_layout

Use layout consistently instead of mixing it with representation

Author: nikomatsakis

active_discussion/representation.md renamed to active_discussion/layout.md

@@ -1,4 +1,4 @@
-# Data structure representation
+# Data structure layout
 
 ## Introduction
 
@@ -135,9 +135,9 @@ To start, we will create threads for each major categories of types
     - When using the C ABI, these map to the C pointer types, presumably
 - Raw pointers
     - Effectively same as integers?
-    - Is `ptr::null` etc guaranteed to be equal in representation to `0_usize`?
+    - Is `ptr::null` etc guaranteed to be equal to `0_usize`?
       - C does guarantee that `0` when cast to a pointer is NULL
-- Representation knobs:
+- Layout knobs:
     - Custom alignment ([RFC 1358])
     - Packed ([RFC 1240] talks about some safety issues)
 

reference/src/SUMMARY.md

@@ -7,17 +7,17 @@
     - [Keeping secrets](./active_discussion/crypto_concerns/keeping_secrets.md)
     - [Constant time code](./active_discussion/crypto_concerns/constant_time_code.md)
     - [Zeroing](./active_discussion/crypto_concerns/zeroing.md)
-  - [Data structure representation](./active_discussion/representation.md)
+  - [Data structure layout](./active_discussion/layout.md)
   - [Stable addresses](./active_discussion/stable_addresses.md)
   - [Storage liveness](./active_discussion/storage_liveness.md)
   - [Uninhabited types like `!` and exhaustiveness](./active_discussion/uninhabited_types.md)
   - [Unions](./active_discussion/unions.md)
   - [Uninitialized memory](./active_discussion/uninitialized_memory.md)
-- [Data representation](./representation.md)
-  - [Structs and tuples](./representation/structs-and-tuples.md)
-  - [Integers and Floating Points] (./integers-floatingpoint.md)
-  - [Unions](./representation/unions.md)
-  - [Vectors](./representation/vectors.md)
+- [Data layout](./layout.md)
+  - [Structs and tuples](./layout/structs-and-tuples.md)
+  - [Integers and Floating Points](./layout/integers-floatingpoint.md)
+  - [Unions](./layout/unions.md)
+  - [Vectors](./layout/vectors.md)
 - [Optimizations](./optimizations.md)
   - [Optimizing immutable memory](./optimizations/immutable_memory.md) 
 - [Glossary](./glossary.md)

reference/src/glossary.md

@@ -49,16 +49,18 @@ Moreover, such unsafe code must not return a non-UTF-8 string to the "outside" o
 To summarize: *Data must always be valid, but it only must be safe in safe code.*
 For some more information, see [this blog post](https://www.ralfj.de/blog/2018/08/22/two-kinds-of-invariants.html).
 
-#### Layout / Representation
+#### Layout
 
 The *layout* of a type defines its size and alignment as well as the offsets of its subobjects (e.g. fields of structs/unions/enum/... or elements of arrays).
 Moreover, the layout of a type records its *function call ABI* (or just *ABI* for short): how the type is passed *by value* across a function boundary.
 
-We often use *representation* as a synonym for "layout".
+Note: Originally, *layout* and *representation* were treated as synonyms, and Rust language features like the `#[repr]` attribute reflect this. 
+In this document, *layout* and *representation* are not synonyms.
 
 ### TODO
 
 * *niche*
 * *tag*
 * *rvalue*
 * *lvalue*
+* *representation*

reference/src/representation/integers-floatingpoint.md renamed to reference/src/layout/integers-floatingpoint.md

@@ -1,9 +1,9 @@
-# Representation of Boolean, Floating Point, and Integral Types
+# Layout of Boolean, Floating Point, and Integral Types
 This chapter represents the consensus from issue [#9]. It documents the memory layout and considerations for `bool`, `usize`, `isize`, floating point types, and integral types.
 [#9]: https://github.com/rust-rfcs/unsafe-code-guidelines/issues/9
 
 ## Overview
-These are all scalar types, representing a single value. These types have no representation variants (no #[repr(C)] or #[repr(Rust)]. Their size is fixed and well-defined across FFI boundaries and map to their corresponding integral types in the C ABI.
+These are all scalar types, representing a single value. These types have no layout variants (no #[repr(C)] or #[repr(Rust)]. Their size is fixed and well-defined across FFI boundaries and map to their corresponding integral types in the C ABI.
 - `bool`: 1 byte
   - any `bool` can be cast into an integer, taking on the values 1 (true) or 0 (false)
 - `usize`, `isize`: pointer-sized unsigned/signed integer type
@@ -20,7 +20,7 @@ These are all scalar types, representing a single value. These types have no rep
   - represents [Unicode scalar value](http://www.unicode.org/glossary/#unicode_scalar_value)
 
 ##`usize`/`isize`
-Types `usize` and `isize` are committed to having the same size as a native pointer on the platform. The representation of `usize` determines the following:
+Types `usize` and `isize` are committed to having the same size as a native pointer on the platform. The layout of `usize` determines the following:
 - how much a pointer of a certain type can be offseted,
 - the maximum size of Rust objects (because size_of/size_of_val return `usize`),
 - the maximum number of elements in an array ([T; N: usize]),

reference/src/representation/pointers.md renamed to reference/src/layout/pointers.md

@@ -1,4 +1,4 @@
-# Representation of reference and pointer types
+# Layout of reference and pointer types
 
 ### Terminology
 
@@ -29,13 +29,13 @@ and are at least one word.
 
 ### Notes
 
-The representations of `&T`, `&mut T` and `*T` are the same.
+The layouts of `&T`, `&mut T` and `*T` are the same.
 
-We do not make any guarantees about the representation of
+We do not make any guarantees about the layout of
 multi-trait objects `&(dyn T + U)` or references to other dynamically sized types,
 other than that they are at least word-aligned, and have size at least one word.
 
-The representation of `&dyn T` when `T` is a trait is the same as that of:
+The layout of `&dyn T` when `T` is a trait is the same as that of:
 ```rust
 #[repr(C)]
 struct DynObject {
@@ -44,7 +44,7 @@ struct DynObject {
 }
 ```
 
-The representation of `&[T]` is the same as that of:
+The layout of `&[T]` is the same as that of:
 ```rust
 #[repr(C)]
 struct Slice<T> {
@@ -53,4 +53,4 @@ struct Slice<T> {
 }
 ```
 
-The representation of `&str` is the same as that of `&[u8]`.
+The layout of `&str` is the same as that of `&[u8]`.

reference/src/representation/structs-and-tuples.md renamed to reference/src/layout/structs-and-tuples.md

@@ -1,4 +1,4 @@
-# Representation of structs and tuples
+# Layout of structs and tuples
 
 **Disclaimer:** This chapter represents the consensus from issues
 [#11] and [#12].  The statements in here are not (yet) "guaranteed"
@@ -36,7 +36,7 @@ extend unsizing to other elements of tuples as well.
 Some related discussion:
 
 - [RFC #1582](https://github.com/rust-lang/rfcs/pull/1582) proposed
-  that tuple structs should have a "nested representation", where
+  that tuple structs should have a "nested layout", where
   e.g. `(T1, T2, T3)` would in fact be laid out as `(T1, (T2,
   T3))`. The purpose of this was to permit variadic matching and so
   forth against some suffix of the struct. This RFC was not accepted,

reference/src/representation/unions.md renamed to reference/src/layout/unions.md

@@ -1,4 +1,4 @@
-# Representation of unions
+# Layout of unions
 
 **Disclaimer:** This chapter represents the consensus from issue
 [#13].  The statements in here are not (yet) "guaranteed"

reference/src/representation/vectors.md renamed to reference/src/layout/vectors.md

@@ -1,4 +1,4 @@
-# Representation of vectors
+# Layout of vectors
 
 **Disclaimer:** This chapter represents the consensus from issue
 [#38]. The statements in here are not (yet) "guaranteed"

reference/src/representation.md

@@ -1,23 +1,23 @@
-# Data structure representation
+# Data structure layout
 
 ## Introduction
 
-## Representation of scalars
+## Layout of scalars
 
 https://github.com/rust-rfcs/unsafe-code-guidelines/issues/9
 
-## Representation of enums 
+## Layout of enums 
 
 https://github.com/rust-rfcs/unsafe-code-guidelines/issues/10 
 
-## Representation of unions
+## Layout of unions
 
 https://github.com/rust-rfcs/unsafe-code-guidelines/issues/13
 
-## Representation of references and raw pointers
+## Layout of references and raw pointers
 
 https://github.com/rust-rfcs/unsafe-code-guidelines/issues/16
 
-## Representation of function pointers
+## Layout of function pointers
 
 https://github.com/rust-rfcs/unsafe-code-guidelines/issues/14