2 use crate::io::{self, buffered::LineWriterShim, BufWriter, IntoInnerError, IoSlice, Write};
4 /// Wraps a writer and buffers output to it, flushing whenever a newline
5 /// (`0x0a`, `'\n'`) is detected.
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.
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.
16 /// If there's still a partial line in the buffer when the `LineWriter` is
17 /// dropped, it will flush those contents.
21 /// We can use `LineWriter` to write one line at a time, significantly
22 /// reducing the number of actual writes to the file.
25 /// use std::fs::{self, File};
26 /// use std::io::prelude::*;
27 /// use std::io::LineWriter;
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.";
36 /// let file = File::create("poem.txt")?;
37 /// let mut file = LineWriter::new(file);
39 /// file.write_all(b"I shall be telling this with a sigh")?;
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")?;
46 /// fs::read_to_string("poem.txt")?,
47 /// "I shall be telling this with a sigh\n",
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.")?;
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
61 /// // Confirm the whole poem was written.
62 /// assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]);
66 #[stable(feature = "rust1", since = "1.0.0")]
67 pub struct LineWriter<W: Write> {
71 impl<W: Write> LineWriter<W> {
72 /// Creates a new `LineWriter`.
77 /// use std::fs::File;
78 /// use std::io::LineWriter;
80 /// fn main() -> std::io::Result<()> {
81 /// let file = File::create("poem.txt")?;
82 /// let file = LineWriter::new(file);
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)
92 /// Creates a new `LineWriter` with a specified capacity for the internal
98 /// use std::fs::File;
99 /// use std::io::LineWriter;
101 /// fn main() -> std::io::Result<()> {
102 /// let file = File::create("poem.txt")?;
103 /// let file = LineWriter::with_capacity(100, file);
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) }
112 /// Gets a reference to the underlying writer.
117 /// use std::fs::File;
118 /// use std::io::LineWriter;
120 /// fn main() -> std::io::Result<()> {
121 /// let file = File::create("poem.txt")?;
122 /// let file = LineWriter::new(file);
124 /// let reference = file.get_ref();
128 #[stable(feature = "rust1", since = "1.0.0")]
129 pub fn get_ref(&self) -> &W {
133 /// Gets a mutable reference to the underlying writer.
135 /// Caution must be taken when calling methods on the mutable reference
136 /// returned as extra writes could corrupt the output stream.
141 /// use std::fs::File;
142 /// use std::io::LineWriter;
144 /// fn main() -> std::io::Result<()> {
145 /// let file = File::create("poem.txt")?;
146 /// let mut file = LineWriter::new(file);
148 /// // we can use reference just like file
149 /// let reference = file.get_mut();
153 #[stable(feature = "rust1", since = "1.0.0")]
154 pub fn get_mut(&mut self) -> &mut W {
158 /// Unwraps this `LineWriter`, returning the underlying writer.
160 /// The internal buffer is written out before returning the writer.
164 /// An [`Err`] will be returned if an error occurs while flushing the buffer.
169 /// use std::fs::File;
170 /// use std::io::LineWriter;
172 /// fn main() -> std::io::Result<()> {
173 /// let file = File::create("poem.txt")?;
175 /// let writer: LineWriter<File> = LineWriter::new(file);
177 /// let file: File = writer.into_inner()?;
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 }))
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)
193 fn flush(&mut self) -> io::Result<()> {
197 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
198 LineWriterShim::new(&mut self.inner).write_vectored(bufs)
201 fn is_write_vectored(&self) -> bool {
202 self.inner.is_write_vectored()
205 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
206 LineWriterShim::new(&mut self.inner).write_all(buf)
209 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
210 LineWriterShim::new(&mut self.inner).write_all_vectored(bufs)
213 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
214 LineWriterShim::new(&mut self.inner).write_fmt(fmt)
218 #[stable(feature = "rust1", since = "1.0.0")]
219 impl<W: Write> fmt::Debug for LineWriter<W>
223 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
224 fmt.debug_struct("LineWriter")
225 .field("writer", &self.get_ref())
228 &format_args!("{}/{}", self.inner.buffer().len(), self.inner.capacity()),
230 .finish_non_exhaustive()