Auto merge of #79673 - ijackson:intoinnerintoinnererror, r=m-ou-se

Provide IntoInnerError::into_parts

Hi.  This is an updated version of the IntoInnerError bits of my previous portmanteau MR #78689.  Thanks to `@jyn514` and `@m-ou-se` for helpful comments there.

I have made this insta-stable since it seems like it will probably be uncontroversial, but that is definitely something that someone from the libs API team should be aware of and explicitly consider.

I included a tangentially-related commit providing documentation of the buffer full behaviiour of `&mut [u8] as Write`; the behaviour I am documenting is relied on by the doctest for `into_parts`.

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

@@ -126,6 +126,51 @@ pub fn error(&self) -> &Error {
     pub fn into_inner(self) -> W {
         self.0
     }
+
+    /// Consumes the [`IntoInnerError`] and returns the error which caused the call to
+    /// [`BufWriter::into_inner()`] to fail.  Unlike `error`, this can be used to
+    /// obtain ownership of the underlying error.
+    ///
+    /// # Example
+    /// ```
+    /// #![feature(io_into_inner_error_parts)]
+    /// use std::io::{BufWriter, ErrorKind, Write};
+    ///
+    /// let mut not_enough_space = [0u8; 10];
+    /// let mut stream = BufWriter::new(not_enough_space.as_mut());
+    /// write!(stream, "this cannot be actually written").unwrap();
+    /// let into_inner_err = stream.into_inner().expect_err("now we discover it's too small");
+    /// let err = into_inner_err.into_error();
+    /// assert_eq!(err.kind(), ErrorKind::WriteZero);
+    /// ```
+    #[unstable(feature = "io_into_inner_error_parts", issue = "79704")]
+    pub fn into_error(self) -> Error {
+        self.1
+    }
+
+    /// Consumes the [`IntoInnerError`] and returns the error which caused the call to
+    /// [`BufWriter::into_inner()`] to fail, and the underlying writer.
+    ///
+    /// This can be used to simply obtain ownership of the underlying error; it can also be used for
+    /// advanced error recovery.
+    ///
+    /// # Example
+    /// ```
+    /// #![feature(io_into_inner_error_parts)]
+    /// use std::io::{BufWriter, ErrorKind, Write};
+    ///
+    /// let mut not_enough_space = [0u8; 10];
+    /// let mut stream = BufWriter::new(not_enough_space.as_mut());
+    /// write!(stream, "this cannot be actually written").unwrap();
+    /// let into_inner_err = stream.into_inner().expect_err("now we discover it's too small");
+    /// let (err, recovered_writer) = into_inner_err.into_parts();
+    /// assert_eq!(err.kind(), ErrorKind::WriteZero);
+    /// assert_eq!(recovered_writer.buffer(), b"t be actually written");
+    /// ```
+    #[unstable(feature = "io_into_inner_error_parts", issue = "79704")]
+    pub fn into_parts(self) -> (Error, W) {
+        (self.1, self.0)
+    }
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]

library/std/src/io/impls.rs

@@ -306,6 +306,10 @@ fn consume(&mut self, amt: usize) {
 ///
 /// Note that writing updates the slice to point to the yet unwritten part.
 /// The slice will be empty when it has been completely overwritten.
+///
+/// If the number of bytes to be written exceeds the size of the slice, write operations will
+/// return short writes: ultimately, `Ok(0)`; in this situation, `write_all` returns an error of
+/// kind `ErrorKind::WriteZero`.
 #[stable(feature = "rust1", since = "1.0.0")]
 impl Write for &mut [u8] {
     #[inline]