Merge pull request #1392 from joshlf/joshlf-patch-1

Specify bit validity and padding of some types

Author: ehuss

src/types/boolean.md

@@ -92,6 +92,12 @@ boolean type for its operands, they evaluate using the rules of [boolean logic].
 * `a < b` is the same as `!(a >= b)`
 * `a <= b` is the same as `a == b | a < b`
 
+## Bit validity
+
+The single byte of a `bool` is guaranteed to be initialized (in other words,
+`transmute::<bool, u8>(...)` is always sound -- but since some bit patterns
+are invalid `bool`s, the inverse is not always sound).
+
 [boolean logic]: https://en.wikipedia.org/wiki/Boolean_algebra
 [enumerated type]: enum.md
 [expressions]: ../expressions.md

src/types/numeric.md

@@ -45,3 +45,8 @@ within an object along with one byte past the end.
 > `isize` are either 32-bit or 64-bit. As a consequence, 16-bit
 > pointer support is limited and may require explicit care and acknowledgment
 > from a library to support.
+
+## Bit validity
+
+For every numeric type, `T`, the bit validity of `T` is equivalent to the bit
+validity of `[u8; size_of::<T>()]`. An uninitialized byte is not a valid `u8`.

src/types/pointer.md

@@ -50,6 +50,16 @@ Raw pointers can be created directly using [`core::ptr::addr_of!`] for `*const`
 
 The standard library contains additional 'smart pointer' types beyond references and raw pointers.
 
+## Bit validity
+
+Despite pointers and references being similar to `usize`s in the machine code emitted on most platforms,
+the semantics of transmuting a reference or pointer type to a non-pointer type is currently undecided.
+Thus, it may not be valid to transmute a pointer or reference type, `P`, to a `[u8; size_of::<P>()]`.
+
+For thin raw pointers (i.e., for `P = *const T` or `P = *mut T` for `T: Sized`),
+the inverse direction (transmuting from an integer or array of integers to `P`) is always valid.
+However, the pointer produced via such a transmutation may not be dereferenced (not even if `T` has size zero).
+
 [`core::ptr::addr_of!`]: ../../core/ptr/macro.addr_of.html
 [`core::ptr::addr_of_mut!`]: ../../core/ptr/macro.addr_of_mut.html
 [Interior mutability]: ../interior-mutability.md

src/types/textual.md

@@ -17,6 +17,12 @@ is valid UTF-8. Calling a `str` method with a non-UTF-8 buffer can cause
 Since `str` is a [dynamically sized type], it can only be instantiated through a
 pointer type, such as `&str`.
 
+## Bit validity
+
+Every byte of a `char` is guaranteed to be initialized (in other words,
+`transmute::<char, [u8; size_of::<char>()]>(...)` is always sound -- but since
+some bit patterns are invalid `char`s, the inverse is not always sound).
+
 [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
 [Undefined Behavior]: ../behavior-considered-undefined.md
 [dynamically sized type]: ../dynamically-sized-types.md