From 8f7eb3b058f78bffe5406776eb31080615799ce7 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Fri, 10 Apr 2015 13:23:17 -0700 Subject: core: Update all Result docs --- src/libcore/result.rs | 122 +++++++++++++++++++++----------------------------- 1 file changed, 52 insertions(+), 70 deletions(-) (limited to 'src/libcore') diff --git a/src/libcore/result.rs b/src/libcore/result.rs index 67a5ab891f7..66c68631491 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -85,35 +85,32 @@ //! functions that may encounter errors but don't otherwise return a //! useful value. //! -//! Consider the `write_line` method defined for I/O types -//! by the [`Writer`](../old_io/trait.Writer.html) trait: +//! Consider the `write_all` method defined for I/O types +//! by the [`Write`](../io/trait.Write.html) trait: //! //! ``` -//! # #![feature(old_io)] -//! use std::old_io::IoError; +//! use std::io; //! //! trait Writer { -//! fn write_line(&mut self, s: &str) -> Result<(), IoError>; +//! fn write_all(&mut self, bytes: &[u8]) -> Result<(), io::Error>; //! } //! ``` //! -//! *Note: The actual definition of `Writer` uses `IoResult`, which -//! is just a synonym for `Result`.* +//! *Note: The actual definition of `Write` uses `io::Result`, which +//! is just a synonym for `Result`.* //! //! This method doesn't produce a value, but the write may //! fail. It's crucial to handle the error case, and *not* write //! something like this: //! -//! ```{.ignore} -//! # #![feature(old_io)] -//! use std::old_io::*; -//! use std::old_path::Path; +//! ```no_run +//! use std::fs::File; +//! use std::io::prelude::*; //! -//! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write); -//! // If `write_line` errors, then we'll never know, because the return +//! let mut file = File::create("valuable_data.txt").unwrap(); +//! // If `write_all` errors, then we'll never know, because the return //! // value is ignored. -//! file.write_line("important message"); -//! drop(file); +//! file.write_all(b"important message"); //! ``` //! //! If you *do* write that in Rust, the compiler will give you a @@ -125,37 +122,31 @@ //! a marginally useful message indicating why: //! //! ```{.no_run} -//! # #![feature(old_io, old_path)] -//! use std::old_io::*; -//! use std::old_path::Path; +//! use std::fs::File; +//! use std::io::prelude::*; //! -//! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write); -//! file.write_line("important message").ok().expect("failed to write message"); -//! drop(file); +//! let mut file = File::create("valuable_data.txt").unwrap(); +//! file.write_all(b"important message").ok().expect("failed to write message"); //! ``` //! //! You might also simply assert success: //! //! ```{.no_run} -//! # #![feature(old_io, old_path)] -//! # use std::old_io::*; -//! # use std::old_path::Path; -//! -//! # let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write); -//! assert!(file.write_line("important message").is_ok()); -//! # drop(file); +//! # use std::fs::File; +//! # use std::io::prelude::*; +//! # let mut file = File::create("valuable_data.txt").unwrap(); +//! assert!(file.write_all(b"important message").is_ok()); //! ``` //! //! Or propagate the error up the call stack with `try!`: //! //! ``` -//! # #![feature(old_io, old_path)] -//! # use std::old_io::*; -//! # use std::old_path::Path; -//! fn write_message() -> Result<(), IoError> { -//! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write); -//! try!(file.write_line("important message")); -//! drop(file); +//! # use std::fs::File; +//! # use std::io::prelude::*; +//! # use std::io; +//! fn write_message() -> io::Result<()> { +//! let mut file = try!(File::create("valuable_data.txt")); +//! try!(file.write_all(b"important message")); //! Ok(()) //! } //! ``` @@ -170,9 +161,9 @@ //! It replaces this: //! //! ``` -//! # #![feature(old_io, old_path)] -//! use std::old_io::*; -//! use std::old_path::Path; +//! use std::fs::File; +//! use std::io::prelude::*; +//! use std::io; //! //! struct Info { //! name: String, @@ -180,25 +171,28 @@ //! rating: i32, //! } //! -//! fn write_info(info: &Info) -> Result<(), IoError> { -//! let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write); +//! fn write_info(info: &Info) -> io::Result<()> { +//! let mut file = try!(File::create("my_best_friends.txt")); //! // Early return on error -//! if let Err(e) = file.write_line(&format!("name: {}", info.name)) { +//! if let Err(e) = file.write_all(format!("name: {}\n", info.name).as_bytes()) { +//! return Err(e) +//! } +//! if let Err(e) = file.write_all(format!("age: {}\n", info.age).as_bytes()) { //! return Err(e) //! } -//! if let Err(e) = file.write_line(&format!("age: {}", info.age)) { +//! if let Err(e) = file.write_all(format!("rating: {}\n", info.rating).as_bytes()) { //! return Err(e) //! } -//! file.write_line(&format!("rating: {}", info.rating)) +//! Ok(()) //! } //! ``` //! //! With this: //! //! ``` -//! # #![feature(old_io, old_path)] -//! use std::old_io::*; -//! use std::old_path::Path; +//! use std::fs::File; +//! use std::io::prelude::*; +//! use std::io; //! //! struct Info { //! name: String, @@ -206,12 +200,12 @@ //! rating: i32, //! } //! -//! fn write_info(info: &Info) -> Result<(), IoError> { -//! let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write); +//! fn write_info(info: &Info) -> io::Result<()> { +//! let mut file = try!(File::create("my_best_friends.txt")); //! // Early return on error -//! try!(file.write_line(&format!("name: {}", info.name))); -//! try!(file.write_line(&format!("age: {}", info.age))); -//! try!(file.write_line(&format!("rating: {}", info.rating))); +//! try!(file.write_all(format!("name: {}\n", info.name).as_bytes())); +//! try!(file.write_all(format!("age: {}\n", info.age).as_bytes())); +//! try!(file.write_all(format!("rating: {}\n", info.rating).as_bytes())); //! Ok(()) //! } //! ``` @@ -464,29 +458,17 @@ impl Result { /// /// # Examples /// - /// Sum the lines of a buffer by mapping strings to numbers, - /// ignoring I/O and parse errors: + /// Print the numbers on each line of a string multiplied by two. /// /// ``` - /// # #![feature(old_io)] - /// use std::old_io::*; + /// let line = "1\n2\n3\n4\n"; /// - /// let mut buffer: &[u8] = b"1\n2\n3\n4\n"; - /// let mut buffer = &mut buffer; - /// - /// let mut sum = 0; - /// - /// while !buffer.is_empty() { - /// let line: IoResult = buffer.read_line(); - /// // Convert the string line to a number using `map` and `from_str` - /// let val: IoResult = line.map(|line| { - /// line.trim_right().parse::().unwrap_or(0) - /// }); - /// // Add the value if there were no errors, otherwise add 0 - /// sum += val.unwrap_or(0); + /// for num in line.lines() { + /// match num.parse::().map(|i| i * 2) { + /// Ok(n) => println!("{}", n), + /// Err(..) => {} + /// } /// } - /// - /// assert!(sum == 10); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5