---

yaml
---
r: 105275
b: refs/heads/master
c: 207ebf1
h: refs/heads/master
i:
  105273: e5ec662
  105271: 48ce8ac
v: v3

Author: tari

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 91bed14ca8085887a26d029d785d853ad2587718
+refs/heads/master: 207ebf13f12d8fa4449d66cd86407de03f264667
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: b8601a3d8b91ad3b653d143307611f2f5c75617e
 refs/heads/try: db814977d07bd798feb24f6b74c00800ef458a13

trunk/src/libstd/io/mod.rs

@@ -172,6 +172,40 @@ need to inspect or unwrap the `IoResult<File>` and we simply call `write_line`
 on it. If `new` returned an `Err(..)` then the followup call to `write_line`
 will also return an error.
 
+## `try!`
+
+Explicit pattern matching on `IoResult`s can get quite verbose, especially
+when performing many I/O operations. Some examples (like those above) are
+alleviated with extra methods implemented on `IoResult`, but others have more
+complex interdependencies among each I/O operation.
+
+The `try!` macro from `std::macros` is provided as a method of early-return
+inside `Result`-returning functions. It expands to an early-return on `Err`
+and otherwise unwraps the contained `Ok` value.
+
+If you wanted to read several `u32`s from a file and return their product:
+
+```rust
+use std::io::{File, IoResult};
+
+fn file_product(p: &Path) -> IoResult<u32> {
+    let mut f = File::open(p);
+    let x1 = try!(f.read_le_u32());
+    let x2 = try!(f.read_le_u32());
+
+    Ok(x1 * x2)
+}
+
+match file_product(&Path::new("numbers.bin")) {
+    Ok(x) => println!("{}", x),
+    Err(e) => println!("Failed to read numbers!")
+}
+```
+
+With `try!` in `file_product`, each `read_le_u32` need not be directly
+concerned with error handling; instead its caller is responsible for
+responding to errors that may occur while attempting to read the numbers.
+
 */
 
 #[deny(unused_must_use)];