From aea0186fe5e583b101016e40da55bd9adcd0bc27 Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Tue, 12 May 2020 11:41:41 -0500
Subject: make many ptr functions 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.
---
 src/libcore/ptr/const_ptr.rs | 6 ++++++
 src/libcore/ptr/mut_ptr.rs   | 6 ++++++
 2 files changed, 12 insertions(+)

(limited to 'src/libcore/ptr')

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
-- 
cgit 1.4.1-3-g733a5