Rollup merge of #72143 - rust-lang:steveklabnik-must-use, r=sfackler

make offset must_use

https://djugei.github.io/bad-at-unsafe/ describes an error a user had when trying to use offset:

> At first I just assumed that the .add() and .offset() methods on pointers would mutate the pointer. They do not. Instead they return a new pointer, which gets dropped silently if you don't use it. Unlike for example Result, which is must_use annotated.

This PR only adds `offset`, because I wanted to float the idea; I'm imagining that there's more than just `add` and `offset` that could use this. I am also very open to re-wording the warning.

r? @rust-lang/libs

3 files changed, 14 insertions, 0 deletions

diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs
index 43512f7a236..a60380137e1 100644
--- a/src/libcore/intrinsics.rs
+++ b/src/libcore/intrinsics.rs
@@ -1311,6 +1311,7 @@ extern "rust-intrinsic" {
     ///
     /// The stabilized version of this intrinsic is
     /// [`std::pointer::offset`](../../std/primitive.pointer.html#method.offset).
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     pub fn offset<T>(dst: *const T, offset: isize) -> *const T;
 
     /// Calculates the offset from a pointer, potentially wrapping.
@@ -1327,6 +1328,7 @@ extern "rust-intrinsic" {
     ///
     /// The stabilized version of this intrinsic is
     /// [`std::pointer::wrapping_offset`](../../std/primitive.pointer.html#method.wrapping_offset).
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
 
     /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
diff --git a/src/libcore/ptr/const_ptr.rs b/src/libcore/ptr/const_ptr.rs
index 94ad77d1ec6..85ba5fc0638 100644
--- a/src/libcore/ptr/const_ptr.rs
+++ b/src/libcore/ptr/const_ptr.rs
@@ -150,6 +150,7 @@ impl<T: ?Sized> *const T {
     /// }
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub unsafe fn offset(self, count: isize) -> *const T
     where
@@ -208,6 +209,7 @@ impl<T: ?Sized> *const T {
     /// }
     /// ```
     #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub fn wrapping_offset(self, count: isize) -> *const T
     where
@@ -390,6 +392,7 @@ impl<T: ?Sized> *const T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub unsafe fn add(self, count: usize) -> Self
     where
@@ -451,6 +454,7 @@ impl<T: ?Sized> *const T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub unsafe fn sub(self, count: usize) -> Self
     where
@@ -506,6 +510,7 @@ impl<T: ?Sized> *const T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub fn wrapping_add(self, count: usize) -> Self
     where
@@ -561,6 +566,7 @@ impl<T: ?Sized> *const T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub fn wrapping_sub(self, count: usize) -> Self
     where
diff --git a/src/libcore/ptr/mut_ptr.rs b/src/libcore/ptr/mut_ptr.rs
index cf9e20aa569..0781d7e6cac 100644
--- a/src/libcore/ptr/mut_ptr.rs
+++ b/src/libcore/ptr/mut_ptr.rs
@@ -144,6 +144,7 @@ impl<T: ?Sized> *mut T {
     /// }
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub unsafe fn offset(self, count: isize) -> *mut T
     where
@@ -201,6 +202,7 @@ impl<T: ?Sized> *mut T {
     /// assert_eq!(&data, &[0, 2, 0, 4, 0]);
     /// ```
     #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub fn wrapping_offset(self, count: isize) -> *mut T
     where
@@ -436,6 +438,7 @@ impl<T: ?Sized> *mut T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub unsafe fn add(self, count: usize) -> Self
     where
@@ -497,6 +500,7 @@ impl<T: ?Sized> *mut T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub unsafe fn sub(self, count: usize) -> Self
     where
@@ -552,6 +556,7 @@ impl<T: ?Sized> *mut T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub fn wrapping_add(self, count: usize) -> Self
     where
@@ -607,6 +612,7 @@ impl<T: ?Sized> *mut T {
     /// }
     /// ```
     #[stable(feature = "pointer_methods", since = "1.26.0")]
+    #[must_use = "returns a new pointer rather than modifying its argument"]
     #[inline]
     pub fn wrapping_sub(self, count: usize) -> Self
     where