Tweak the interface of std::io

* Reexport io::mem and io::buffered structs directly under io, make mem/buffered
  private modules
* Remove with_mem_writer
* Remove DEFAULT_CAPACITY and use DEFAULT_BUF_SIZE (in io::buffered)

41 files changed, 204 insertions, 180 deletions

diff --git a/doc/complement-cheatsheet.md b/doc/complement-cheatsheet.md
index 4c106a357e6..770b0ad1421 100644
--- a/doc/complement-cheatsheet.md
+++ b/doc/complement-cheatsheet.md
@@ -62,8 +62,8 @@ let reader : File = File::open(&path).unwrap_or_else(on_error);
 Use the [`lines`](http://static.rust-lang.org/doc/master/std/io/trait.Buffer.html#method.lines) method on a [`BufferedReader`](http://static.rust-lang.org/doc/master/std/io/buffered/struct.BufferedReader.html).
 
 ~~~
-use std::io::buffered::BufferedReader;
-# use std::io::mem::MemReader;
+use std::io::BufferedReader;
+# use std::io::MemReader;
 
 # let reader = MemReader::new(~[]);
 
diff --git a/doc/guide-conditions.md b/doc/guide-conditions.md
index d7b6608ad45..3099cc62b1a 100644
--- a/doc/guide-conditions.md
+++ b/doc/guide-conditions.md
@@ -46,12 +46,11 @@ An example program that does this task reads like this:
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
@@ -245,13 +244,12 @@ and trapping its exit status using `task::try`:
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 use std::task;
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
@@ -350,12 +348,11 @@ but similarly clear as the version that used `fail!` in the logic where the erro
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
@@ -420,12 +417,11 @@ and replaces bad input lines with the pair `(-1,-1)`:
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
@@ -496,12 +492,11 @@ Changing the condition's return type from `(int,int)` to `Option<(int,int)>` wil
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
@@ -582,12 +577,11 @@ This can be encoded in the handler API by introducing a helper type: `enum Malfo
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
 use std::io::File;
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
@@ -707,12 +701,11 @@ a second condition and a helper function will suffice:
 ~~~~
 # #[allow(unused_imports)];
 # extern mod extra;
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 # mod BufferedReader {
 #     use std::io::File;
-#     use std::io::mem::MemReader;
-#     use std::io::buffered::BufferedReader;
+#     use std::io::MemReader;
+#     use std::io::BufferedReader;
 #     static s : &'static [u8] = bytes!("1 2\n\
 #                                        34 56\n\
 #                                        789 123\n\
diff --git a/src/compiletest/errors.rs b/src/compiletest/errors.rs
index b15bf73c193..3a6b1666c1e 100644
--- a/src/compiletest/errors.rs
+++ b/src/compiletest/errors.rs
@@ -8,8 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use std::io::buffered::BufferedReader;
-use std::io::File;
+use std::io::{BufferedReader, File};
 
 pub struct ExpectedError { line: uint, kind: ~str, msg: ~str }
 
diff --git a/src/compiletest/header.rs b/src/compiletest/header.rs
index d4a4f38cc63..3caddb2af49 100644
--- a/src/compiletest/header.rs
+++ b/src/compiletest/header.rs
@@ -103,8 +103,7 @@ pub fn is_test_ignored(config: &config, testfile: &Path) -> bool {
 }
 
 fn iter_header(testfile: &Path, it: |&str| -> bool) -> bool {
-    use std::io::buffered::BufferedReader;
-    use std::io::File;
+    use std::io::{BufferedReader, File};
 
     let mut rdr = BufferedReader::new(File::open(testfile).unwrap());
     for ln in rdr.lines() {
diff --git a/src/libextra/ebml.rs b/src/libextra/ebml.rs
index 3798ed8617e..9feaa327324 100644
--- a/src/libextra/ebml.rs
+++ b/src/libextra/ebml.rs
@@ -582,7 +582,7 @@ pub mod writer {
     use std::clone::Clone;
     use std::io;
     use std::io::{Writer, Seek};
-    use std::io::mem::MemWriter;
+    use std::io::MemWriter;
     use std::io::extensions::u64_to_be_bytes;
 
     // ebml writing
@@ -935,7 +935,7 @@ mod tests {
     use serialize::Encodable;
     use serialize;
 
-    use std::io::mem::MemWriter;
+    use std::io::MemWriter;
     use std::option::{None, Option, Some};
 
     #[test]
diff --git a/src/libextra/json.rs b/src/libextra/json.rs
index 68eb4e1e5ac..67a15ac02fd 100644
--- a/src/libextra/json.rs
+++ b/src/libextra/json.rs
@@ -21,7 +21,7 @@ use std::cast::transmute;
 use std::f64;
 use std::hashmap::HashMap;
 use std::io;
-use std::io::mem::MemWriter;
+use std::io::MemWriter;
 use std::num;
 use std::str;
 use std::to_str;
@@ -1506,7 +1506,7 @@ mod tests {
     }
 
     fn with_str_writer(f: |&mut io::Writer|) -> ~str {
-        use std::io::mem::MemWriter;
+        use std::io::MemWriter;
         use std::str;
 
         let mut m = MemWriter::new();
diff --git a/src/libextra/stats.rs b/src/libextra/stats.rs
index 1d57e94035a..629d826c37b 100644
--- a/src/libextra/stats.rs
+++ b/src/libextra/stats.rs
@@ -998,7 +998,7 @@ mod tests {
     #[test]
     fn test_boxplot_nonpositive() {
         fn t(s: &Summary, expected: ~str) {
-            use std::io::mem::MemWriter;
+            use std::io::MemWriter;
             let mut m = MemWriter::new();
             write_boxplot(&mut m as &mut io::Writer, s, 30);
             let out = str::from_utf8_owned(m.unwrap());
diff --git a/src/libextra/test.rs b/src/libextra/test.rs
index 8d4c4471c89..84f67743a3a 100644
--- a/src/libextra/test.rs
+++ b/src/libextra/test.rs
@@ -673,7 +673,7 @@ pub fn run_tests_console(opts: &TestOpts,
 
 #[test]
 fn should_sort_failures_before_printing_them() {
-    use std::io::mem::MemWriter;
+    use std::io::MemWriter;
     use std::str;
 
     let test_a = TestDesc {
diff --git a/src/libextra/time.rs b/src/libextra/time.rs
index d19181ab9f1..9c9edc3ddd9 100644
--- a/src/libextra/time.rs
+++ b/src/libextra/time.rs
@@ -10,8 +10,7 @@
 
 #[allow(missing_doc)];
 
-use std::io::Reader;
-use std::io::mem::BufReader;
+use std::io::BufReader;
 use std::libc;
 use std::num;
 use std::str;
diff --git a/src/libextra/url.rs b/src/libextra/url.rs
index 657ff1737df..7591f564da2 100644
--- a/src/libextra/url.rs
+++ b/src/libextra/url.rs
@@ -12,8 +12,7 @@
 
 #[allow(missing_doc)];
 
-use std::io::{Reader, Seek};
-use std::io::mem::BufReader;
+use std::io::BufReader;
 use std::cmp::Eq;
 use std::hashmap::HashMap;
 use std::to_bytes;
diff --git a/src/libextra/uuid.rs b/src/libextra/uuid.rs
index b9e3e817414..2c48a7a4d3e 100644
--- a/src/libextra/uuid.rs
+++ b/src/libextra/uuid.rs
@@ -522,7 +522,7 @@ mod test {
     use std::str;
     use std::rand;
     use std::num::Zero;
-    use std::io::mem::MemWriter;
+    use std::io::MemWriter;
 
     #[test]
     fn test_new_nil() {
diff --git a/src/libextra/workcache.rs b/src/libextra/workcache.rs
index 9dbb607681d..2bec1a2f962 100644
--- a/src/libextra/workcache.rs
+++ b/src/libextra/workcache.rs
@@ -17,8 +17,7 @@ use arc::{Arc,RWArc};
 use treemap::TreeMap;
 use std::str;
 use std::io;
-use std::io::File;
-use std::io::mem::MemWriter;
+use std::io::{File, MemWriter};
 
 /**
 *
diff --git a/src/librustc/driver/driver.rs b/src/librustc/driver/driver.rs
index aa3ab80b487..058728f26a0 100644
--- a/src/librustc/driver/driver.rs
+++ b/src/librustc/driver/driver.rs
@@ -30,7 +30,7 @@ use std::cell::{Cell, RefCell};
 use std::hashmap::{HashMap,HashSet};
 use std::io;
 use std::io::fs;
-use std::io::mem::MemReader;
+use std::io::MemReader;
 use std::os;
 use std::vec;
 use extra::getopts::groups::{optopt, optmulti, optflag, optflagopt};
diff --git a/src/librustc/metadata/encoder.rs b/src/librustc/metadata/encoder.rs
index 5848744ec1c..c46b573c1e0 100644
--- a/src/librustc/metadata/encoder.rs
+++ b/src/librustc/metadata/encoder.rs
@@ -24,7 +24,7 @@ use middle;
 use std::cast;
 use std::cell::{Cell, RefCell};
 use std::hashmap::{HashMap, HashSet};
-use std::io::mem::MemWriter;
+use std::io::MemWriter;
 use std::str;
 use std::vec;
 
diff --git a/src/librustc/metadata/tyencode.rs b/src/librustc/metadata/tyencode.rs
index 8a8fdd72652..aca3d9000de 100644
--- a/src/librustc/metadata/tyencode.rs
+++ b/src/librustc/metadata/tyencode.rs
@@ -13,7 +13,7 @@
 use std::cell::RefCell;
 use std::hashmap::HashMap;
 use std::io;
-use std::io::mem::MemWriter;
+use std::io::MemWriter;
 use std::str;
 use std::fmt;
 
diff --git a/src/librustc/middle/astencode.rs b/src/librustc/middle/astencode.rs
index 6a37324e05a..1b3d91e024f 100644
--- a/src/librustc/middle/astencode.rs
+++ b/src/librustc/middle/astencode.rs
@@ -1456,7 +1456,7 @@ fn mk_ctxt() -> @fake_ext_ctxt {
 
 #[cfg(test)]
 fn roundtrip(in_item: Option<@ast::Item>) {
-    use std::io::mem::MemWriter;
+    use std::io::MemWriter;
 
     let in_item = in_item.unwrap();
     let mut wr = MemWriter::new();
diff --git a/src/librustc/middle/liveness.rs b/src/librustc/middle/liveness.rs
index 8d6e2b6f6b3..65d2f9c150c 100644
--- a/src/librustc/middle/liveness.rs
+++ b/src/librustc/middle/liveness.rs
@@ -794,8 +794,9 @@ impl Liveness {
     }
 
     pub fn ln_str(&self, ln: LiveNode) -> ~str {
-        str::from_utf8_owned(io::mem::with_mem_writer(|wr| {
-            let wr = wr as &mut io::Writer;
+        let mut wr = io::MemWriter::new();
+        {
+            let wr = &mut wr as &mut io::Writer;
             {
                 let lnks = self.ir.lnks.try_borrow();
                 write!(wr,
@@ -823,7 +824,8 @@ impl Liveness {
                     write!(wr, "  precedes (successors borrowed)]");
                 }
             }
-        }))
+        }
+        str::from_utf8_owned(wr.unwrap())
     }
 
     pub fn init_empty(&self, ln: LiveNode, succ_ln: LiveNode) {
diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs
index 74f94ba00f5..007a4502a1a 100644
--- a/src/librustdoc/html/render.rs
+++ b/src/librustdoc/html/render.rs
@@ -36,10 +36,8 @@
 use std::fmt;
 use std::hashmap::{HashMap, HashSet};
 use std::local_data;
-use std::io::buffered::BufferedWriter;
 use std::io;
-use std::io::fs;
-use std::io::File;
+use std::io::{fs, File, BufferedWriter};
 use std::str;
 use std::vec;
 
diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
index 125af757dc7..a6bdb2250a6 100644
--- a/src/librustdoc/lib.rs
+++ b/src/librustdoc/lib.rs
@@ -21,8 +21,7 @@ extern mod extra;
 
 use std::local_data;
 use std::io;
-use std::io::File;
-use std::io::mem::MemWriter;
+use std::io::{File, MemWriter};
 use std::str;
 use extra::getopts;
 use extra::getopts::groups;
diff --git a/src/libstd/fmt/mod.rs b/src/libstd/fmt/mod.rs
index 8de406f306f..a075010bfb2 100644
--- a/src/libstd/fmt/mod.rs
+++ b/src/libstd/fmt/mod.rs
@@ -242,7 +242,7 @@ actually invoking the `write` function defined in this module. Example usage is:
 ```rust
 use std::io;
 
-let mut w = io::mem::MemWriter::new();
+let mut w = io::MemWriter::new();
 write!(&mut w as &mut io::Writer, "Hello {}!", "world");
 ```
 
@@ -470,7 +470,7 @@ use prelude::*;
 
 use cast;
 use char::Char;
-use io::mem::MemWriter;
+use io::MemWriter;
 use io;
 use str;
 use repr;
diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs
index d0894bef413..928482b64df 100644
--- a/src/libstd/io/buffered.rs
+++ b/src/libstd/io/buffered.rs
@@ -9,59 +9,37 @@
 // except according to those terms.
 
 //! Buffering wrappers for I/O traits
-//!
-//! It can be excessively inefficient to work directly with a `Reader` or
-//! `Writer`. Every call to `read` or `write` on `TcpStream` results in a
-//! system call, for example. This module provides structures that wrap
-//! `Readers`, `Writers`, and `Streams` and buffer input and output to them.
-//!
-//! # Examples
-//!
-//! ```
-//! let tcp_stream = TcpStream::connect(addr);
-//! let reader = BufferedReader::new(tcp_stream);
-//!
-//! let mut buf: ~[u8] = vec::from_elem(100, 0u8);
-//! match reader.read(buf.as_slice()) {
-//!     Some(nread) => println!("Read {} bytes", nread),
-//!     None => println!("At the end of the stream!")
-//! }
-//! ```
-//!
-//! ```
-//! let tcp_stream = TcpStream::connect(addr);
-//! let writer = BufferedWriter::new(tcp_stream);
-//!
-//! writer.write("hello, world".as_bytes());
-//! writer.flush();
-//! ```
-//!
-//! ```
-//! let tcp_stream = TcpStream::connect(addr);
-//! let stream = BufferedStream::new(tcp_stream);
-//!
-//! stream.write("hello, world".as_bytes());
-//! stream.flush();
-//!
-//! let mut buf = vec::from_elem(100, 0u8);
-//! match stream.read(buf.as_slice()) {
-//!     Some(nread) => println!("Read {} bytes", nread),
-//!     None => println!("At the end of the stream!")
-//! }
-//! ```
-//!
-
-use prelude::*;
 
+use container::Container;
+use io::{Reader, Writer, Stream, Buffer, DEFAULT_BUF_SIZE};
+use iter::ExactSize;
 use num;
+use option::{Option, Some, None};
+use vec::{OwnedVector, ImmutableVector, MutableVector};
 use vec;
-use super::Stream;
-
-// libuv recommends 64k buffers to maximize throughput
-// https://groups.google.com/forum/#!topic/libuv/oQO1HJAIDdA
-static DEFAULT_CAPACITY: uint = 64 * 1024;
 
 /// Wraps a Reader and buffers input from it
+///
+/// It can be excessively inefficient to work directly with a `Reader` or
+/// `Writer`. Every call to `read` or `write` on `TcpStream` results in a
+/// system call, for example. This module provides structures that wrap
+/// `Readers`, `Writers`, and `Streams` and buffer input and output to them.
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::{BufferedReader, File};
+///
+/// # let _g = ::std::io::ignore_io_error();
+/// let file = File::open(&Path::new("message.txt"));
+/// let mut reader = BufferedReader::new(file);
+///
+/// let mut buf = [0, ..100];
+/// match reader.read(buf) {
+///     Some(nread) => println!("Read {} bytes", nread),
+///     None => println!("At the end of the file!")
+/// }
+/// ```
 pub struct BufferedReader<R> {
     priv inner: R,
     priv buf: ~[u8],
@@ -92,7 +70,7 @@ impl<R: Reader> BufferedReader<R> {
 
     /// Creates a new `BufferedReader` with a default buffer capacity
     pub fn new(inner: R) -> BufferedReader<R> {
-        BufferedReader::with_capacity(DEFAULT_CAPACITY, inner)
+        BufferedReader::with_capacity(DEFAULT_BUF_SIZE, inner)
     }
 
     /// Gets a reference to the underlying reader.
@@ -146,6 +124,19 @@ impl<R: Reader> Reader for BufferedReader<R> {
 /// Wraps a Writer and buffers output to it
 ///
 /// Note that `BufferedWriter` will NOT flush its buffer when dropped.
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::{BufferedWriter, File};
+///
+/// # let _g = ::std::io::ignore_io_error();
+/// let file = File::open(&Path::new("message.txt"));
+/// let mut writer = BufferedWriter::new(file);
+///
+/// writer.write_str("hello, world");
+/// writer.flush();
+/// ```
 pub struct BufferedWriter<W> {
     priv inner: W,
     priv buf: ~[u8],
@@ -167,7 +158,7 @@ impl<W: Writer> BufferedWriter<W> {
 
     /// Creates a new `BufferedWriter` with a default buffer capacity
     pub fn new(inner: W) -> BufferedWriter<W> {
-        BufferedWriter::with_capacity(DEFAULT_CAPACITY, inner)
+        BufferedWriter::with_capacity(DEFAULT_BUF_SIZE, inner)
     }
 
     fn flush_buf(&mut self) {
@@ -273,6 +264,25 @@ impl<W: Reader> Reader for InternalBufferedWriter<W> {
 /// Wraps a Stream and buffers input and output to and from it
 ///
 /// Note that `BufferedStream` will NOT flush its output buffer when dropped.
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::{BufferedStream, File};
+///
+/// # let _g = ::std::io::ignore_io_error();
+/// let file = File::open(&Path::new("message.txt"));
+/// let mut stream = BufferedStream::new(file);
+///
+/// stream.write("hello, world".as_bytes());
+/// stream.flush();
+///
+/// let mut buf = [0, ..100];
+/// match stream.read(buf) {
+///     Some(nread) => println!("Read {} bytes", nread),
+///     None => println!("At the end of the stream!")
+/// }
+/// ```
 pub struct BufferedStream<S> {
     priv inner: BufferedReader<InternalBufferedWriter<S>>
 }
@@ -292,7 +302,7 @@ impl<S: Stream> BufferedStream<S> {
     /// Creates a new buffered stream with the default reader/writer buffer
     /// capacities.
     pub fn new(inner: S) -> BufferedStream<S> {
-        BufferedStream::with_capacities(DEFAULT_CAPACITY, DEFAULT_CAPACITY,
+        BufferedStream::with_capacities(DEFAULT_BUF_SIZE, DEFAULT_BUF_SIZE,
                                         inner)
     }
 
@@ -337,9 +347,9 @@ mod test {
     use super::super::mem::{MemReader, MemWriter, BufReader};
     use Harness = extra::test::BenchHarness;
 
-    /// A type, free to create, primarily intended for benchmarking creation of wrappers that, just
-    /// for construction, don't need a Reader/Writer that does anything useful. Is equivalent to
-    /// `/dev/null` in semantics.
+    /// A type, free to create, primarily intended for benchmarking creation of
+    /// wrappers that, just for construction, don't need a Reader/Writer that
+    /// does anything useful. Is equivalent to `/dev/null` in semantics.
     #[deriving(Clone,Eq,Ord)]
     pub struct NullStream;
 
diff --git a/src/libstd/io/extensions.rs b/src/libstd/io/extensions.rs
index 066dc883597..72f61a7bf84 100644
--- a/src/libstd/io/extensions.rs
+++ b/src/libstd/io/extensions.rs
@@ -141,7 +141,7 @@ pub fn u64_from_be_bytes(data: &[u8],
 mod test {
     use unstable::finally::Finally;
     use prelude::*;
-    use io::mem::{MemReader, MemWriter};
+    use io::{MemReader, MemWriter};
     use io::{io_error, placeholder_error};
 
     struct InitialZeroByteReader {
diff --git a/src/libstd/io/mem.rs b/src/libstd/io/mem.rs
index f036131d211..660c3d3adbc 100644
--- a/src/libstd/io/mem.rs
+++ b/src/libstd/io/mem.rs
@@ -9,18 +9,28 @@
 // except according to those terms.
 
 //! Readers and Writers for in-memory buffers
-//!
-//! # XXX
-//!
-//! * Should probably have something like this for strings.
-//! * Should they implement Closable? Would take extra state.
+
 use cmp::max;
 use cmp::min;
-use prelude::*;
-use super::*;
+use container::Container;
+use option::{Option, Some, None};
+use super::{Reader, Writer, Seek, Buffer, IoError, SeekStyle, io_error,
+            OtherIoError};
 use vec;
+use vec::{Vector, ImmutableVector, MutableVector, OwnedCopyableVector};
 
 /// Writes to an owned, growable byte vector
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::MemWriter;
+///
+/// let mut w = MemWriter::new();
+/// w.write([0, 1, 2]);
+///
+/// assert_eq!(w.unwrap(), ~[0, 1, 2]);
+/// ```
 pub struct MemWriter {
     priv buf: ~[u8],
     priv pos: uint,
@@ -96,6 +106,16 @@ impl Seek for MemWriter {
 }
 
 /// Reads from an owned byte vector
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::MemReader;
+///
+/// let mut r = MemReader::new(~[0, 1, 2]);
+///
+/// assert_eq!(r.read_to_end(), ~[0, 1, 2]);
+/// ```
 pub struct MemReader {
     priv buf: ~[u8],
     priv pos: uint
@@ -159,6 +179,19 @@ impl Buffer for MemReader {
 ///
 /// If a write will not fit in the buffer, it raises the `io_error`
 /// condition and does not write any data.
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::BufWriter;
+///
+/// let mut buf = [0, ..4];
+/// {
+///     let mut w = BufWriter::new(buf);
+///     w.write([0, 1, 2]);
+/// }
+/// assert_eq!(buf, [0, 1, 2, 0]);
+/// ```
 pub struct BufWriter<'a> {
     priv buf: &'a mut [u8],
     priv pos: uint
@@ -209,12 +242,24 @@ impl<'a> Seek for BufWriter<'a> {
 
 
 /// Reads from a fixed-size byte slice
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::BufReader;
+///
+/// let mut buf = [0, 1, 2, 3];
+/// let mut r = BufReader::new(buf);
+///
+/// assert_eq!(r.read_to_end(), ~[0, 1, 2, 3]);
+/// ```
 pub struct BufReader<'a> {
     priv buf: &'a [u8],
     priv pos: uint
 }
 
 impl<'a> BufReader<'a> {
+    /// Creates a new buffered reader which will read the specified buffer
     pub fn new<'a>(buf: &'a [u8]) -> BufReader<'a> {
         BufReader {
             buf: buf,
@@ -257,14 +302,6 @@ impl<'a> Buffer for BufReader<'a> {
     fn consume(&mut self, amt: uint) { self.pos += amt; }
 }
 
-///Calls a function with a MemWriter and returns
-///the writer's stored vector.
-pub fn with_mem_writer(writeFn: |&mut MemWriter|) -> ~[u8] {
-    let mut writer = MemWriter::new();
-    writeFn(&mut writer);
-    writer.unwrap()
-}
-
 #[cfg(test)]
 mod test {
     use prelude::*;
@@ -399,12 +436,6 @@ mod test {
     }
 
     #[test]
-    fn test_with_mem_writer() {
-        let buf = with_mem_writer(|wr| wr.write([1,2,3,4,5,6,7]));
-        assert_eq!(buf, ~[1,2,3,4,5,6,7]);
-    }
-
-    #[test]
     fn test_read_char() {
         let mut r = BufReader::new(bytes!("Việt"));
         assert_eq!(r.read_char(), Some('V'));
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 2e33bef380c..6515cbc5fb3 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -26,7 +26,7 @@ Some examples of obvious things you might want to do
 * Read lines from stdin
 
     ```rust
-    use std::io::buffered::BufferedReader;
+    use std::io::BufferedReader;
     use std::io::stdin;
 
     # let _g = ::std::io::ignore_io_error();
@@ -60,7 +60,7 @@ Some examples of obvious things you might want to do
 * Iterate over the lines of a file
 
     ```rust
-    use std::io::buffered::BufferedReader;
+    use std::io::BufferedReader;
     use std::io::File;
 
     # let _g = ::std::io::ignore_io_error();
@@ -74,7 +74,7 @@ Some examples of obvious things you might want to do
 * Pull the lines of a file into a vector of strings
 
     ```rust
-    use std::io::buffered::BufferedReader;
+    use std::io::BufferedReader;
     use std::io::File;
 
     # let _g = ::std::io::ignore_io_error();
@@ -321,6 +321,11 @@ pub use self::net::udp::UdpStream;
 pub use self::pipe::PipeStream;
 pub use self::process::Process;
 
+pub use self::mem::{MemReader, BufReader, MemWriter, BufWriter};
+pub use self::buffered::{BufferedReader, BufferedWriter, BufferedStream,
+                         LineBufferedWriter};
+pub use self::comm_adapters::{PortReader, ChanWriter};
+
 /// Various utility functions useful for writing I/O tests
 pub mod test;
 
@@ -337,7 +342,7 @@ pub mod process;
 pub mod net;
 
 /// Readers and Writers for memory buffers and strings.
-pub mod mem;
+mod mem;
 
 /// Non-blocking access to stdin, stdout, stderr
 pub mod stdio;
@@ -345,9 +350,6 @@ pub mod stdio;
 /// Implementations for Option
 mod option;
 
-/// Basic stream compression. XXX: Belongs with other flate code
-pub mod flate;
-
 /// Extension traits
 pub mod extensions;
 
@@ -355,7 +357,7 @@ pub mod extensions;
 pub mod timer;
 
 /// Buffered I/O wrappers
-pub mod buffered;
+mod buffered;
 
 /// Signal handling
 pub mod signal;
@@ -364,9 +366,11 @@ pub mod signal;
 pub mod util;
 
 /// Adapatation of Chan/Port types to a Writer/Reader type.
-pub mod comm_adapters;
+mod comm_adapters;
 
 /// The default buffer size for various I/O operations
+// libuv recommends 64k buffers to maximize throughput
+// https://groups.google.com/forum/#!topic/libuv/oQO1HJAIDdA
 static DEFAULT_BUF_SIZE: uint = 1024 * 64;
 
 /// The type passed to I/O condition handlers to indicate error
@@ -1098,11 +1102,10 @@ pub trait Buffer: Reader {
     /// # Example
     ///
     /// ```rust
-    /// use std::io::buffered::BufferedReader;
-    /// use std::io;
+    /// use std::io::{BufferedReader, stdin};
     /// # let _g = ::std::io::ignore_io_error();
     ///
-    /// let mut reader = BufferedReader::new(io::stdin());
+    /// let mut reader = BufferedReader::new(stdin());
     ///
     /// let input = reader.read_line().unwrap_or(~"nothing");
     /// ```
diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs
index f3177276bc2..f3f071ab78b 100644
--- a/src/libstd/io/stdio.rs
+++ b/src/libstd/io/stdio.rs
@@ -28,9 +28,8 @@ out.write(bytes!("Hello, world!"));
 
 use container::Container;
 use fmt;
-use io::buffered::LineBufferedWriter;
 use io::{Reader, Writer, io_error, IoError, OtherIoError,
-         standard_error, EndOfFile};
+         standard_error, EndOfFile, LineBufferedWriter};
 use libc;
 use option::{Option, Some, None};
 use prelude::drop;
diff --git a/src/libstd/io/util.rs b/src/libstd/io/util.rs
index 612c757ad4c..a1794d24fc9 100644
--- a/src/libstd/io/util.rs
+++ b/src/libstd/io/util.rs
@@ -171,7 +171,7 @@ pub fn copy<R: Reader, W: Writer>(r: &mut R, w: &mut W) {
 
 #[cfg(test)]
 mod test {
-    use io::mem::{MemReader, MemWriter};
+    use io::{MemReader, MemWriter};
     use super::*;
     use prelude::*;
 
diff --git a/src/libstd/logging.rs b/src/libstd/logging.rs
index d10b873c5b5..636d3ffd90a 100644
--- a/src/libstd/logging.rs
+++ b/src/libstd/logging.rs
@@ -96,7 +96,7 @@ start, print out all modules registered for logging, and then exit.
 */
 
 use fmt;
-use io::buffered::LineBufferedWriter;
+use io::LineBufferedWriter;
 use io;
 use io::Writer;
 use ops::Drop;
diff --git a/src/libstd/rand/reader.rs b/src/libstd/rand/reader.rs
index 7af98e418a8..e19fbd9aaf8 100644
--- a/src/libstd/rand/reader.rs
+++ b/src/libstd/rand/reader.rs
@@ -25,9 +25,9 @@ use rand::Rng;
 ///
 /// ```rust
 /// use std::rand::{reader, Rng};
-/// use std::io::mem;
+/// use std::io::MemReader;
 ///
-/// let mut rng = reader::ReaderRng::new(mem::MemReader::new(~[1,2,3,4,5,6,7,8]));
+/// let mut rng = reader::ReaderRng::new(MemReader::new(~[1,2,3,4,5,6,7,8]));
 /// println!("{:x}", rng.gen::<uint>());
 /// ```
 pub struct ReaderRng<R> {
@@ -76,7 +76,7 @@ impl<R: Reader> Rng for ReaderRng<R> {
 #[cfg(test)]
 mod test {
     use super::*;
-    use io::mem::MemReader;
+    use io::MemReader;
     use cast;
     use rand::*;
     use prelude::*;
diff --git a/src/libstd/repr.rs b/src/libstd/repr.rs
index e0f96365edd..cc166b764d2 100644
--- a/src/libstd/repr.rs
+++ b/src/libstd/repr.rs
@@ -621,7 +621,7 @@ pub fn repr_to_str<T>(t: &T) -> ~str {
     use str;
     use io;
 
-    let mut result = io::mem::MemWriter::new();
+    let mut result = io::MemWriter::new();
     write_repr(&mut result as &mut io::Writer, t);
     str::from_utf8_owned(result.unwrap())
 }
@@ -639,7 +639,7 @@ fn test_repr() {
     use char::is_alphabetic;
 
     fn exact_test<T>(t: &T, e:&str) {
-        let mut m = io::mem::MemWriter::new();
+        let mut m = io::MemWriter::new();
         write_repr(&mut m as &mut io::Writer, t);
         let s = str::from_utf8_owned(m.unwrap());
         assert_eq!(s.as_slice(), e);
diff --git a/src/libstd/to_bytes.rs b/src/libstd/to_bytes.rs
index bd1c49c6c24..8df028f56d5 100644
--- a/src/libstd/to_bytes.rs
+++ b/src/libstd/to_bytes.rs
@@ -359,15 +359,14 @@ pub trait ToBytes {
 
 impl<A:IterBytes> ToBytes for A {
     fn to_bytes(&self, lsb0: bool) -> ~[u8] {
-        use io::mem;
         use io::Writer;
 
-        mem::with_mem_writer(|wr| {
-            self.iter_bytes(lsb0, |bytes| {
-                wr.write(bytes);
-                true
-            });
-        })
+        let mut m = ::io::MemWriter::new();
+        self.iter_bytes(lsb0, |bytes| {
+            m.write(bytes);
+            true
+        });
+        m.unwrap()
     }
 }
 
diff --git a/src/libsyntax/parse/mod.rs b/src/libsyntax/parse/mod.rs
index ea069c2ffe3..30a662c9cce 100644
--- a/src/libsyntax/parse/mod.rs
+++ b/src/libsyntax/parse/mod.rs
@@ -337,7 +337,7 @@ mod test {
     use extra::serialize::Encodable;
     use extra;
     use std::io;
-    use std::io::mem::MemWriter;
+    use std::io::MemWriter;
     use std::str;
     use codemap::{Span, BytePos, Spanned};
     use opt_vec;
diff --git a/src/libsyntax/print/pprust.rs b/src/libsyntax/print/pprust.rs
index b6db827f7b8..3275ba2cef5 100644
--- a/src/libsyntax/print/pprust.rs
+++ b/src/libsyntax/print/pprust.rs
@@ -32,7 +32,7 @@ use std::cell::RefCell;
 use std::char;
 use std::str;
 use std::io;
-use std::io::mem::MemWriter;
+use std::io::MemWriter;
 
 // The &mut State is stored here to prevent recursive type.
 pub enum AnnNode<'a,'b> {
diff --git a/src/test/bench/core-std.rs b/src/test/bench/core-std.rs
index 9be462f736b..4d5c4ec24f3 100644
--- a/src/test/bench/core-std.rs
+++ b/src/test/bench/core-std.rs
@@ -70,7 +70,7 @@ fn shift_push() {
 }
 
 fn read_line() {
-    use std::io::buffered::BufferedReader;
+    use std::io::BufferedReader;
 
     let mut path = Path::new(env!("CFG_SRC_DIR"));
     path.push("src/test/bench/shootout-k-nucleotide.data");
diff --git a/src/test/bench/shootout-fasta.rs b/src/test/bench/shootout-fasta.rs
index 50138562fa3..74d8af52f7d 100644
--- a/src/test/bench/shootout-fasta.rs
+++ b/src/test/bench/shootout-fasta.rs
@@ -15,8 +15,7 @@
  */
 
 use std::io;
-use std::io::buffered::BufferedWriter;
-use std::io::File;
+use std::io::{BufferedWriter, File};
 use std::num::min;
 use std::os;
 
diff --git a/src/test/bench/shootout-k-nucleotide-pipes.rs b/src/test/bench/shootout-k-nucleotide-pipes.rs
index cef59b7c0e6..83eb1388c6b 100644
--- a/src/test/bench/shootout-k-nucleotide-pipes.rs
+++ b/src/test/bench/shootout-k-nucleotide-pipes.rs
@@ -145,10 +145,7 @@ fn make_sequence_processor(sz: uint,
 
 // given a FASTA file on stdin, process sequence THREE
 fn main() {
-    use std::io::Reader;
-    use std::io::stdio;
-    use std::io::mem::MemReader;
-    use std::io::buffered::BufferedReader;
+    use std::io::{stdio, MemReader, BufferedReader};
 
     let rdr = if os::getenv("RUST_BENCH").is_some() {
         let foo = include_bin!("shootout-k-nucleotide.data");
diff --git a/src/test/bench/shootout-mandelbrot.rs b/src/test/bench/shootout-mandelbrot.rs
index 732922cdb07..a0e9f96b31d 100644
--- a/src/test/bench/shootout-mandelbrot.rs
+++ b/src/test/bench/shootout-mandelbrot.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use std::io::buffered::BufferedWriter;
+use std::io::BufferedWriter;
 
 struct DummyWriter;
 impl Writer for DummyWriter {
diff --git a/src/test/bench/sudoku.rs b/src/test/bench/sudoku.rs
index fb14ba71b88..4980691512d 100644
--- a/src/test/bench/sudoku.rs
+++ b/src/test/bench/sudoku.rs
@@ -16,7 +16,7 @@ extern mod extra;
 
 use std::io;
 use std::io::stdio::StdReader;
-use std::io::buffered::BufferedReader;
+use std::io::BufferedReader;
 use std::os;
 use std::unstable::intrinsics::cttz16;
 use std::vec;
diff --git a/src/test/run-pass/auto-encode.rs b/src/test/run-pass/auto-encode.rs
index 35e171704ac..5f697b7e514 100644
--- a/src/test/run-pass/auto-encode.rs
+++ b/src/test/run-pass/auto-encode.rs
@@ -34,7 +34,7 @@ fn test_ebml<'a, A:
     Encodable<EBWriter::Encoder> +
     Decodable<EBReader::Decoder<'a>>
 >(a1: &A) {
-    let mut wr = std::io::mem::MemWriter::new();
+    let mut wr = std::io::MemWriter::new();
     let mut ebml_w = EBWriter::Encoder(&mut wr);
     a1.encode(&mut ebml_w);
     let bytes = wr.get_ref();
diff --git a/src/test/run-pass/capturing-logging.rs b/src/test/run-pass/capturing-logging.rs
index e385c1c14a4..b810bfd1c6b 100644
--- a/src/test/run-pass/capturing-logging.rs
+++ b/src/test/run-pass/capturing-logging.rs
@@ -16,7 +16,7 @@
 extern mod native;
 
 use std::fmt;
-use std::io::comm_adapters::{PortReader, ChanWriter};
+use std::io::{PortReader, ChanWriter};
 use std::logging::{set_logger, Logger};
 
 struct MyWriter(ChanWriter);
diff --git a/src/test/run-pass/deriving-encodable-decodable.rs b/src/test/run-pass/deriving-encodable-decodable.rs
index e22f0a8f8c7..d16f2135f50 100644
--- a/src/test/run-pass/deriving-encodable-decodable.rs
+++ b/src/test/run-pass/deriving-encodable-decodable.rs
@@ -18,7 +18,7 @@
 
 extern mod extra;
 
-use std::io::mem::MemWriter;
+use std::io::MemWriter;
 use std::rand::{random, Rand};
 use extra::serialize::{Encodable, Decodable};
 use extra::ebml;
diff --git a/src/test/run-pass/ifmt.rs b/src/test/run-pass/ifmt.rs
index 837adfce048..54aaa86351e 100644
--- a/src/test/run-pass/ifmt.rs
+++ b/src/test/run-pass/ifmt.rs
@@ -14,9 +14,8 @@
 #[deny(warnings)];
 
 use std::fmt;
-use std::io::mem::MemWriter;
+use std::io::MemWriter;
 use std::io;
-use std::io::Writer;
 use std::str;
 
 struct A;