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

   1 use crate::fmt;
   2 use crate::io::{self, buffered::LineWriterShim, BufWriter, IntoInnerError, IoSlice, Write};
   3
   4 /// Wraps a writer and buffers output to it, flushing whenever a newline
   5 /// (`0x0a`, `'\n'`) is detected.
   6 ///
   7 /// The [`BufWriter`] struct wraps a writer and buffers its output.
   8 /// But it only does this batched write when it goes out of scope, or when the
   9 /// internal buffer is full. Sometimes, you'd prefer to write each line as it's
  10 /// completed, rather than the entire buffer at once. Enter `LineWriter`. It
  11 /// does exactly that.
  12 ///
  13 /// Like [`BufWriter`], a `LineWriter`’s buffer will also be flushed when the
  14 /// `LineWriter` goes out of scope or when its internal buffer is full.
  15 ///
  16 /// If there's still a partial line in the buffer when the `LineWriter` is
  17 /// dropped, it will flush those contents.
  18 ///
  19 /// # Examples
  20 ///
  21 /// We can use `LineWriter` to write one line at a time, significantly
  22 /// reducing the number of actual writes to the file.
  23 ///
  24 /// ```no_run
  25 /// use std::fs::{self, File};
  26 /// use std::io::prelude::*;
  27 /// use std::io::LineWriter;
  28 ///
  29 /// fn main() -> std::io::Result<()> {
  30 ///     let road_not_taken = b"I shall be telling this with a sigh
  31 /// Somewhere ages and ages hence:
  32 /// Two roads diverged in a wood, and I -
  33 /// I took the one less traveled by,
  34 /// And that has made all the difference.";
  35 ///
  36 ///     let file = File::create("poem.txt")?;
  37 ///     let mut file = LineWriter::new(file);
  38 ///
  39 ///     file.write_all(b"I shall be telling this with a sigh")?;
  40 ///
  41 ///     // No bytes are written until a newline is encountered (or
  42 ///     // the internal buffer is filled).
  43 ///     assert_eq!(fs::read_to_string("poem.txt")?, "");
  44 ///     file.write_all(b"\n")?;
  45 ///     assert_eq!(
  46 ///         fs::read_to_string("poem.txt")?,
  47 ///         "I shall be telling this with a sigh\n",
  48 ///     );
  49 ///
  50 ///     // Write the rest of the poem.
  51 ///     file.write_all(b"Somewhere ages and ages hence:
  52 /// Two roads diverged in a wood, and I -
  53 /// I took the one less traveled by,
  54 /// And that has made all the difference.")?;
  55 ///
  56 ///     // The last line of the poem doesn't end in a newline, so
  57 ///     // we have to flush or drop the `LineWriter` to finish
  58 ///     // writing.
  59 ///     file.flush()?;
  60 ///
  61 ///     // Confirm the whole poem was written.
  62 ///     assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]);
  63 ///     Ok(())
  64 /// }
  65 /// ```
  66 #[stable(feature = "rust1", since = "1.0.0")]
  67 pub struct LineWriter<W: Write> {
  68     inner: BufWriter<W>,
  69 }
  70
  71 impl<W: Write> LineWriter<W> {
  72     /// Creates a new `LineWriter`.
  73     ///
  74     /// # Examples
  75     ///
  76     /// ```no_run
  77     /// use std::fs::File;
  78     /// use std::io::LineWriter;
  79     ///
  80     /// fn main() -> std::io::Result<()> {
  81     ///     let file = File::create("poem.txt")?;
  82     ///     let file = LineWriter::new(file);
  83     ///     Ok(())
  84     /// }
  85     /// ```
  86     #[stable(feature = "rust1", since = "1.0.0")]
  87     pub fn new(inner: W) -> LineWriter<W> {
  88         // Lines typically aren't that long, don't use a giant buffer
  89         LineWriter::with_capacity(1024, inner)
  90     }
  91
  92     /// Creates a new `LineWriter` with at least the specified capacity for the
  93     /// internal buffer.
  94     ///
  95     /// # Examples
  96     ///
  97     /// ```no_run
  98     /// use std::fs::File;
  99     /// use std::io::LineWriter;
 100     ///
 101     /// fn main() -> std::io::Result<()> {
 102     ///     let file = File::create("poem.txt")?;
 103     ///     let file = LineWriter::with_capacity(100, file);
 104     ///     Ok(())
 105     /// }
 106     /// ```
 107     #[stable(feature = "rust1", since = "1.0.0")]
 108     pub fn with_capacity(capacity: usize, inner: W) -> LineWriter<W> {
 109         LineWriter { inner: BufWriter::with_capacity(capacity, inner) }
 110     }
 111
 112     /// Gets a reference to the underlying writer.
 113     ///
 114     /// # Examples
 115     ///
 116     /// ```no_run
 117     /// use std::fs::File;
 118     /// use std::io::LineWriter;
 119     ///
 120     /// fn main() -> std::io::Result<()> {
 121     ///     let file = File::create("poem.txt")?;
 122     ///     let file = LineWriter::new(file);
 123     ///
 124     ///     let reference = file.get_ref();
 125     ///     Ok(())
 126     /// }
 127     /// ```
 128     #[stable(feature = "rust1", since = "1.0.0")]
 129     pub fn get_ref(&self) -> &W {
 130         self.inner.get_ref()
 131     }
 132
 133     /// Gets a mutable reference to the underlying writer.
 134     ///
 135     /// Caution must be taken when calling methods on the mutable reference
 136     /// returned as extra writes could corrupt the output stream.
 137     ///
 138     /// # Examples
 139     ///
 140     /// ```no_run
 141     /// use std::fs::File;
 142     /// use std::io::LineWriter;
 143     ///
 144     /// fn main() -> std::io::Result<()> {
 145     ///     let file = File::create("poem.txt")?;
 146     ///     let mut file = LineWriter::new(file);
 147     ///
 148     ///     // we can use reference just like file
 149     ///     let reference = file.get_mut();
 150     ///     Ok(())
 151     /// }
 152     /// ```
 153     #[stable(feature = "rust1", since = "1.0.0")]
 154     pub fn get_mut(&mut self) -> &mut W {
 155         self.inner.get_mut()
 156     }
 157
 158     /// Unwraps this `LineWriter`, returning the underlying writer.
 159     ///
 160     /// The internal buffer is written out before returning the writer.
 161     ///
 162     /// # Errors
 163     ///
 164     /// An [`Err`] will be returned if an error occurs while flushing the buffer.
 165     ///
 166     /// # Examples
 167     ///
 168     /// ```no_run
 169     /// use std::fs::File;
 170     /// use std::io::LineWriter;
 171     ///
 172     /// fn main() -> std::io::Result<()> {
 173     ///     let file = File::create("poem.txt")?;
 174     ///
 175     ///     let writer: LineWriter<File> = LineWriter::new(file);
 176     ///
 177     ///     let file: File = writer.into_inner()?;
 178     ///     Ok(())
 179     /// }
 180     /// ```
 181     #[stable(feature = "rust1", since = "1.0.0")]
 182     pub fn into_inner(self) -> Result<W, IntoInnerError<LineWriter<W>>> {
 183         self.inner.into_inner().map_err(|err| err.new_wrapped(|inner| LineWriter { inner }))
 184     }
 185 }
 186
 187 #[stable(feature = "rust1", since = "1.0.0")]
 188 impl<W: Write> Write for LineWriter<W> {
 189     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 190         LineWriterShim::new(&mut self.inner).write(buf)
 191     }
 192
 193     fn flush(&mut self) -> io::Result<()> {
 194         self.inner.flush()
 195     }
 196
 197     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 198         LineWriterShim::new(&mut self.inner).write_vectored(bufs)
 199     }
 200
 201     fn is_write_vectored(&self) -> bool {
 202         self.inner.is_write_vectored()
 203     }
 204
 205     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 206         LineWriterShim::new(&mut self.inner).write_all(buf)
 207     }
 208
 209     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 210         LineWriterShim::new(&mut self.inner).write_all_vectored(bufs)
 211     }
 212
 213     fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
 214         LineWriterShim::new(&mut self.inner).write_fmt(fmt)
 215     }
 216 }
 217
 218 #[stable(feature = "rust1", since = "1.0.0")]
 219 impl<W: Write> fmt::Debug for LineWriter<W>
 220 where
 221     W: fmt::Debug,
 222 {
 223     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 224         fmt.debug_struct("LineWriter")
 225             .field("writer", &self.get_ref())
 226             .field(
 227                 "buffer",
 228                 &format_args!("{}/{}", self.inner.buffer().len(), self.inner.capacity()),
 229             )
 230             .finish_non_exhaustive()
 231     }
 232 }