Document explicit exceptions to str/String's UTF-8 requirements.

Author: zachs18

library/alloc/src/string.rs

@@ -358,6 +358,38 @@ use crate::vec::Vec;
 /// called on a `String` may assume that it is valid UTF-8, which means that a non-UTF-8 `String`
 /// can lead to undefined behavior down the road.
 ///
+/// As an exception, some functions explicitly allow invalid UTF-8, and will not immediately cause undefined
+/// behavior if called on a `String` containing invalid UTF-8. In general, all of `String`'s associated
+/// functions other than those listed here should be assumed to require their input be valid UTF-8.
+/// Note that calling one of these functions on a `String` containing invalid UTF-8, may result in the return value
+/// also containing invalid UTF-8, if relevant.
+///
+/// * `String::as_bytes`
+/// * `String::as_bytes_mut`
+/// * `String::as_str`
+/// * `String::as_mut_str`
+/// * `String::as_ptr`
+/// * `String::as_mut_ptr`
+/// * `String::as_mut_vec`
+/// * `String::capacity`
+/// * `String::len`
+/// * `String::clear`
+/// * `<String as Drop>::drop` (i.e. dropping a `String` that contains invalid UTF-8 does not alone cause UB)
+/// * `String::leak`
+/// * `String::into_boxed_str`
+/// * `String::reserve`
+/// * `String::reserve_exact`
+/// * `String::try_reserve`
+/// * `String::try_reserve_exact`
+/// * `<String as Deref>::deref`
+/// * `<String as DerefMut>::deref_mut`
+/// * `<String as AsRef<str>>::as_ref`
+/// * `<String as AsMut<str>>::as_mut`
+/// * `<String as Borrow<str>>::borrow`
+/// * `<String as BorrowMut<str>>::borrow_mut`
+/// * `<String as Clone>::clone`
+/// * `<String as Clone>::clone_from`
+///
 /// [str]: prim@str "str"
 /// [`str`]: prim@str "str"
 /// [`&str`]: prim@str "&str"

library/core/src/primitive_docs.rs

@@ -1015,6 +1015,29 @@ mod prim_slice {}
 /// Constructing a non-UTF-8 string slice is not immediate undefined behavior, but any function
 /// called on a string slice may assume that it is valid UTF-8, which means that a non-UTF-8 string
 /// slice can lead to undefined behavior down the road.
+///
+/// As an exception, some functions explicitly allow invalid UTF-8, and will not immediately cause undefined
+/// behavior if called on a `str` containing invalid UTF-8. In general, all of `str`'s associated
+/// functions other than those listed here should be assumed to require their input be valid UTF-8.
+/// Note that calling one of these functions on a `str` containing invalid UTF-8, may result in the return value
+/// also containing invalid UTF-8, if relevant.
+///
+/// * `str::as_bytes`
+/// * `str::as_bytes_mut`
+/// * `str::as_str`
+/// * `str::as_ptr`
+/// * `str::as_mut_ptr`
+/// * `str::bytes`
+/// * `str::into_string`
+/// * `str::into_boxed_bytes`
+/// * `str::len`
+/// * `<str as AsRef<[u8]>>::as_ref`
+/// * `<str as AsRef<str>>::as_ref`
+/// * `<str as AsMut<str>>::as_mut`
+/// * `<str as Borrow<str>>::borrow`
+/// * `<str as BorrowMut<str>>::borrow_mut`
+/// * `<Box<str> as Clone>::clone`
+/// * `<Box<str> as Clone>::clone_from`
 #[stable(feature = "rust1", since = "1.0.0")]
 mod prim_str {}