(index<- ) ./libstd/result.rs
git branch: * master 5200215 auto merge of #14035 : alexcrichton/rust/experimental, r=huonw
modified: Fri May 9 13:02:28 2014
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Error handling with the `Result` type
12 //!
13 //! `Result<T>` is the type used for returning and propagating
14 //! errors. It is an enum with the variants, `Ok(T)`, representing
15 //! success and containing a value, and `Err(E)`, representing error
16 //! and containing an error value.
17 //!
18 //! ~~~
19 //! enum Result<T, E> {
20 //! Ok(T),
21 //! Err(E)
22 //! }
23 //! ~~~
24 //!
25 //! Functions return `Result` whenever errors are expected and
26 //! recoverable. In the `std` crate `Result` is most prominently used
27 //! for [I/O](../io/index.html).
28 //!
29 //! A simple function returning `Result` might be
30 //! defined and used like so:
31 //!
32 //! ~~~
33 //! #[deriving(Show)]
34 //! enum Version { Version1, Version2 }
35 //!
36 //! fn parse_version(header: &[u8]) -> Result<Version, &'static str> {
37 //! if header.len() < 1 {
38 //! return Err("invalid header length");
39 //! }
40 //! match header[0] {
41 //! 1 => Ok(Version1),
42 //! 2 => Ok(Version2),
43 //! _ => Err("invalid version")
44 //! }
45 //! }
46 //!
47 //! let version = parse_version(&[1, 2, 3, 4]);
48 //! match version {
49 //! Ok(v) => {
50 //! println!("working with version: {}", v);
51 //! }
52 //! Err(e) => {
53 //! println!("error parsing header: {}", e);
54 //! }
55 //! }
56 //! ~~~
57 //!
58 //! Pattern matching on `Result`s is clear and straightforward for
59 //! simple cases, but `Result` comes with some convenience methods
60 //! that make working it more succinct.
61 //!
62 //! ~~~
63 //! let good_result: Result<int, int> = Ok(10);
64 //! let bad_result: Result<int, int> = Err(10);
65 //!
66 //! // The `is_ok` and `is_err` methods do what they say.
67 //! assert!(good_result.is_ok() && !good_result.is_err());
68 //! assert!(bad_result.is_err() && !bad_result.is_ok());
69 //!
70 //! // `map` consumes the `Result` and produces another.
71 //! let good_result: Result<int, int> = good_result.map(|i| i + 1);
72 //! let bad_result: Result<int, int> = bad_result.map(|i| i - 1);
73 //!
74 //! // Use `and_then` to continue the computation.
75 //! let good_result: Result<bool, int> = good_result.and_then(|i| Ok(i == 11));
76 //!
77 //! // Use `or_else` to handle the error.
78 //! let bad_result: Result<int, int> = bad_result.or_else(|i| Ok(11));
79 //!
80 //! // Consume the result and return the contents with `unwrap`.
81 //! let final_awesome_result = good_result.ok().unwrap();
82 //! ~~~
83 //!
84 //! # Results must be used
85 //!
86 //! A common problem with using return values to indicate errors is
87 //! that it is easy to ignore the return value, thus failing to handle
88 //! the error. Result is annotated with the #[must_use] attribute,
89 //! which will cause the compiler to issue a warning when a Result
90 //! value is ignored. This makes `Result` especially useful with
91 //! functions that may encounter errors but don't otherwise return a
92 //! useful value.
93 //!
94 //! Consider the `write_line` method defined for I/O types
95 //! by the [`Writer`](../io/trait.Writer.html) trait:
96 //!
97 //! ~~~
98 //! use std::io::IoError;
99 //!
100 //! trait Writer {
101 //! fn write_line(&mut self, s: &str) -> Result<(), IoError>;
102 //! }
103 //! ~~~
104 //!
105 //! *Note: The actual definition of `Writer` uses `IoResult`, which
106 //! is just a synonym for `Result<T, IoError>`.*
107 //!
108 //! This method doesn`t produce a value, but the write may
109 //! fail. It's crucial to handle the error case, and *not* write
110 //! something like this:
111 //!
112 //! ~~~ignore
113 //! use std::io::{File, Open, Write};
114 //!
115 //! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
116 //! // If `write_line` errors, then we'll never know, because the return
117 //! // value is ignored.
118 //! file.write_line("important message");
119 //! drop(file);
120 //! ~~~
121 //!
122 //! If you *do* write that in Rust, the compiler will by give you a
123 //! warning (by default, controlled by the `unused_must_use` lint).
124 //!
125 //! You might instead, if you don't want to handle the error, simply
126 //! fail, by converting to an `Option` with `ok`, then asserting
127 //! success with `expect`. This will fail if the write fails, proving
128 //! a marginally useful message indicating why:
129 //!
130 //! ~~~no_run
131 //! use std::io::{File, Open, Write};
132 //!
133 //! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
134 //! file.write_line("important message").ok().expect("failed to write message");
135 //! drop(file);
136 //! ~~~
137 //!
138 //! You might also simply assert success:
139 //!
140 //! ~~~no_run
141 //! # use std::io::{File, Open, Write};
142 //!
143 //! # let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
144 //! assert!(file.write_line("important message").is_ok());
145 //! # drop(file);
146 //! ~~~
147 //!
148 //! Or propagate the error up the call stack with `try!`:
149 //!
150 //! ~~~
151 //! # use std::io::{File, Open, Write, IoError};
152 //! fn write_message() -> Result<(), IoError> {
153 //! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
154 //! try!(file.write_line("important message"));
155 //! drop(file);
156 //! return Ok(());
157 //! }
158 //! ~~~
159 //!
160 //! # The `try!` macro
161 //!
162 //! When writing code that calls many functions that return the
163 //! `Result` type, the error handling can be tedious. The `try!`
164 //! macro hides some of the boilerplate of propagating errors up the
165 //! call stack.
166 //!
167 //! It replaces this:
168 //!
169 //! ~~~
170 //! use std::io::{File, Open, Write, IoError};
171 //!
172 //! struct Info { name: ~str, age: int, rating: int }
173 //!
174 //! fn write_info(info: &Info) -> Result<(), IoError> {
175 //! let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write);
176 //! // Early return on error
177 //! match file.write_line(format!("name: {}", info.name)) {
178 //! Ok(_) => (),
179 //! Err(e) => return Err(e)
180 //! }
181 //! match file.write_line(format!("age: {}", info.age)) {
182 //! Ok(_) => (),
183 //! Err(e) => return Err(e)
184 //! }
185 //! return file.write_line(format!("rating: {}", info.rating));
186 //! }
187 //! ~~~
188 //!
189 //! With this:
190 //!
191 //! ~~~
192 //! use std::io::{File, Open, Write, IoError};
193 //!
194 //! struct Info { name: ~str, age: int, rating: int }
195 //!
196 //! fn write_info(info: &Info) -> Result<(), IoError> {
197 //! let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write);
198 //! // Early return on error
199 //! try!(file.write_line(format!("name: {}", info.name)));
200 //! try!(file.write_line(format!("age: {}", info.age)));
201 //! try!(file.write_line(format!("rating: {}", info.rating)));
202 //! return Ok(());
203 //! }
204 //! ~~~
205 //!
206 //! *It's much nicer!*
207 //!
208 //! Wrapping an expression in `try!` will result in the unwrapped
209 //! success (`Ok`) value, unless the result is `Err`, in which case
210 //! `Err` is returned early from the enclosing function. Its simple definition
211 //! makes it clear:
212 //!
213 //! ~~~
214 //! # #![feature(macro_rules)]
215 //! macro_rules! try(
216 //! ($e:expr) => (match $e { Ok(e) => e, Err(e) => return Err(e) })
217 //! )
218 //! # fn main() { }
219 //! ~~~
220 //!
221 //! `try!` is imported by the prelude, and is available everywhere.
222 //!
223 //! # `Result` and `Option`
224 //!
225 //! The `Result` and [`Option`](../option/index.html) types are
226 //! similar and complementary: they are often employed to indicate a
227 //! lack of a return value; and they are trivially converted between
228 //! each other, so `Result`s are often handled by first converting to
229 //! `Option` with the [`ok`](enum.Result.html#method.ok) and
230 //! [`err`](enum.Result.html#method.ok) methods.
231 //!
232 //! Whereas `Option` only indicates the lack of a value, `Result` is
233 //! specifically for error reporting, and carries with it an error
234 //! value. Sometimes `Option` is used for indicating errors, but this
235 //! is only for simple cases and is generally discouraged. Even when
236 //! there is no useful error value to return, prefer `Result<T, ()>`.
237 //!
238 //! Converting to an `Option` with `ok()` to handle an error:
239 //!
240 //! ~~~
241 //! use std::io::Timer;
242 //! let mut t = Timer::new().ok().expect("failed to create timer!");
243 //! ~~~
244 //!
245 //! # `Result` vs. `fail!`
246 //!
247 //! `Result` is for recoverable errors; `fail!` is for unrecoverable
248 //! errors. Callers should always be able to avoid failure if they
249 //! take the proper precautions, for example, calling `is_some()`
250 //! on an `Option` type before calling `unwrap`.
251 //!
252 //! The suitability of `fail!` as an error handling mechanism is
253 //! limited by Rust's lack of any way to "catch" and resume execution
254 //! from a thrown exception. Therefore using failure for error
255 //! handling requires encapsulating fallable code in a task. Calling
256 //! the `fail!` macro, or invoking `fail!` indirectly should be
257 //! avoided as an error reporting strategy. Failure is only for
258 //! unrecoverable errors and a failing task is typically the sign of
259 //! a bug.
260 //!
261 //! A module that instead returns `Results` is alerting the caller
262 //! that failure is possible, and providing precise control over how
263 //! it is handled.
264 //!
265 //! Furthermore, failure may not be recoverable at all, depending on
266 //! the context. The caller of `fail!` should assume that execution
267 //! will not resume after failure, that failure is catastrophic.
268
269 use fmt::Show;
270
271 pub use core::result::{Result, Ok, Err, collect, fold, fold_};
272
273 // FIXME: These traits should not exist. Once std::fmt is moved to libcore,
274 // these can once again become inherent methods on Result.
275
276 /// Temporary trait for unwrapping a result
277 pub trait ResultUnwrap<T, E> {
278 /// Unwraps a result, yielding the content of an `Ok`.
279 ///
280 /// Fails if the value is an `Err`.
281 fn unwrap(self) -> T;
282 }
283
284 /// Temporary trait for unwrapping the error of a result
285 pub trait ResultUnwrapErr<T, E> {
286 /// Unwraps a result, yielding the content of an `Err`.
287 ///
288 /// Fails if the value is an `Ok`.
289 fn unwrap_err(self) -> E;
290 }
291
292 impl<T, E: Show> ResultUnwrap<T, E> for Result<T, E> {
293 #[inline]
294 fn unwrap(self) -> T {
295 match self {
296 Ok(t) => t,
297 Err(e) =>
298 fail!("called `Result::unwrap()` on an `Err` value: {}", e)
299 }
300 }
301 }
302
303 impl<T: Show, E> ResultUnwrapErr<T, E> for Result<T, E> {
304 #[inline]
305 fn unwrap_err(self) -> E {
306 match self {
307 Ok(t) =>
308 fail!("called `Result::unwrap_err()` on an `Ok` value: {}", t),
309 Err(e) => e
310 }
311 }
312 }