Document String::as(_mut)_str and str::as_str as exceptions to str/String's UTF-8 requirements.

Author: zachs18

library/alloc/src/string.rs

@@ -1077,15 +1077,25 @@ impl String {
     ///
     /// assert_eq!("foo", s.as_str());
     /// ```
+    ///
+    /// # Safety
+    ///
+    /// As an exception to the [general rule](String#utf-8), this function does not assume
+    /// that the input `String` contains valid UTF-8, and is guaranteed to not cause
+    /// immediate undefined behavior if called on a `String` containing invalid UTF-8.
     #[inline]
     #[must_use]
     #[stable(feature = "string_as_str", since = "1.7.0")]
     #[rustc_diagnostic_item = "string_as_str"]
     #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
     pub const fn as_str(&self) -> &str {
-        // SAFETY: String contents are stipulated to be valid UTF-8, invalid contents are an error
-        // at construction.
-        unsafe { str::from_utf8_unchecked(self.vec.as_slice()) }
+        // Note: cannot use `str::from_utf8_unchecked` as that may not allow invalid UTF-8.
+        let bytes = self.vec.as_slice();
+        // SAFETY: the pointer dereference is safe because that pointer
+        // comes from a reference which is guaranteed to be valid for reads.
+        // If the input bytes are not valid UTF-8, then the returned `&str` will
+        // have invalid UTF-8, which is unsafe but not immediate UB. See the "# Safety" section above.
+        unsafe { &*(bytes as *const [u8] as *const str) }
     }
 
     /// Converts a `String` into a mutable string slice.
@@ -1100,15 +1110,25 @@ impl String {
     ///
     /// assert_eq!("FOOBAR", s_mut_str);
     /// ```
+    ///
+    /// # Safety
+    ///
+    /// As an exception to the [general rule](String#utf-8), this function does not assume
+    /// that the input `String` contains valid UTF-8, and is guaranteed to not cause
+    /// immediate undefined behavior if called on a `String` containing invalid UTF-8.
     #[inline]
     #[must_use]
     #[stable(feature = "string_as_str", since = "1.7.0")]
     #[rustc_diagnostic_item = "string_as_mut_str"]
     #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
     pub const fn as_mut_str(&mut self) -> &mut str {
-        // SAFETY: String contents are stipulated to be valid UTF-8, invalid contents are an error
-        // at construction.
-        unsafe { str::from_utf8_unchecked_mut(self.vec.as_mut_slice()) }
+        // Note: cannot use `str::from_utf8_unchecked_mut` as that may not allow invalid UTF-8.
+        let bytes = self.vec.as_mut_slice();
+        // SAFETY: the pointer dereference is safe because that pointer
+        // comes from a reference which is guaranteed to be valid for reads and writes.
+        // If the input bytes are not valid UTF-8, then the returned `&str` will
+        // have invalid UTF-8, which is unsafe but not immediate UB. See the "# Safety" section above.
+        unsafe { &mut *(bytes as *mut [u8] as *mut str) }
     }
 
     /// Appends a given string slice onto the end of this `String`.
@@ -2966,13 +2986,8 @@ impl ops::Deref for String {
     /// immediate undefined behavior if called on a `String` containing invalid UTF-8.
     #[inline]
     fn deref(&self) -> &str {
-        // Note: cannot use `String::as_str` as that may not allow invalid UTF-8.
-        let bytes = self.vec.as_slice();
-        // SAFETY: the pointer dereference is safe because that pointer
-        // comes from a reference which is guaranteed to be valid for reads.
-        // If the input bytes are not valid UTF-8, then the returned `&str` will
-        // have invalid UTF-8, which is unsafe but not immediate UB. See the "# Safety" section above.
-        unsafe { &*(bytes as *const [u8] as *const str) }
+        // SAFETY: `String::as_str` has the same guarantee that invalid UTF-8 is not immediate UB
+        String::as_str(self)
     }
 }
 
@@ -2990,13 +3005,8 @@ impl ops::DerefMut for String {
     /// immediate undefined behavior if called on a `String` containing invalid UTF-8.
     #[inline]
     fn deref_mut(&mut self) -> &mut str {
-        // Note: cannot use `String::as_mut_str` as that may not allow invalid UTF-8.
-        let bytes = self.vec.as_mut_slice();
-        // SAFETY: the pointer dereference is safe because that pointer
-        // comes from a reference which is guaranteed to be valid for reads and writes.
-        // If the input bytes are not valid UTF-8, then the returned `&str` will
-        // have invalid UTF-8, which is unsafe but not immediate UB. See the "# Safety" section above.
-        unsafe { &mut *(bytes as *mut [u8] as *mut str) }
+        // SAFETY: `String::as_mut_str` has the same guarantee that invalid UTF-8 is not immediate UB
+        String::as_mut_str(self)
     }
 }
 

library/core/src/str/mod.rs

@@ -3277,6 +3277,12 @@ impl str {
     /// This method is redundant when used directly on `&str`, but
     /// it helps dereferencing other string-like types to string slices,
     /// for example references to `Box<str>` or `Arc<str>`.
+    ///
+    /// # Safety
+    ///
+    /// As an exception to the [general rule](prim@str#invariant), this function does not assume
+    /// that the input `str` contains valid UTF-8, and is guaranteed to not cause
+    /// immediate undefined behavior if called on a `str` containing invalid UTF-8.
     #[inline]
     #[unstable(feature = "str_as_str", issue = "130366")]
     pub const fn as_str(&self) -> &str {

tests/mir-opt/jump_threading.chained_conditions.JumpThreading.panic-abort.diff

@@ -47,29 +47,29 @@
               scope 6 (inlined #[track_caller] <String as Index<RangeFull>>::index) {
                   let _29: &str;
                   scope 7 (inlined String::as_str) {
-                      scope 8 (inlined Vec::<u8>::as_slice) {
-                          let _30: *const [u8];
-                          let mut _31: *const u8;
-                          let mut _32: usize;
-                          scope 9 (inlined Vec::<u8>::as_ptr) {
-                              scope 10 (inlined alloc::raw_vec::RawVec::<u8>::ptr) {
-                                  scope 11 (inlined alloc::raw_vec::RawVecInner::ptr::<u8>) {
-                                      scope 12 (inlined alloc::raw_vec::RawVecInner::non_null::<u8>) {
-                                          let mut _33: std::ptr::NonNull<u8>;
-                                          scope 13 (inlined NonNull::<u8>::cast::<u8>) {
-                                              scope 14 (inlined NonNull::<u8>::as_ptr) {
+                      let _30: *const str;
+                      scope 8 {
+                      }
+                      scope 9 (inlined Vec::<u8>::as_slice) {
+                          let _31: *const [u8];
+                          let mut _32: *const u8;
+                          let mut _33: usize;
+                          scope 10 (inlined Vec::<u8>::as_ptr) {
+                              scope 11 (inlined alloc::raw_vec::RawVec::<u8>::ptr) {
+                                  scope 12 (inlined alloc::raw_vec::RawVecInner::ptr::<u8>) {
+                                      scope 13 (inlined alloc::raw_vec::RawVecInner::non_null::<u8>) {
+                                          let mut _34: std::ptr::NonNull<u8>;
+                                          scope 14 (inlined NonNull::<u8>::cast::<u8>) {
+                                              scope 15 (inlined NonNull::<u8>::as_ptr) {
                                               }
                                           }
                                       }
-                                      scope 15 (inlined NonNull::<u8>::as_ptr) {
+                                      scope 16 (inlined NonNull::<u8>::as_ptr) {
                                       }
                                   }
                               }
                           }
                       }
-                      scope 16 (inlined from_utf8_unchecked) {
-                          let _34: *const str;
-                      }
                   }
                   scope 17 (inlined #[track_caller] core::str::traits::<impl SliceIndex<str> for RangeFull>::index) {
                   }
@@ -119,29 +119,29 @@
               scope 32 (inlined #[track_caller] <String as Index<RangeFull>>::index) {
                   let _49: &str;
                   scope 33 (inlined String::as_str) {
-                      scope 34 (inlined Vec::<u8>::as_slice) {
-                          let _50: *const [u8];
-                          let mut _51: *const u8;
-                          let mut _52: usize;
-                          scope 35 (inlined Vec::<u8>::as_ptr) {
-                              scope 36 (inlined alloc::raw_vec::RawVec::<u8>::ptr) {
-                                  scope 37 (inlined alloc::raw_vec::RawVecInner::ptr::<u8>) {
-                                      scope 38 (inlined alloc::raw_vec::RawVecInner::non_null::<u8>) {
-                                          let mut _53: std::ptr::NonNull<u8>;
-                                          scope 39 (inlined NonNull::<u8>::cast::<u8>) {
-                                              scope 40 (inlined NonNull::<u8>::as_ptr) {
+                      let _50: *const str;
+                      scope 34 {
+                      }
+                      scope 35 (inlined Vec::<u8>::as_slice) {
+                          let _51: *const [u8];
+                          let mut _52: *const u8;
+                          let mut _53: usize;
+                          scope 36 (inlined Vec::<u8>::as_ptr) {
+                              scope 37 (inlined alloc::raw_vec::RawVec::<u8>::ptr) {
+                                  scope 38 (inlined alloc::raw_vec::RawVecInner::ptr::<u8>) {
+                                      scope 39 (inlined alloc::raw_vec::RawVecInner::non_null::<u8>) {
+                                          let mut _54: std::ptr::NonNull<u8>;
+                                          scope 40 (inlined NonNull::<u8>::cast::<u8>) {
+                                              scope 41 (inlined NonNull::<u8>::as_ptr) {
                                               }
                                           }
                                       }
-                                      scope 41 (inlined NonNull::<u8>::as_ptr) {
+                                      scope 42 (inlined NonNull::<u8>::as_ptr) {
                                       }
                                   }
                               }
                           }
                       }
-                      scope 42 (inlined from_utf8_unchecked) {
-                          let _54: *const str;
-                      }
                   }
                   scope 43 (inlined #[track_caller] core::str::traits::<impl SliceIndex<str> for RangeFull>::index) {
                   }
@@ -226,22 +226,22 @@
           _27 = no_retag copy (*_8);
           _28 = no_retag copy (*_10);
           StorageLive(_29);
-          StorageLive(_30);
           StorageLive(_31);
-          StorageLive(_33);
-          _33 = copy (((((*_27).0: std::vec::Vec<u8>).0: alloc::raw_vec::RawVec<u8>).0: alloc::raw_vec::RawVecInner).0: std::ptr::NonNull<u8>);
-          _31 = copy _33 as *const u8 (Transmute);
-          StorageDead(_33);
           StorageLive(_32);
-          _32 = copy (((*_27).0: std::vec::Vec<u8>).1: usize);
-          _30 = *const [u8] from (copy _31, move _32);
-          StorageDead(_32);
-          StorageDead(_31);
           StorageLive(_34);
-          _34 = copy _30 as *const str (PtrToPtr);
-          _29 = &(*_34);
+          _34 = copy (((((*_27).0: std::vec::Vec<u8>).0: alloc::raw_vec::RawVec<u8>).0: alloc::raw_vec::RawVecInner).0: std::ptr::NonNull<u8>);
+          _32 = copy _34 as *const u8 (Transmute);
           StorageDead(_34);
+          StorageLive(_33);
+          _33 = copy (((*_27).0: std::vec::Vec<u8>).1: usize);
+          _31 = *const [u8] from (copy _32, move _33);
+          StorageDead(_33);
+          StorageDead(_32);
+          StorageLive(_30);
+          _30 = copy _31 as *const str (PtrToPtr);
+          _29 = &(*_30);
           StorageDead(_30);
+          StorageDead(_31);
           StorageLive(_36);
           StorageLive(_38);
           _36 = copy _29 as &[u8] (Transmute);
@@ -288,22 +288,22 @@
           _47 = no_retag copy (*_15);
           _48 = no_retag copy (*_17);
           StorageLive(_49);
-          StorageLive(_50);
           StorageLive(_51);
-          StorageLive(_53);
-          _53 = copy (((((*_47).0: std::vec::Vec<u8>).0: alloc::raw_vec::RawVec<u8>).0: alloc::raw_vec::RawVecInner).0: std::ptr::NonNull<u8>);
-          _51 = copy _53 as *const u8 (Transmute);
-          StorageDead(_53);
           StorageLive(_52);
-          _52 = copy (((*_47).0: std::vec::Vec<u8>).1: usize);
-          _50 = *const [u8] from (copy _51, move _52);
-          StorageDead(_52);
-          StorageDead(_51);
           StorageLive(_54);
-          _54 = copy _50 as *const str (PtrToPtr);
-          _49 = &(*_54);
+          _54 = copy (((((*_47).0: std::vec::Vec<u8>).0: alloc::raw_vec::RawVec<u8>).0: alloc::raw_vec::RawVecInner).0: std::ptr::NonNull<u8>);
+          _52 = copy _54 as *const u8 (Transmute);
           StorageDead(_54);
+          StorageLive(_53);
+          _53 = copy (((*_47).0: std::vec::Vec<u8>).1: usize);
+          _51 = *const [u8] from (copy _52, move _53);
+          StorageDead(_53);
+          StorageDead(_52);
+          StorageLive(_50);
+          _50 = copy _51 as *const str (PtrToPtr);
+          _49 = &(*_50);
           StorageDead(_50);
+          StorageDead(_51);
           StorageLive(_56);
           StorageLive(_58);
           _56 = copy _49 as &[u8] (Transmute);