Skip to content

make the safety documentation consistent in Ptr module #164241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rust-bors merged 1 commit into from
Nov 4, 2026
+144 −27
Merged

make the safety documentation consistent in Ptr module #164241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 36 additions & 9 deletions library/core/src/ptr/const_ptr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -393,11 +393,14 @@ impl<T: PointeeSized> *const T {
/// `count` is in units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [offset][pointer::offset] on it. See that method for documentation
/// and safety requirements.
/// using [offset][pointer::offset] on it.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
///
/// # Safety
///
/// See [offset][pointer::offset] for documentation and safety requirements.
#[must_use]
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -626,11 +629,14 @@ impl<T: PointeeSized> *const T {
/// units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [`offset_from`][pointer::offset_from] on it. See that method for
/// documentation and safety requirements.
/// using [`offset_from`][pointer::offset_from] on it.
///
/// For non-`Sized` pointees this operation considers only the data pointers,
/// ignoring the metadata.
///
/// # Safety
///
/// See [`offset_from`][pointer::offset_from] for documentation and safety requirements.
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
#[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -738,10 +744,13 @@ impl<T: PointeeSized> *const T {
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [`offset_from_unsigned`][pointer::offset_from_unsigned] on it.
/// See that method for documentation and safety requirements.
///
/// For non-`Sized` pointees this operation considers only the data pointers,
/// ignoring the metadata.
///
/// # Safety
///
/// See [`offset_from_unsigned`][pointer::offset_from_unsigned] for documentation and safety requirements.
#[stable(feature = "ptr_sub_ptr", since = "1.87.0")]
#[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "1.87.0")]
#[inline]
Expand Down Expand Up @@ -875,11 +884,14 @@ impl<T: PointeeSized> *const T {
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [add][pointer::add] on it. See that method for documentation
/// and safety requirements.
/// using [add][pointer::add] on it.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
///
/// # Safety
///
/// See [add][pointer::add] for documentation and safety requirements.
#[must_use]
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -960,11 +972,14 @@ impl<T: PointeeSized> *const T {
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [sub][pointer::sub] on it. See that method for documentation
/// and safety requirements.
/// using [sub][pointer::sub] on it.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
///
/// # Safety
///
/// See [sub][pointer::sub] for documentation and safety requirements.
#[must_use]
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -1137,6 +1152,8 @@ impl<T: PointeeSized> *const T {
/// Reads the value from `self` without moving it. This leaves the
/// memory in `self` unchanged.
///
/// # Safety
///
/// See [`ptr::read`] for safety concerns and examples.
///
/// [`ptr::read`]: crate::ptr::read()
Expand All @@ -1159,6 +1176,8 @@ impl<T: PointeeSized> *const T {
/// to not be elided or reordered by the compiler across other volatile
/// operations.
///
/// # Safety
///
/// See [`ptr::read_volatile`] for safety concerns and examples.
///
/// [`ptr::read_volatile`]: crate::ptr::read_volatile()
Expand All @@ -1179,6 +1198,8 @@ impl<T: PointeeSized> *const T {
///
/// Unlike `read`, the pointer may be unaligned.
///
/// # Safety
///
/// See [`ptr::read_unaligned`] for safety concerns and examples.
///
/// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()
Expand All @@ -1199,6 +1220,8 @@ impl<T: PointeeSized> *const T {
///
/// NOTE: this has the *same* argument order as [`ptr::copy`].
///
/// # Safety
///
/// See [`ptr::copy`] for safety concerns and examples.
///
/// [`ptr::copy`]: crate::ptr::copy()
Expand All @@ -1219,6 +1242,8 @@ impl<T: PointeeSized> *const T {
///
/// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`].
///
/// # Safety
///
/// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
///
/// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
Expand Down Expand Up @@ -1497,6 +1522,8 @@ impl<T> *const [T] {
/// Returns a raw pointer to an element or subslice, without doing bounds
/// checking.
///
/// # Safety
///
/// Calling this method with an [out-of-bounds index] or when `self` is not dereferenceable
/// is *[undefined behavior]* even if the resulting pointer is not used.
///
Expand Down
63 changes: 54 additions & 9 deletions library/core/src/ptr/mut_ptr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,11 +397,14 @@ impl<T: PointeeSized> *mut T {
/// `count` is in units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [offset][pointer::offset] on it. See that method for documentation
/// and safety requirements.
/// using [offset][pointer::offset] on it.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
///
/// # Safety
///
/// See [offset][pointer::offset] for documentation and safety requirements.
#[must_use]
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -806,11 +809,14 @@ impl<T: PointeeSized> *mut T {
/// units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [`offset_from`][pointer::offset_from] on it. See that method for
/// documentation and safety requirements.
/// using [`offset_from`][pointer::offset_from] on it.
///
/// For non-`Sized` pointees this operation considers only the data pointers,
/// ignoring the metadata.
///
/// # Safety
///
/// See [`offset_from`][pointer::offset_from] for documentation and safety requirements.
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
#[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -897,10 +903,13 @@ impl<T: PointeeSized> *mut T {
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [`offset_from_unsigned`][pointer::offset_from_unsigned] on it.
/// See that method for documentation and safety requirements.
///
/// For non-`Sized` pointees this operation considers only the data pointers,
/// ignoring the metadata.
///
/// # Safety
///
/// See [`offset_from_unsigned`][pointer::offset_from_unsigned] for documentation and safety requirements.
#[stable(feature = "ptr_sub_ptr", since = "1.87.0")]
#[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "1.87.0")]
#[inline]
Expand Down Expand Up @@ -974,11 +983,14 @@ impl<T: PointeeSized> *mut T {
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [add][pointer::add] on it. See that method for documentation
/// and safety requirements.
/// using [add][pointer::add] on it.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
///
/// # Safety
///
/// See [`add`][pointer::add] for documentation and safety requirements.
#[must_use]
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -1059,11 +1071,14 @@ impl<T: PointeeSized> *mut T {
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [sub][pointer::sub] on it. See that method for documentation
/// and safety requirements.
/// using [sub][pointer::sub] on it.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
///
/// # Safety
///
/// See [`sub`][pointer::sub] for documentation and safety requirements.
#[must_use]
#[inline(always)]
#[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
Expand Down Expand Up @@ -1230,6 +1245,8 @@ impl<T: PointeeSized> *mut T {
/// Reads the value from `self` without moving it. This leaves the
/// memory in `self` unchanged.
///
/// # Safety
///
/// See [`ptr::read`] for safety concerns and examples.
///
/// [`ptr::read`]: crate::ptr::read()
Expand All @@ -1252,6 +1269,8 @@ impl<T: PointeeSized> *mut T {
/// to not be elided or reordered by the compiler across other volatile
/// operations.
///
/// # Safety
///
/// See [`ptr::read_volatile`] for safety concerns and examples.
///
/// [`ptr::read_volatile`]: crate::ptr::read_volatile()
Expand All @@ -1272,6 +1291,8 @@ impl<T: PointeeSized> *mut T {
///
/// Unlike `read`, the pointer may be unaligned.
///
/// # Safety
///
/// See [`ptr::read_unaligned`] for safety concerns and examples.
///
/// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()
Expand All @@ -1292,6 +1313,8 @@ impl<T: PointeeSized> *mut T {
///
/// NOTE: this has the *same* argument order as [`ptr::copy`].
///
/// # Safety
///
/// See [`ptr::copy`] for safety concerns and examples.
///
/// [`ptr::copy`]: crate::ptr::copy()
Expand All @@ -1312,6 +1335,8 @@ impl<T: PointeeSized> *mut T {
///
/// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`].
///
/// # Safety
///
/// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
///
/// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
Expand All @@ -1332,6 +1357,8 @@ impl<T: PointeeSized> *mut T {
///
/// NOTE: this has the *opposite* argument order of [`ptr::copy`].
///
/// # Safety
///
/// See [`ptr::copy`] for safety concerns and examples.
///
/// [`ptr::copy`]: crate::ptr::copy()
Expand All @@ -1352,6 +1379,8 @@ impl<T: PointeeSized> *mut T {
///
/// NOTE: this has the *opposite* argument order of [`ptr::copy_nonoverlapping`].
///
/// # Safety
///
/// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
///
/// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
Expand All @@ -1369,6 +1398,8 @@ impl<T: PointeeSized> *mut T {

/// Executes the destructor (if any) of the pointed-to value.
///
/// # Safety
///
/// See [`ptr::drop_in_place`] for safety concerns and examples.
///
/// [`ptr::drop_in_place`]: crate::ptr::drop_in_place()
Expand All @@ -1387,6 +1418,8 @@ impl<T: PointeeSized> *mut T {
/// Overwrites a memory location with the given value without reading or
/// dropping the old value.
///
/// # Safety
///
/// See [`ptr::write`] for safety concerns and examples.
///
/// [`ptr::write`]: crate::ptr::write()
Expand All @@ -1405,6 +1438,8 @@ impl<T: PointeeSized> *mut T {
/// Invokes memset on the specified pointer, setting `count * size_of::<T>()`
/// bytes of memory starting at `self` to `val`.
///
/// # Safety
///
/// See [`ptr::write_bytes`] for safety concerns and examples.
///
/// [`ptr::write_bytes`]: crate::ptr::write_bytes()
Expand All @@ -1428,6 +1463,8 @@ impl<T: PointeeSized> *mut T {
/// to not be elided or reordered by the compiler across other volatile
/// operations.
///
/// # Safety
///
/// See [`ptr::write_volatile`] for safety concerns and examples.
///
/// [`ptr::write_volatile`]: crate::ptr::write_volatile()
Expand All @@ -1448,6 +1485,8 @@ impl<T: PointeeSized> *mut T {
///
/// Unlike `write`, the pointer may be unaligned.
///
/// # Safety
///
/// See [`ptr::write_unaligned`] for safety concerns and examples.
///
/// [`ptr::write_unaligned`]: crate::ptr::write_unaligned()
Expand All @@ -1466,6 +1505,8 @@ impl<T: PointeeSized> *mut T {
/// Replaces the value at `self` with `src`, returning the old
/// value, without dropping either.
///
/// # Safety
///
/// See [`ptr::replace`] for safety concerns and examples.
///
/// [`ptr::replace`]: crate::ptr::replace()
Expand All @@ -1484,6 +1525,8 @@ impl<T: PointeeSized> *mut T {
/// deinitializing either. They may overlap, unlike `mem::swap` which is
/// otherwise equivalent.
///
/// # Safety
///
/// See [`ptr::swap`] for safety concerns and examples.
///
/// [`ptr::swap`]: crate::ptr::swap()
Expand Down Expand Up @@ -1876,6 +1919,8 @@ impl<T> *mut [T] {
/// Returns a raw pointer to an element or subslice, without doing bounds
/// checking.
///
/// # Safety
///
/// Calling this method with an [out-of-bounds index] or when `self` is not dereferenceable
/// is *[undefined behavior]* even if the resulting pointer is not used.
///
Expand Down
Loading
Loading