1 use crate::std::fmt; 2 use crate::std::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 pub struct LineWriter<W: ?Sized + Write> { 67 inner: BufWriter<W>, 68 } 69 70 impl<W: Write> LineWriter<W> { 71 /// Creates a new `LineWriter`. 72 /// 73 /// # Examples 74 /// 75 /// ```no_run 76 /// use std::fs::File; 77 /// use std::io::LineWriter; 78 /// 79 /// fn main() -> std::io::Result<()> { 80 /// let file = File::create("poem.txt")?; 81 /// let file = LineWriter::new(file); 82 /// Ok(()) 83 /// } 84 /// ``` 85 pub fn new(inner: W) -> LineWriter<W> { 86 // Lines typically aren't that long, don't use a giant buffer 87 LineWriter::with_capacity(1024, inner) 88 } 89 90 /// Creates a new `LineWriter` with at least the specified capacity for the 91 /// internal buffer. 92 /// 93 /// # Examples 94 /// 95 /// ```no_run 96 /// use std::fs::File; 97 /// use std::io::LineWriter; 98 /// 99 /// fn main() -> std::io::Result<()> { 100 /// let file = File::create("poem.txt")?; 101 /// let file = LineWriter::with_capacity(100, file); 102 /// Ok(()) 103 /// } 104 /// ``` 105 pub fn with_capacity(capacity: usize, inner: W) -> LineWriter<W> { 106 LineWriter { 107 inner: BufWriter::with_capacity(capacity, inner), 108 } 109 } 110 111 /// Gets a mutable reference to the underlying writer. 112 /// 113 /// Caution must be taken when calling methods on the mutable reference 114 /// returned as extra writes could corrupt the output stream. 115 /// 116 /// # Examples 117 /// 118 /// ```no_run 119 /// use std::fs::File; 120 /// use std::io::LineWriter; 121 /// 122 /// fn main() -> std::io::Result<()> { 123 /// let file = File::create("poem.txt")?; 124 /// let mut file = LineWriter::new(file); 125 /// 126 /// // we can use reference just like file 127 /// let reference = file.get_mut(); 128 /// Ok(()) 129 /// } 130 /// ``` 131 pub fn get_mut(&mut self) -> &mut W { 132 self.inner.get_mut() 133 } 134 135 /// Unwraps this `LineWriter`, returning the underlying writer. 136 /// 137 /// The internal buffer is written out before returning the writer. 138 /// 139 /// # Errors 140 /// 141 /// An [`Err`] will be returned if an error occurs while flushing the buffer. 142 /// 143 /// # Examples 144 /// 145 /// ```no_run 146 /// use std::fs::File; 147 /// use std::io::LineWriter; 148 /// 149 /// fn main() -> std::io::Result<()> { 150 /// let file = File::create("poem.txt")?; 151 /// 152 /// let writer: LineWriter<File> = LineWriter::new(file); 153 /// 154 /// let file: File = writer.into_inner()?; 155 /// Ok(()) 156 /// } 157 /// ``` 158 pub fn into_inner(self) -> Result<W, IntoInnerError<LineWriter<W>>> { 159 self.inner 160 .into_inner() 161 .map_err(|err| err.new_wrapped(|inner| LineWriter { inner })) 162 } 163 } 164 165 impl<W: ?Sized + Write> LineWriter<W> { 166 /// Gets a reference to the underlying writer. 167 /// 168 /// # Examples 169 /// 170 /// ```no_run 171 /// use std::fs::File; 172 /// use std::io::LineWriter; 173 /// 174 /// fn main() -> std::io::Result<()> { 175 /// let file = File::create("poem.txt")?; 176 /// let file = LineWriter::new(file); 177 /// 178 /// let reference = file.get_ref(); 179 /// Ok(()) 180 /// } 181 /// ``` 182 pub fn get_ref(&self) -> &W { 183 self.inner.get_ref() 184 } 185 } 186 187 impl<W: ?Sized + Write> Write for LineWriter<W> { 188 fn write(&mut self, buf: &[u8]) -> io::Result<usize> { 189 LineWriterShim::new(&mut self.inner).write(buf) 190 } 191 192 fn flush(&mut self) -> io::Result<()> { 193 self.inner.flush() 194 } 195 196 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> { 197 LineWriterShim::new(&mut self.inner).write_vectored(bufs) 198 } 199 200 fn is_write_vectored(&self) -> bool { 201 self.inner.is_write_vectored() 202 } 203 204 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { 205 LineWriterShim::new(&mut self.inner).write_all(buf) 206 } 207 208 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { 209 LineWriterShim::new(&mut self.inner).write_all_vectored(bufs) 210 } 211 212 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> { 213 LineWriterShim::new(&mut self.inner).write_fmt(fmt) 214 } 215 } 216 217 impl<W: ?Sized + Write> fmt::Debug for LineWriter<W> 218 where 219 W: fmt::Debug, 220 { 221 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { 222 fmt.debug_struct("LineWriter") 223 .field("writer", &self.get_ref()) 224 .field( 225 "buffer", 226 &format_args!("{}/{}", self.inner.buffer().len(), self.inner.capacity()), 227 ) 228 .finish_non_exhaustive() 229 } 230 } 231