bufwriter::WriterPanicked: Provide panicking example

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 24 insertions, 0 deletions

diff --git a/library/std/src/io/buffered/bufwriter.rs b/library/std/src/io/buffered/bufwriter.rs
index a1c5f22d417..94e625b9410 100644
--- a/library/std/src/io/buffered/bufwriter.rs
+++ b/library/std/src/io/buffered/bufwriter.rs
@@ -324,6 +324,30 @@ impl<W: Write> BufWriter<W> {
 #[unstable(feature = "bufwriter_into_raw_parts", issue = "none")]
 /// Error returned for the buffered data from `BufWriter::into_raw_parts`, when the underlying
 /// writer has previously panicked.  Contains the (possibly partly written) buffered data.
+///
+/// # Example
+///
+/// ```
+/// #![feature(bufwriter_into_raw_parts)]
+/// use std::io::{self, BufWriter, Write};
+/// use std::panic::{catch_unwind, AssertUnwindSafe};
+///
+/// struct PanickingWriter;
+/// impl Write for PanickingWriter {
+///   fn write(&mut self, buf: &[u8]) -> io::Result<usize> { panic!() }
+///   fn flush(&mut self) -> io::Result<()> { panic!() }
+/// }
+///
+/// let mut stream = BufWriter::new(PanickingWriter);
+/// write!(stream, "some data").unwrap();
+/// let result = catch_unwind(AssertUnwindSafe(|| {
+///     stream.flush().unwrap()
+/// }));
+/// assert!(result.is_err());
+/// let (recovered_writer, buffered_data) = stream.into_raw_parts();
+/// assert!(matches!(recovered_writer, PanickingWriter));
+/// assert_eq!(buffered_data.unwrap_err().into_inner(), b"some data");
+/// ```
 pub struct WriterPanicked {
     buf: Vec<u8>,
 }