auto merge of #18891 : erickt/rust/deprecate-as-ref, r=alexcrichton

It seems odd that the `AsRefReader`/`AsRefWriter` have the single method `by_ref()`. This creates the new traits `ByRefReader`/`ByRefWriter` and deprecates the old traits.

src/libstd/io/mod.rs

@@ -849,6 +849,7 @@ fn read_i8(&mut self) -> IoResult<i8> {
 }
 
 /// A reader which can be converted to a RefReader.
+#[deprecated = "use ByRefReader instead"]
 pub trait AsRefReader {
     /// Creates a wrapper around a mutable reference to the reader.
     ///
@@ -857,12 +858,28 @@ pub trait AsRefReader {
     fn by_ref<'a>(&'a mut self) -> RefReader<'a, Self>;
 }
 
+#[allow(deprecated)]
 impl<T: Reader> AsRefReader for T {
     fn by_ref<'a>(&'a mut self) -> RefReader<'a, T> {
         RefReader { inner: self }
     }
 }
 
+/// A reader which can be converted to a RefReader.
+pub trait ByRefReader {
+    /// Creates a wrapper around a mutable reference to the reader.
+    ///
+    /// This is useful to allow applying adaptors while still
+    /// retaining ownership of the original value.
+    fn by_ref<'a>(&'a mut self) -> RefReader<'a, Self>;
+}
+
+impl<T: Reader> ByRefReader for T {
+    fn by_ref<'a>(&'a mut self) -> RefReader<'a, T> {
+        RefReader { inner: self }
+    }
+}
+
 /// A reader which can be converted to bytes.
 pub trait BytesReader {
     /// Create an iterator that reads a single byte on
@@ -925,7 +942,7 @@ unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec<T>, start: uint, end: uint) -
 /// # fn process_input<R: Reader>(r: R) {}
 /// # fn foo() {
 /// use std::io;
-/// use std::io::AsRefReader;
+/// use std::io::ByRefReader;
 /// use std::io::util::LimitReader;
 ///
 /// let mut stream = io::stdin();
@@ -1211,6 +1228,7 @@ fn write_i8(&mut self, n: i8) -> IoResult<()> {
 }
 
 /// A writer which can be converted to a RefWriter.
+#[deprecated = "use ByRefWriter instead"]
 pub trait AsRefWriter {
     /// Creates a wrapper around a mutable reference to the writer.
     ///
@@ -1220,12 +1238,29 @@ pub trait AsRefWriter {
     fn by_ref<'a>(&'a mut self) -> RefWriter<'a, Self>;
 }
 
+#[allow(deprecated)]
 impl<T: Writer> AsRefWriter for T {
     fn by_ref<'a>(&'a mut self) -> RefWriter<'a, T> {
         RefWriter { inner: self }
     }
 }
 
+/// A writer which can be converted to a RefWriter.
+pub trait ByRefWriter {
+    /// Creates a wrapper around a mutable reference to the writer.
+    ///
+    /// This is useful to allow applying wrappers while still
+    /// retaining ownership of the original value.
+    #[inline]
+    fn by_ref<'a>(&'a mut self) -> RefWriter<'a, Self>;
+}
+
+impl<T: Writer> ByRefWriter for T {
+    fn by_ref<'a>(&'a mut self) -> RefWriter<'a, T> {
+        RefWriter { inner: self }
+    }
+}
+
 impl<'a> Writer for Box<Writer+'a> {
     #[inline]
     fn write(&mut self, buf: &[u8]) -> IoResult<()> {
@@ -1256,7 +1291,7 @@ fn flush(&mut self) -> IoResult<()> { (**self).flush() }
 /// # fn process_input<R: Reader>(r: R) {}
 /// # fn foo () {
 /// use std::io::util::TeeReader;
-/// use std::io::{stdin, MemWriter, AsRefWriter};
+/// use std::io::{stdin, MemWriter, ByRefWriter};
 ///
 /// let mut output = MemWriter::new();
 ///

src/libstd/io/util.rs

@@ -265,7 +265,7 @@ fn read(&mut self, buf: &mut [u8]) -> io::IoResult<uint> {
 
 #[cfg(test)]
 mod test {
-    use io::{MemReader, MemWriter, BufReader, AsRefReader};
+    use io::{MemReader, MemWriter, BufReader, ByRefReader};
     use io;
     use boxed::Box;
     use super::*;