liballoc/{Vec,String}: safety comments for slice methods

Author: npry

library/alloc/src/string.rs

@@ -1079,6 +1079,8 @@ impl String {
     #[cfg_attr(not(test), rustc_diagnostic_item = "string_as_str")]
     #[rustc_const_unstable(feature = "const_vec_string_slice", issue = "129041")]
     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()) }
     }
 
@@ -1100,6 +1102,8 @@ impl String {
     #[cfg_attr(not(test), rustc_diagnostic_item = "string_as_mut_str")]
     #[rustc_const_unstable(feature = "const_vec_string_slice", issue = "129041")]
     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()) }
     }
 

library/alloc/src/vec/mod.rs

@@ -1551,6 +1551,19 @@ impl<T, A: Allocator> Vec<T, A> {
     #[cfg_attr(not(test), rustc_diagnostic_item = "vec_as_slice")]
     #[rustc_const_unstable(feature = "const_vec_string_slice", issue = "129041")]
     pub const fn as_slice(&self) -> &[T] {
+        // SAFETY: `slice::from_raw_parts` requires pointee is a contiguous, aligned buffer of size
+        // `len` containing properly-initialized `T`s. Data must not be mutated for the returned
+        // lifetime. Further, `len * mem::size_of::<T>` <= `ISIZE::MAX`, and allocation does not
+        // "wrap" through overflowing memory addresses.
+        //
+        // * Vec API guarantees that self.buf:
+        //      * contains only properly-initialized items within 0..len
+        //      * is aligned, contiguous, and valid for `len` reads
+        //      * obeys size and address-wrapping constraints
+        //  
+        // * We only construct `&mut` references to `self.buf` through `&mut self` methods; borrow-
+        //   check ensures that it is not possible to mutably alias `self.buf` within the         
+        //   returned lifetime.
         unsafe { slice::from_raw_parts(self.as_ptr(), self.len) }
     }
 
@@ -1570,6 +1583,19 @@ impl<T, A: Allocator> Vec<T, A> {
     #[cfg_attr(not(test), rustc_diagnostic_item = "vec_as_mut_slice")]
     #[rustc_const_unstable(feature = "const_vec_string_slice", issue = "129041")]
     pub const fn as_mut_slice(&mut self) -> &mut [T] {
+        // SAFETY: `slice::from_raw_parts_mut` requires pointee is a contiguous, aligned buffer of
+        // size `len` containing properly-initialized `T`s. Data must not be accessed through any
+        // other pointer for the returned lifetime. Further, `len * mem::size_of::<T>` <=
+        // `ISIZE::MAX` and allocation does not "wrap" through overflowing memory addresses.
+        //
+        // * Vec API guarantees that self.buf:
+        //      * contains only properly-initialized items within 0..len
+        //      * is aligned, contiguous, and valid for `len` reads
+        //      * obeys size and address-wrapping constraints
+        //  
+        // * We only construct references to `self.buf` through `&self` and `&mut self` methods; 
+        //   borrow-check ensures that it is not possible to construct a reference to `self.buf`
+        //   within the returned lifetime.
         unsafe { slice::from_raw_parts_mut(self.as_mut_ptr(), self.len) }
     }