Return a buffered stdin by default.

One of the most common ways to use the stdin stream is to read it line by line
for a small program. In order to facilitate this common usage pattern, this
commit changes the stdin() function to return a BufferedReader by default. A new
`stdin_raw()` method was added to get access to the raw unbuffered stream.

I have not changed the stdout or stderr methods because they are currently
unable to flush in their destructor, but #12403 should have just fixed that.

src/libstd/io/mod.rs

@@ -26,11 +26,9 @@ Some examples of obvious things you might want to do
 * Read lines from stdin
 
     ```rust
-    use std::io::BufferedReader;
+    use std::io;
-    use std::io::stdin;
 
-    let mut stdin = BufferedReader::new(stdin());
+    for line in io::stdin().lines() {
-    for line in stdin.lines() {
         print!("{}", line);
     }
     ```
@@ -1097,10 +1095,9 @@ pub trait Buffer: Reader {
     /// # Example
     ///
     /// ```rust
-    /// use std::io::{BufferedReader, stdin};
+    /// use std::io;
-    ///
-    /// let mut reader = BufferedReader::new(stdin());
     ///
+    /// let mut reader = io::stdin();
     /// let input = reader.read_line().ok().unwrap_or(~"nothing");
     /// ```
     ///

src/libstd/io/stdio.rs

@@ -30,7 +30,7 @@ out.write(bytes!("Hello, world!"));
 use container::Container;
 use fmt;
 use io::{Reader, Writer, IoResult, IoError, OtherIoError,
-         standard_error, EndOfFile, LineBufferedWriter};
+         standard_error, EndOfFile, LineBufferedWriter, BufferedReader};
 use libc;
 use mem::replace;
 use option::{Option, Some, None};
@@ -86,8 +86,21 @@ fn src<T>(fd: libc::c_int, readable: bool, f: |StdSource| -> T) -> T {
 
 /// Creates a new non-blocking handle to the stdin of the current process.
 ///
-/// See `stdout()` for notes about this function.
+/// The returned handled is buffered by default with a `BufferedReader`. If
-pub fn stdin() -> StdReader {
+/// buffered access is not desired, the `stdin_raw` function is provided to
+/// provided unbuffered access to stdin.
+///
+/// See `stdout()` for more notes about this function.
+pub fn stdin() -> BufferedReader<StdReader> {
+    BufferedReader::new(stdin_raw())
+}
+
+/// Creates a new non-blocking handle to the stdin of the current process.
+///
+/// Unlike `stdin()`, the returned reader is *not* a buffered reader.
+///
+/// See `stdout()` for more notes about this function.
+pub fn stdin_raw() -> StdReader {
     src(libc::STDIN_FILENO, true, |src| StdReader { inner: src })
 }
 

src/test/bench/sudoku.rs

@@ -278,7 +278,7 @@ fn main() {
     let mut sudoku = if use_default {
         Sudoku::from_vec(&DEFAULT_SUDOKU)
     } else {
-        Sudoku::read(BufferedReader::new(io::stdin()))
+        Sudoku::read(io::stdin())
     };
     sudoku.solve();
     sudoku.write(&mut io::stdout());