Move offset_of_enum documentation to unstable book; add offset_of_slice.

Author: kpreid

library/core/src/mem/mod.rs

@@ -1256,10 +1256,6 @@ impl<T> SizedTypeProperties for T {}
 ///
 /// The offset is returned as a [`usize`].
 ///
-/// If the nightly-only feature `offset_of_enum` is enabled,
-/// `enum` variants may be traversed as if they were fields.
-/// Variants themselves do not have an offset.
-///
 /// # Offsets of, and in, dynamically sized types
 ///
 /// The field’s type must be [`Sized`], but it may be located in a [dynamically sized] container.
@@ -1338,11 +1334,16 @@ impl<T> SizedTypeProperties for T {}
 ///
 /// [explicit `repr` attribute]: https://doc.rust-lang.org/reference/type-layout.html#representations
 ///
+/// # Unstable features
+///
+/// The following unstable features expand the functionality of `offset_of!`:
+///
+/// * [`offset_of_enum`] — allows `enum` variants to be traversed as if they were fields.
+/// * [`offset_of_slice`] — allows getting the offset of a field of type `[T]`.
+///
 /// # Examples
 ///
 /// ```
-/// #![feature(offset_of_enum)]
-///
 /// use std::mem;
 /// #[repr(C)]
 /// struct FieldStruct {
@@ -1364,20 +1365,11 @@ impl<T> SizedTypeProperties for T {}
 /// struct NestedB(u8);
 ///
 /// assert_eq!(mem::offset_of!(NestedA, b.0), 0);
-///
-/// #[repr(u8)]
-/// enum Enum {
-///     A(u8, u16),
-///     B { one: u8, two: u16 },
-/// }
-///
-/// assert_eq!(mem::offset_of!(Enum, A.0), 1);
-/// assert_eq!(mem::offset_of!(Enum, B.two), 2);
-///
-/// assert_eq!(mem::offset_of!(Option<&u8>, Some.0), 0);
 /// ```
 ///
 /// [dynamically sized]: https://doc.rust-lang.org/reference/dynamically-sized-types.html
+/// [`offset_of_enum`]: https://doc.rust-lang.org/nightly/unstable-book/language-features/offset-of-enum.html
+/// [`offset_of_slice`]: https://doc.rust-lang.org/nightly/unstable-book/language-features/offset-of-slice.html
 #[stable(feature = "offset_of", since = "1.77.0")]
 #[allow_internal_unstable(builtin_syntax)]
 pub macro offset_of($Container:ty, $($fields:expr)+ $(,)?) {

src/doc/unstable-book/src/language-features/offset-of-enum.md

@@ -0,0 +1,29 @@
+# `offset_of_slice`
+
+The tracking issue for this feature is: [#120141]
+
+[#120141]: https://github.com/rust-lang/rust/issues/120141
+
+------------------------
+
+When the `offset_of_enum` feature is enabled, the [`offset_of!`] macro may be used to obtain the
+offsets of fields of `enum`s; to express this, `enum` variants may be traversed as if they were
+fields. Variants themselves do not have an offset, so they cannot appear as the last path component.
+
+```rust
+#![feature(offset_of_enum)]
+use std::mem;
+
+#[repr(u8)]
+enum Enum {
+    A(u8, u16),
+    B { one: u8, two: u16 },
+}
+
+assert_eq!(mem::offset_of!(Enum, A.0), 1);
+assert_eq!(mem::offset_of!(Enum, B.two), 2);
+
+assert_eq!(mem::offset_of!(Option<&u8>, Some.0), 0);
+```
+
+[`offset_of!`]: ../../std/mem/macro.offset_of.html

src/doc/unstable-book/src/language-features/offset-of-slice.md

@@ -0,0 +1,30 @@
+# `offset_of_slice`
+
+The tracking issue for this feature is: [#126151]
+
+[#126151]: https://github.com/rust-lang/rust/issues/126151
+
+------------------------
+
+When the `offset_of_slice` feature is enabled, the [`offset_of!`] macro may be used to determine
+the offset of fields whose type is `[T]`, that is, a slice of dynamic size.
+
+In general, fields whose type is dynamically sized do not have statically known offsets because
+they do not have statically known alignments. However, `[T]` has the same alignment as `T`, so
+it specifically may be allowed.
+
+```rust
+#![feature(offset_of_slice)]
+
+#[repr(C)]
+pub struct Struct {
+    head: u32,
+    tail: [u8],
+}
+
+fn main() {
+    assert_eq!(std::mem::offset_of!(Struct, tail), 4);
+}
+```
+
+[`offset_of!`]: ../../std/mem/macro.offset_of.html