Auto merge of #25009 - alexcrichton:less-buffered-stream, r=aturon

As pointed out in #17136 the semantics of a `BufStream` aren't always what one
expects, and it looks like other [languages like C#][c-sharp] implement a
buffered stream with only one underlying buffer. For now this commit
destabilizes the primitive in the `std::io` module to give us some more time in
figuring out what to do with it.

[c-sharp]: https://msdn.microsoft.com/en-us/library/system.io.bufferedstream%28v=vs.110%29.aspx

[breaking-change]

src/libstd/io/buffered.rs

@@ -433,15 +433,19 @@ impl<W: Read + Write> Read for InternalBufWriter<W> {
 /// infrequent calls to `read` and `write` on the underlying `Read+Write`.
 ///
 /// The output buffer will be written out when this stream is dropped.
-#[stable(feature = "rust1", since = "1.0.0")]
+#[unstable(feature = "buf_stream",
+           reason = "unsure about semantics of buffering two directions, \
+                     leading to issues like #17136")]
 pub struct BufStream<S: Write> {
     inner: BufReader<InternalBufWriter<S>>
 }
 
+#[unstable(feature = "buf_stream",
+           reason = "unsure about semantics of buffering two directions, \
+                     leading to issues like #17136")]
 impl<S: Read + Write> BufStream<S> {
     /// Creates a new buffered stream with explicitly listed capacities for the
     /// reader/writer buffer.
-    #[stable(feature = "rust1", since = "1.0.0")]
     pub fn with_capacities(reader_cap: usize, writer_cap: usize, inner: S)
                            -> BufStream<S> {
         let writer = BufWriter::with_capacity(writer_cap, inner);
@@ -452,13 +456,11 @@ impl<S: Read + Write> BufStream<S> {
 
     /// Creates a new buffered stream with the default reader/writer buffer
     /// capacities.
-    #[stable(feature = "rust1", since = "1.0.0")]
     pub fn new(inner: S) -> BufStream<S> {
         BufStream::with_capacities(DEFAULT_BUF_SIZE, DEFAULT_BUF_SIZE, inner)
     }
 
     /// Gets a reference to the underlying stream.
-    #[stable(feature = "rust1", since = "1.0.0")]
     pub fn get_ref(&self) -> &S {
         let InternalBufWriter(ref w) = self.inner.inner;
         w.get_ref()
@@ -470,7 +472,6 @@ impl<S: Read + Write> BufStream<S> {
     ///
     /// It is inadvisable to read directly from or write directly to the
     /// underlying stream.
-    #[stable(feature = "rust1", since = "1.0.0")]
     pub fn get_mut(&mut self) -> &mut S {
         let InternalBufWriter(ref mut w) = self.inner.inner;
         w.get_mut()
@@ -480,7 +481,6 @@ impl<S: Read + Write> BufStream<S> {
     ///
     /// The internal write buffer is written out before returning the stream.
     /// Any leftover data in the read buffer is lost.
-    #[stable(feature = "rust1", since = "1.0.0")]
     pub fn into_inner(self) -> Result<S, IntoInnerError<BufStream<S>>> {
         let BufReader { inner: InternalBufWriter(w), buf, pos, cap } = self.inner;
         w.into_inner().map_err(|IntoInnerError(w, e)| {
@@ -491,20 +491,26 @@ impl<S: Read + Write> BufStream<S> {
     }
 }
 
-#[stable(feature = "rust1", since = "1.0.0")]
+#[unstable(feature = "buf_stream",
+           reason = "unsure about semantics of buffering two directions, \
+                     leading to issues like #17136")]
 impl<S: Read + Write> BufRead for BufStream<S> {
     fn fill_buf(&mut self) -> io::Result<&[u8]> { self.inner.fill_buf() }
     fn consume(&mut self, amt: usize) { self.inner.consume(amt) }
 }
 
-#[stable(feature = "rust1", since = "1.0.0")]
+#[unstable(feature = "buf_stream",
+           reason = "unsure about semantics of buffering two directions, \
+                     leading to issues like #17136")]
 impl<S: Read + Write> Read for BufStream<S> {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.read(buf)
     }
 }
 
-#[stable(feature = "rust1", since = "1.0.0")]
+#[unstable(feature = "buf_stream",
+           reason = "unsure about semantics of buffering two directions, \
+                     leading to issues like #17136")]
 impl<S: Read + Write> Write for BufStream<S> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.inner.inner.get_mut().write(buf)
@@ -514,7 +520,9 @@ impl<S: Read + Write> Write for BufStream<S> {
     }
 }
 
-#[stable(feature = "rust1", since = "1.0.0")]
+#[unstable(feature = "buf_stream",
+           reason = "unsure about semantics of buffering two directions, \
+                     leading to issues like #17136")]
 impl<S: Write> fmt::Debug for BufStream<S> where S: fmt::Debug {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
         let reader = &self.inner;