BufWriter: Make the soundness of BorrowedBuf usage clearer.

The previous safety comment was outdated as it was written before
`BorrowedBuf::set_init` was changed to be a boolean. It also failed
to address the possibility that `flush_buf` invalidated the
assumption.

Simplify the implementation of `flush_buf` to more obviously preserve
the spare capacity, and document the need to preserve the spare
capacity where necessary.

Author: briansmith

library/alloc/src/vec/mod.rs

@@ -1784,6 +1784,9 @@ impl<T, A: Allocator> Vec<T, A> {
     /// [`drain`]: Vec::drain
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn truncate(&mut self, len: usize) {
+        // SAFETY: `BufWriter::flush_buf` assumes that this preserves the spare
+        // capacity.
+
         // This is safe because:
         //
         // * the slice passed to `drop_in_place` is valid; the `len > self.len`
@@ -1857,6 +1860,9 @@ impl<T, A: Allocator> Vec<T, A> {
     #[rustc_diagnostic_item = "vec_as_mut_slice"]
     #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
     pub const fn as_mut_slice(&mut self) -> &mut [T] {
+        // SAFETY: `BufWriter::flush_buf` assumes that this preserves the spare
+        // capacity.
+
         // 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 * size_of::<T>` <=

library/std/src/io/buffered/bufwriter.rs

@@ -193,6 +193,9 @@ impl<W: ?Sized + Write> BufWriter<W> {
     /// `write`), any 0-length writes from `inner` must be reported as i/o
     /// errors from this method.
     pub(in crate::io) fn flush_buf(&mut self) -> io::Result<()> {
+        // SAFETY: `<BufWriter as BufferedWriterSpec>::copy_from` assumes this
+        // preserves `self.buf`'s spare capacity.
+
         /// Helper struct to ensure the buffer is updated after all the writes
         /// are complete. It tracks the number of written bytes and drains them
         /// all from the front of the buffer when dropped.
@@ -225,7 +228,15 @@ impl<W: ?Sized + Write> BufWriter<W> {
         impl Drop for BufGuard<'_> {
             fn drop(&mut self) {
                 if self.written > 0 {
-                    self.buffer.drain(..self.written);
+                    // Like `self.buffer.drain(..self.written)` but more obviously
+                    // preserving the spare capacity; see note above.
+                    let new_len = self.buffer.len() - self.written;
+                    // SAFETY: Assumes `<&mut [u8]>::copy_within` never writes
+                    // outside of the slice, so it preserves the spare capacity.
+                    self.buffer.as_mut_slice().copy_within(self.written.., 0);
+                    // SAFETY: Assumes `Vec::truncate` preserves the spare
+                    // capacity.
+                    self.buffer.truncate(new_len);
                 }
             }
         }

library/std/src/io/copy.rs

@@ -221,7 +221,9 @@ impl<I: Write + ?Sized> BufferedWriterSpec for BufWriter<I> {
             let mut read_buf: BorrowedBuf<'_> = buf.spare_capacity_mut().into();
 
             if init {
-                // SAFETY: init is either 0 or the init_len from the previous iteration.
+                // SAFETY: `init` is only true after `reader` initializes
+                // `read_buf`. `flush_buf` preserves the spare capacity, so it
+                // is OK to persist this across `flush_buf` calls.
                 unsafe { read_buf.set_init() };
             }