From b1b87ffdbc24e3928bf0aa4c766cd731ebbc641e Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Thu, 12 Mar 2026 12:35:39 -0700 Subject: [PATCH] Add overview documentation for `std::mem`. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I heard that `std::mem` sounds scary to some people, and how it’s described — “Basic functions for dealing with memory” — sounds even to me like something that should be avoided, not even because it would be unsafe, but because it is too low-level. Let’s fix that by telling people about what they can actually find in the module, without having to read all the individual item descriptions. --- library/core/src/mem/mod.rs | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/library/core/src/mem/mod.rs b/library/core/src/mem/mod.rs index d8521e79006e..b321908fd9e7 100644 --- a/library/core/src/mem/mod.rs +++ b/library/core/src/mem/mod.rs @@ -1,7 +1,32 @@ -//! Basic functions for dealing with memory. +//! Basic functions for dealing with memory, values, and types. //! -//! This module contains functions for querying the size and alignment of -//! types, initializing and manipulating memory. +//! The contents of this module can be seen as belonging to a few families: +//! +//! * [`drop`], [`replace`], [`swap`], and [`take`] +//! are safe functions for moving values in particular ways. +//! They are useful in everyday Rust code. +//! +//! * [`size_of`], [`size_of_val`], [`align_of`], [`align_of_val`], and [`offset_of`] +//! give information about the representation of values in memory. +//! +//! * [`discriminant`] +//! allows comparing the variants of [`enum`] values while ignoring their fields. +//! +//! * [`forget`] and [`ManuallyDrop`] +//! prevent destructors from running, which is used in certain kinds of ownership transfer. +//! [`needs_drop`] +//! tells you whether a type’s destructor even does anything. +//! +//! * [`transmute`], [`transmute_copy`], and [`MaybeUninit`] +//! convert and construct values in [`unsafe`] ways. +//! +//! See also the [`alloc`] and [`ptr`] modules for more primitive operations on memory. +//! +// core::alloc exists but doesn’t contain all the items we want to discuss +//! [`alloc`]: ../../std/alloc/index.html +//! [`enum`]: ../../std/keyword.enum.html +//! [`ptr`]: crate::ptr +//! [`unsafe`]: ../../std/keyword.unsafe.html #![stable(feature = "rust1", since = "1.0.0")]