linewriter.rs - source
Description: Source of the Rust file `library/std/src/io/buffered/linewriter.rs`.

#
std/io/buffered/
linewriter.rs

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