Auto merge of #68558 - HeroicKatora:buf-writer-capacity, r=alexcrichton

Add a method to query the capacity of a BufWriter and BufReader

Besides the obvious of retrieving the parameter used to construct the writer, this method allows consumers to control the number of `flush` calls during write operations. For `BufReader` it gives an upper bound on the returned buffer in `fill_buf` which might influence the allocation behaviour of a consumer.

src/libstd/io/buffered.rs

@@ -179,6 +179,30 @@ impl<R> BufReader<R> {
         &self.buf[self.pos..self.cap]
     }
 
+    /// Returns the number of bytes the internal buffer can hold at once.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// #![feature(buffered_io_capacity)]
+    /// use std::io::{BufReader, BufRead};
+    /// use std::fs::File;
+    ///
+    /// fn main() -> std::io::Result<()> {
+    ///     let f = File::open("log.txt")?;
+    ///     let mut reader = BufReader::new(f);
+    ///
+    ///     let capacity = reader.capacity();
+    ///     let buffer = reader.fill_buf()?;
+    ///     assert!(buffer.len() <= capacity);
+    ///     Ok(())
+    /// }
+    /// ```
+    #[unstable(feature = "buffered_io_capacity", issue = "68558")]
+    pub fn capacity(&self) -> usize {
+        self.buf.len()
+    }
+
     /// Unwraps this `BufReader<R>`, returning the underlying reader.
     ///
     /// Note that any leftover data in the internal buffer is lost. Therefore,
@@ -576,6 +600,27 @@ impl<W: Write> BufWriter<W> {
         &self.buf
     }
 
+    /// Returns the number of bytes the internal buffer can hold without flushing.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// #![feature(buffered_io_capacity)]
+    /// use std::io::BufWriter;
+    /// use std::net::TcpStream;
+    ///
+    /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
+    ///
+    /// // Check the capacity of the inner buffer
+    /// let capacity = buf_writer.capacity();
+    /// // Calculate how many bytes can be written without flushing
+    /// let without_flush = capacity - buf_writer.buffer().len();
+    /// ```
+    #[unstable(feature = "buffered_io_capacity", issue = "68558")]
+    pub fn capacity(&self) -> usize {
+        self.buf.capacity()
+    }
+
     /// Unwraps this `BufWriter<W>`, returning the underlying writer.
     ///
     /// The buffer is written out before returning the writer.