Update values.rst

Author: rcseacord

src/coding-guidelines/values.rst

@@ -52,6 +52,42 @@ Values
 
          let x: u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB
 
+   .. compliant_example::
+      :id: compl_ex_Ke869nSXuShZ
+      :status: draft
+   
+      This compliant example contains no undefined behavior because all of the bytes in ``Newtype32`` are defined by ``Uninit32``.
+      Creating an uninitialized union is allowed, if somewhat controversial.
+      When bytes are read as a type (e.g., by using
+      `ptr.read() <https://doc.rust-lang.org/std/ptr/fn.read.html>`_, 
+      `*ptr <https://doc.rust-lang.org/std/ptr/index.html>`_, or
+      `mem::transmute <https://doc.rust-lang.org/std/mem/fn.transmute.html>`_), a *typed read* occurs.
+      The typed read asserts the bytes are valid as that type.
+      A union's validity requirement is the union of its variants' validity requirements.
+      Because ``()`` is zero-sized, it has no validity requirements.
+      A ``union`` containing ``()`` can validly hold any bit pattern, including uninitialized bytes.
+      ``Uninit32`` and ``MaybeUninit`` are both unions with ``()`` as a possibility.
+      This means they must be valid to read from a blob of uninitialized bytes within a valid allocation.
+      Because ``Newtype32`` is entirely defined by ``Uninit32``, it is also valid to read from uninitialized bytes.
+      The ``struct`` wrapper does not impose additional validity requirements.
+
+      .. code-block:: rust
+
+         use std::mem::MaybeUninit;
+
+         union Uninit32 {
+             u: u32,
+             i: i32,
+             f: f32,
+             void: (),
+         }
+
+         struct Newtype32(Uninit32);
+
+         fn main() {
+             let x: Newtype32 = unsafe { MaybeUninit::uninit().assume_init() };
+         }
+
    .. non_compliant_example::
       :id: non_compl_ex_eJDxk4PP63DF
       :status: draft
@@ -102,9 +138,9 @@ Values
       :id: non_compl_ex_bHaxZM7JOY0k
       :status: draft
 
-      Creating an uninitialized union value is allowed, if somewhat controversial.
-      However, all the of any read field must have been initialized by a prior write and 
+      Any read field must have been initialized by a prior write and 
       the bytes written must form a valid representation for the field's type.
+      Reading ``x.u`` as a ``u32`` field is undefined behavior because the memory is uninitialized.
 
       .. code-block:: rust
 
@@ -171,7 +207,7 @@ Values
       :id: compl_ex_Xr6MjsqshHxc
       :status: draft
 
-      The following code reads a union field:
+      The following code reads a ``union`` field:
 
       .. code-block:: rust