From 9634bcbd3d120e7a13b62bb47e882fc9ce6338cd Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 10:12:16 -0400 Subject: [PATCH 1/5] Improve `try!` docs to make clearer it returns `Result`. The API documentation is not explicit enough that because `try!` returns `Err` early for you, you can only use it in functions that return `Result`. The book mentions this, but if you come across `try!` outside of the book and look it up in the docs, this restriction on the return type of the function is not particularly clear. --- src/libcore/result.rs | 4 +++- src/libstd/macros.rs | 28 +++++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/src/libcore/result.rs b/src/libcore/result.rs index e909946ece402..003c4b2b78c5c 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -223,7 +223,9 @@ //! } //! ``` //! -//! `try!` is imported by the prelude, and is available everywhere. +//! `try!` is imported by the prelude and is available everywhere, but it can only +//! be used in functions that return `Result` because of the early return of +//! `Err` that it provides. #![stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 32193b4089d30..a7c18783025e0 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -117,7 +117,33 @@ macro_rules! println { } /// Helper macro for unwrapping `Result` values while returning early with an -/// error if the value of the expression is `Err`. +/// error if the value of the expression is `Err`. Can only be used in +/// functions that return `Result` because of the early return of `Err` that +/// it provides. +/// +/// # Examples +/// +/// ``` +/// use std::io; +/// use std::fs::File; +/// +/// fn write_to_file_using_try() -> Result<(), io::Error> { +/// let mut file = try!(File::create("my_best_friends.txt")); +/// try!(file.write_line("This is a list of my best friends.")); +/// println!("I wrote to the file"); +/// Ok() +/// } +/// // This is equivalent to: +/// fn write_to_file_using_match() -> Result<(), io::Error> { +/// let mut file = try!(File::create("my_best_friends.txt")); +/// match file.write_line("This is a list of my best friends.") { +/// Ok(_) => (), +/// Err(e) => return Err(e), +/// } +/// println!("I wrote to the file"); +/// Ok() +/// } +/// ``` #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] macro_rules! try { From d328d6472e6a61820c92ed7a910dbbff734fe235 Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:15:50 -0400 Subject: [PATCH 2/5] Add prelude to get Write --- src/libstd/macros.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index a7c18783025e0..1a3fda53366f4 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -126,6 +126,7 @@ macro_rules! println { /// ``` /// use std::io; /// use std::fs::File; +/// use std::io::prelude::*; /// /// fn write_to_file_using_try() -> Result<(), io::Error> { /// let mut file = try!(File::create("my_best_friends.txt")); From a41fd590a8142b524d6a6d34e8977906d6787368 Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:23:20 -0400 Subject: [PATCH 3/5] Use write_all instead of write_line --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 1a3fda53366f4..cbb2880445942 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -130,14 +130,14 @@ macro_rules! println { /// /// fn write_to_file_using_try() -> Result<(), io::Error> { /// let mut file = try!(File::create("my_best_friends.txt")); -/// try!(file.write_line("This is a list of my best friends.")); +/// try!(file.write_all(b"This is a list of my best friends.")); /// println!("I wrote to the file"); /// Ok() /// } /// // This is equivalent to: /// fn write_to_file_using_match() -> Result<(), io::Error> { /// let mut file = try!(File::create("my_best_friends.txt")); -/// match file.write_line("This is a list of my best friends.") { +/// match file.write_all(b"This is a list of my best friends.") { /// Ok(_) => (), /// Err(e) => return Err(e), /// } From 80322e2e970bc7d2d36c14fb63f753fe39acf63e Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:23:40 -0400 Subject: [PATCH 4/5] Return Ok(()) instead of Ok() --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index cbb2880445942..26ace45890c36 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -132,7 +132,7 @@ macro_rules! println { /// let mut file = try!(File::create("my_best_friends.txt")); /// try!(file.write_all(b"This is a list of my best friends.")); /// println!("I wrote to the file"); -/// Ok() +/// Ok(()) /// } /// // This is equivalent to: /// fn write_to_file_using_match() -> Result<(), io::Error> { @@ -142,7 +142,7 @@ macro_rules! println { /// Err(e) => return Err(e), /// } /// println!("I wrote to the file"); -/// Ok() +/// Ok(()) /// } /// ``` #[macro_export] From c692d75b5a595ef5939473aef20e1751d4e0e1f5 Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:23:55 -0400 Subject: [PATCH 5/5] Indent 4 spaces instead of 2 --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 26ace45890c36..706571b67c9ac 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -138,8 +138,8 @@ macro_rules! println { /// fn write_to_file_using_match() -> Result<(), io::Error> { /// let mut file = try!(File::create("my_best_friends.txt")); /// match file.write_all(b"This is a list of my best friends.") { -/// Ok(_) => (), -/// Err(e) => return Err(e), +/// Ok(_) => (), +/// Err(e) => return Err(e), /// } /// println!("I wrote to the file"); /// Ok(())