src/libcore/result.rs

   1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
   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, E>` 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](../../std/io/index.html).
  28 //!
  29 //! A simple function returning `Result` might be
  30 //! defined and used like so:
  31 //!
  32 //! ```
  33 //! #[derive(Debug)]
  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(Version::Version1),
  42 //!         2 => Ok(Version::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 with 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::old_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::old_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 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 //! panic, by converting to an `Option` with `ok`, then asserting
 127 //! success with `expect`. This will panic if the write fails, proving
 128 //! a marginally useful message indicating why:
 129 //!
 130 //! ```{.no_run}
 131 //! use std::old_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::old_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::old_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::old_io::{File, Open, Write, IoError};
 171 //!
 172 //! struct Info {
 173 //!     name: String,
 174 //!     age: int,
 175 //!     rating: int
 176 //! }
 177 //!
 178 //! fn write_info(info: &Info) -> Result<(), IoError> {
 179 //!     let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write);
 180 //!     // Early return on error
 181 //!     if let Err(e) = file.write_line(format!("name: {}", info.name).as_slice()) {
 182 //!         return Err(e)
 183 //!     }
 184 //!     if let Err(e) = file.write_line(format!("age: {}", info.age).as_slice()) {
 185 //!         return Err(e)
 186 //!     }
 187 //!     return file.write_line(format!("rating: {}", info.rating).as_slice());
 188 //! }
 189 //! ```
 190 //!
 191 //! With this:
 192 //!
 193 //! ```
 194 //! use std::old_io::{File, Open, Write, IoError};
 195 //!
 196 //! struct Info {
 197 //!     name: String,
 198 //!     age: int,
 199 //!     rating: int
 200 //! }
 201 //!
 202 //! fn write_info(info: &Info) -> Result<(), IoError> {
 203 //!     let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write);
 204 //!     // Early return on error
 205 //!     try!(file.write_line(format!("name: {}", info.name).as_slice()));
 206 //!     try!(file.write_line(format!("age: {}", info.age).as_slice()));
 207 //!     try!(file.write_line(format!("rating: {}", info.rating).as_slice()));
 208 //!     return Ok(());
 209 //! }
 210 //! ```
 211 //!
 212 //! *It's much nicer!*
 213 //!
 214 //! Wrapping an expression in `try!` will result in the unwrapped
 215 //! success (`Ok`) value, unless the result is `Err`, in which case
 216 //! `Err` is returned early from the enclosing function. Its simple definition
 217 //! makes it clear:
 218 //!
 219 //! ```
 220 //! macro_rules! try {
 221 //!     ($e:expr) => (match $e { Ok(e) => e, Err(e) => return Err(e) })
 222 //! }
 223 //! ```
 224 //!
 225 //! `try!` is imported by the prelude, and is available everywhere.
 226
 227 #![stable(feature = "rust1", since = "1.0.0")]
 228
 229 use self::Result::{Ok, Err};
 230
 231 use clone::Clone;
 232 use fmt;
 233 use iter::{Iterator, IteratorExt, DoubleEndedIterator, FromIterator, ExactSizeIterator};
 234 use ops::{FnMut, FnOnce};
 235 use option::Option::{self, None, Some};
 236 use slice::AsSlice;
 237 use slice;
 238
 239 /// `Result` is a type that represents either success (`Ok`) or failure (`Err`).
 240 ///
 241 /// See the [`std::result`](index.html) module documentation for details.
 242 #[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
 243 #[must_use]
 244 #[stable(feature = "rust1", since = "1.0.0")]
 245 pub enum Result<T, E> {
 246     /// Contains the success value
 247     #[stable(feature = "rust1", since = "1.0.0")]
 248     Ok(T),
 249
 250     /// Contains the error value
 251     #[stable(feature = "rust1", since = "1.0.0")]
 252     Err(E)
 253 }
 254
 255 /////////////////////////////////////////////////////////////////////////////
 256 // Type implementation
 257 /////////////////////////////////////////////////////////////////////////////
 258
 259 #[stable(feature = "rust1", since = "1.0.0")]
 260 impl<T, E> Result<T, E> {
 261     /////////////////////////////////////////////////////////////////////////
 262     // Querying the contained values
 263     /////////////////////////////////////////////////////////////////////////
 264
 265     /// Returns true if the result is `Ok`
 266     ///
 267     /// # Example
 268     ///
 269     /// ```
 270     /// let x: Result<int, &str> = Ok(-3);
 271     /// assert_eq!(x.is_ok(), true);
 272     ///
 273     /// let x: Result<int, &str> = Err("Some error message");
 274     /// assert_eq!(x.is_ok(), false);
 275     /// ```
 276     #[inline]
 277     #[stable(feature = "rust1", since = "1.0.0")]
 278     pub fn is_ok(&self) -> bool {
 279         match *self {
 280             Ok(_) => true,
 281             Err(_) => false
 282         }
 283     }
 284
 285     /// Returns true if the result is `Err`
 286     ///
 287     /// # Example
 288     ///
 289     /// ```
 290     /// let x: Result<int, &str> = Ok(-3);
 291     /// assert_eq!(x.is_err(), false);
 292     ///
 293     /// let x: Result<int, &str> = Err("Some error message");
 294     /// assert_eq!(x.is_err(), true);
 295     /// ```
 296     #[inline]
 297     #[stable(feature = "rust1", since = "1.0.0")]
 298     pub fn is_err(&self) -> bool {
 299         !self.is_ok()
 300     }
 301
 302     /////////////////////////////////////////////////////////////////////////
 303     // Adapter for each variant
 304     /////////////////////////////////////////////////////////////////////////
 305
 306     /// Convert from `Result<T, E>` to `Option<T>`
 307     ///
 308     /// Converts `self` into an `Option<T>`, consuming `self`,
 309     /// and discarding the error, if any.
 310     ///
 311     /// # Example
 312     ///
 313     /// ```
 314     /// let x: Result<uint, &str> = Ok(2);
 315     /// assert_eq!(x.ok(), Some(2));
 316     ///
 317     /// let x: Result<uint, &str> = Err("Nothing here");
 318     /// assert_eq!(x.ok(), None);
 319     /// ```
 320     #[inline]
 321     #[stable(feature = "rust1", since = "1.0.0")]
 322     pub fn ok(self) -> Option<T> {
 323         match self {
 324             Ok(x)  => Some(x),
 325             Err(_) => None,
 326         }
 327     }
 328
 329     /// Convert from `Result<T, E>` to `Option<E>`
 330     ///
 331     /// Converts `self` into an `Option<E>`, consuming `self`,
 332     /// and discarding the value, if any.
 333     ///
 334     /// # Example
 335     ///
 336     /// ```
 337     /// let x: Result<uint, &str> = Ok(2);
 338     /// assert_eq!(x.err(), None);
 339     ///
 340     /// let x: Result<uint, &str> = Err("Nothing here");
 341     /// assert_eq!(x.err(), Some("Nothing here"));
 342     /// ```
 343     #[inline]
 344     #[stable(feature = "rust1", since = "1.0.0")]
 345     pub fn err(self) -> Option<E> {
 346         match self {
 347             Ok(_)  => None,
 348             Err(x) => Some(x),
 349         }
 350     }
 351
 352     /////////////////////////////////////////////////////////////////////////
 353     // Adapter for working with references
 354     /////////////////////////////////////////////////////////////////////////
 355
 356     /// Convert from `Result<T, E>` to `Result<&T, &E>`
 357     ///
 358     /// Produces a new `Result`, containing a reference
 359     /// into the original, leaving the original in place.
 360     ///
 361     /// ```
 362     /// let x: Result<uint, &str> = Ok(2);
 363     /// assert_eq!(x.as_ref(), Ok(&2));
 364     ///
 365     /// let x: Result<uint, &str> = Err("Error");
 366     /// assert_eq!(x.as_ref(), Err(&"Error"));
 367     /// ```
 368     #[inline]
 369     #[stable(feature = "rust1", since = "1.0.0")]
 370     pub fn as_ref(&self) -> Result<&T, &E> {
 371         match *self {
 372             Ok(ref x) => Ok(x),
 373             Err(ref x) => Err(x),
 374         }
 375     }
 376
 377     /// Convert from `Result<T, E>` to `Result<&mut T, &mut E>`
 378     ///
 379     /// ```
 380     /// fn mutate(r: &mut Result<int, int>) {
 381     ///     match r.as_mut() {
 382     ///         Ok(&mut ref mut v) => *v = 42,
 383     ///         Err(&mut ref mut e) => *e = 0,
 384     ///     }
 385     /// }
 386     ///
 387     /// let mut x: Result<int, int> = Ok(2);
 388     /// mutate(&mut x);
 389     /// assert_eq!(x.unwrap(), 42);
 390     ///
 391     /// let mut x: Result<int, int> = Err(13);
 392     /// mutate(&mut x);
 393     /// assert_eq!(x.unwrap_err(), 0);
 394     /// ```
 395     #[inline]
 396     #[stable(feature = "rust1", since = "1.0.0")]
 397     pub fn as_mut(&mut self) -> Result<&mut T, &mut E> {
 398         match *self {
 399             Ok(ref mut x) => Ok(x),
 400             Err(ref mut x) => Err(x),
 401         }
 402     }
 403
 404     /// Convert from `Result<T, E>` to `&mut [T]` (without copying)
 405     ///
 406     /// ```
 407     /// let mut x: Result<&str, uint> = Ok("Gold");
 408     /// {
 409     ///     let v = x.as_mut_slice();
 410     ///     assert!(v == ["Gold"]);
 411     ///     v[0] = "Silver";
 412     ///     assert!(v == ["Silver"]);
 413     /// }
 414     /// assert_eq!(x, Ok("Silver"));
 415     ///
 416     /// let mut x: Result<&str, uint> = Err(45);
 417     /// assert!(x.as_mut_slice().is_empty());
 418     /// ```
 419     #[inline]
 420     #[unstable(feature = "core",
 421                reason = "waiting for mut conventions")]
 422     pub fn as_mut_slice(&mut self) -> &mut [T] {
 423         match *self {
 424             Ok(ref mut x) => slice::mut_ref_slice(x),
 425             Err(_) => {
 426                 // work around lack of implicit coercion from fixed-size array to slice
 427                 let emp: &mut [_] = &mut [];
 428                 emp
 429             }
 430         }
 431     }
 432
 433     /////////////////////////////////////////////////////////////////////////
 434     // Transforming contained values
 435     /////////////////////////////////////////////////////////////////////////
 436
 437     /// Maps a `Result<T, E>` to `Result<U, E>` by applying a function to an
 438     /// contained `Ok` value, leaving an `Err` value untouched.
 439     ///
 440     /// This function can be used to compose the results of two functions.
 441     ///
 442     /// # Example
 443     ///
 444     /// Sum the lines of a buffer by mapping strings to numbers,
 445     /// ignoring I/O and parse errors:
 446     ///
 447     /// ```
 448     /// use std::old_io::IoResult;
 449     ///
 450     /// let mut buffer = &mut b"1\n2\n3\n4\n";
 451     ///
 452     /// let mut sum = 0;
 453     ///
 454     /// while !buffer.is_empty() {
 455     ///     let line: IoResult<String> = buffer.read_line();
 456     ///     // Convert the string line to a number using `map` and `from_str`
 457     ///     let val: IoResult<int> = line.map(|line| {
 458     ///         line.trim_right().parse::<int>().unwrap_or(0)
 459     ///     });
 460     ///     // Add the value if there were no errors, otherwise add 0
 461     ///     sum += val.ok().unwrap_or(0);
 462     /// }
 463     ///
 464     /// assert!(sum == 10);
 465     /// ```
 466     #[inline]
 467     #[stable(feature = "rust1", since = "1.0.0")]
 468     pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> Result<U,E> {
 469         match self {
 470             Ok(t) => Ok(op(t)),
 471             Err(e) => Err(e)
 472         }
 473     }
 474
 475     /// Maps a `Result<T, E>` to `Result<T, F>` by applying a function to an
 476     /// contained `Err` value, leaving an `Ok` value untouched.
 477     ///
 478     /// This function can be used to pass through a successful result while handling
 479     /// an error.
 480     ///
 481     /// # Example
 482     ///
 483     /// ```
 484     /// fn stringify(x: uint) -> String { format!("error code: {}", x) }
 485     ///
 486     /// let x: Result<uint, uint> = Ok(2);
 487     /// assert_eq!(x.map_err(stringify), Ok(2));
 488     ///
 489     /// let x: Result<uint, uint> = Err(13);
 490     /// assert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));
 491     /// ```
 492     #[inline]
 493     #[stable(feature = "rust1", since = "1.0.0")]
 494     pub fn map_err<F, O: FnOnce(E) -> F>(self, op: O) -> Result<T,F> {
 495         match self {
 496             Ok(t) => Ok(t),
 497             Err(e) => Err(op(e))
 498         }
 499     }
 500
 501     /////////////////////////////////////////////////////////////////////////
 502     // Iterator constructors
 503     /////////////////////////////////////////////////////////////////////////
 504
 505     /// Returns an iterator over the possibly contained value.
 506     ///
 507     /// # Example
 508     ///
 509     /// ```
 510     /// let x: Result<uint, &str> = Ok(7);
 511     /// assert_eq!(x.iter().next(), Some(&7));
 512     ///
 513     /// let x: Result<uint, &str> = Err("nothing!");
 514     /// assert_eq!(x.iter().next(), None);
 515     /// ```
 516     #[inline]
 517     #[stable(feature = "rust1", since = "1.0.0")]
 518     pub fn iter(&self) -> Iter<T> {
 519         Iter { inner: self.as_ref().ok() }
 520     }
 521
 522     /// Returns a mutable iterator over the possibly contained value.
 523     ///
 524     /// # Example
 525     ///
 526     /// ```
 527     /// let mut x: Result<uint, &str> = Ok(7);
 528     /// match x.iter_mut().next() {
 529     ///     Some(&mut ref mut x) => *x = 40,
 530     ///     None => {},
 531     /// }
 532     /// assert_eq!(x, Ok(40));
 533     ///
 534     /// let mut x: Result<uint, &str> = Err("nothing!");
 535     /// assert_eq!(x.iter_mut().next(), None);
 536     /// ```
 537     #[inline]
 538     #[stable(feature = "rust1", since = "1.0.0")]
 539     pub fn iter_mut(&mut self) -> IterMut<T> {
 540         IterMut { inner: self.as_mut().ok() }
 541     }
 542
 543     /// Returns a consuming iterator over the possibly contained value.
 544     ///
 545     /// # Example
 546     ///
 547     /// ```
 548     /// let x: Result<uint, &str> = Ok(5);
 549     /// let v: Vec<uint> = x.into_iter().collect();
 550     /// assert_eq!(v, vec![5]);
 551     ///
 552     /// let x: Result<uint, &str> = Err("nothing!");
 553     /// let v: Vec<uint> = x.into_iter().collect();
 554     /// assert_eq!(v, vec![]);
 555     /// ```
 556     #[inline]
 557     #[stable(feature = "rust1", since = "1.0.0")]
 558     pub fn into_iter(self) -> IntoIter<T> {
 559         IntoIter { inner: self.ok() }
 560     }
 561
 562     ////////////////////////////////////////////////////////////////////////
 563     // Boolean operations on the values, eager and lazy
 564     /////////////////////////////////////////////////////////////////////////
 565
 566     /// Returns `res` if the result is `Ok`, otherwise returns the `Err` value of `self`.
 567     ///
 568     /// # Example
 569     ///
 570     /// ```
 571     /// let x: Result<uint, &str> = Ok(2);
 572     /// let y: Result<&str, &str> = Err("late error");
 573     /// assert_eq!(x.and(y), Err("late error"));
 574     ///
 575     /// let x: Result<uint, &str> = Err("early error");
 576     /// let y: Result<&str, &str> = Ok("foo");
 577     /// assert_eq!(x.and(y), Err("early error"));
 578     ///
 579     /// let x: Result<uint, &str> = Err("not a 2");
 580     /// let y: Result<&str, &str> = Err("late error");
 581     /// assert_eq!(x.and(y), Err("not a 2"));
 582     ///
 583     /// let x: Result<uint, &str> = Ok(2);
 584     /// let y: Result<&str, &str> = Ok("different result type");
 585     /// assert_eq!(x.and(y), Ok("different result type"));
 586     /// ```
 587     #[inline]
 588     #[stable(feature = "rust1", since = "1.0.0")]
 589     pub fn and<U>(self, res: Result<U, E>) -> Result<U, E> {
 590         match self {
 591             Ok(_) => res,
 592             Err(e) => Err(e),
 593         }
 594     }
 595
 596     /// Calls `op` if the result is `Ok`, otherwise returns the `Err` value of `self`.
 597     ///
 598     /// This function can be used for control flow based on result values.
 599     ///
 600     /// # Example
 601     ///
 602     /// ```
 603     /// fn sq(x: uint) -> Result<uint, uint> { Ok(x * x) }
 604     /// fn err(x: uint) -> Result<uint, uint> { Err(x) }
 605     ///
 606     /// assert_eq!(Ok(2).and_then(sq).and_then(sq), Ok(16));
 607     /// assert_eq!(Ok(2).and_then(sq).and_then(err), Err(4));
 608     /// assert_eq!(Ok(2).and_then(err).and_then(sq), Err(2));
 609     /// assert_eq!(Err(3).and_then(sq).and_then(sq), Err(3));
 610     /// ```
 611     #[inline]
 612     #[stable(feature = "rust1", since = "1.0.0")]
 613     pub fn and_then<U, F: FnOnce(T) -> Result<U, E>>(self, op: F) -> Result<U, E> {
 614         match self {
 615             Ok(t) => op(t),
 616             Err(e) => Err(e),
 617         }
 618     }
 619
 620     /// Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`.
 621     ///
 622     /// # Example
 623     ///
 624     /// ```
 625     /// let x: Result<uint, &str> = Ok(2);
 626     /// let y: Result<uint, &str> = Err("late error");
 627     /// assert_eq!(x.or(y), Ok(2));
 628     ///
 629     /// let x: Result<uint, &str> = Err("early error");
 630     /// let y: Result<uint, &str> = Ok(2);
 631     /// assert_eq!(x.or(y), Ok(2));
 632     ///
 633     /// let x: Result<uint, &str> = Err("not a 2");
 634     /// let y: Result<uint, &str> = Err("late error");
 635     /// assert_eq!(x.or(y), Err("late error"));
 636     ///
 637     /// let x: Result<uint, &str> = Ok(2);
 638     /// let y: Result<uint, &str> = Ok(100);
 639     /// assert_eq!(x.or(y), Ok(2));
 640     /// ```
 641     #[inline]
 642     #[stable(feature = "rust1", since = "1.0.0")]
 643     pub fn or(self, res: Result<T, E>) -> Result<T, E> {
 644         match self {
 645             Ok(_) => self,
 646             Err(_) => res,
 647         }
 648     }
 649
 650     /// Calls `op` if the result is `Err`, otherwise returns the `Ok` value of `self`.
 651     ///
 652     /// This function can be used for control flow based on result values.
 653     ///
 654     /// # Example
 655     ///
 656     /// ```
 657     /// fn sq(x: uint) -> Result<uint, uint> { Ok(x * x) }
 658     /// fn err(x: uint) -> Result<uint, uint> { Err(x) }
 659     ///
 660     /// assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));
 661     /// assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));
 662     /// assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));
 663     /// assert_eq!(Err(3).or_else(err).or_else(err), Err(3));
 664     /// ```
 665     #[inline]
 666     #[stable(feature = "rust1", since = "1.0.0")]
 667     pub fn or_else<F, O: FnOnce(E) -> Result<T, F>>(self, op: O) -> Result<T, F> {
 668         match self {
 669             Ok(t) => Ok(t),
 670             Err(e) => op(e),
 671         }
 672     }
 673
 674     /// Unwraps a result, yielding the content of an `Ok`.
 675     /// Else it returns `optb`.
 676     ///
 677     /// # Example
 678     ///
 679     /// ```
 680     /// let optb = 2;
 681     /// let x: Result<uint, &str> = Ok(9);
 682     /// assert_eq!(x.unwrap_or(optb), 9);
 683     ///
 684     /// let x: Result<uint, &str> = Err("error");
 685     /// assert_eq!(x.unwrap_or(optb), optb);
 686     /// ```
 687     #[inline]
 688     #[stable(feature = "rust1", since = "1.0.0")]
 689     pub fn unwrap_or(self, optb: T) -> T {
 690         match self {
 691             Ok(t) => t,
 692             Err(_) => optb
 693         }
 694     }
 695
 696     /// Unwraps a result, yielding the content of an `Ok`.
 697     /// If the value is an `Err` then it calls `op` with its value.
 698     ///
 699     /// # Example
 700     ///
 701     /// ```
 702     /// fn count(x: &str) -> uint { x.len() }
 703     ///
 704     /// assert_eq!(Ok(2).unwrap_or_else(count), 2);
 705     /// assert_eq!(Err("foo").unwrap_or_else(count), 3);
 706     /// ```
 707     #[inline]
 708     #[stable(feature = "rust1", since = "1.0.0")]
 709     pub fn unwrap_or_else<F: FnOnce(E) -> T>(self, op: F) -> T {
 710         match self {
 711             Ok(t) => t,
 712             Err(e) => op(e)
 713         }
 714     }
 715 }
 716
 717 #[stable(feature = "rust1", since = "1.0.0")]
 718 impl<T, E: fmt::Debug> Result<T, E> {
 719     /// Unwraps a result, yielding the content of an `Ok`.
 720     ///
 721     /// # Panics
 722     ///
 723     /// Panics if the value is an `Err`, with a custom panic message provided
 724     /// by the `Err`'s value.
 725     ///
 726     /// # Example
 727     ///
 728     /// ```
 729     /// let x: Result<uint, &str> = Ok(2);
 730     /// assert_eq!(x.unwrap(), 2);
 731     /// ```
 732     ///
 733     /// ```{.should_fail}
 734     /// let x: Result<uint, &str> = Err("emergency failure");
 735     /// x.unwrap(); // panics with `emergency failure`
 736     /// ```
 737     #[inline]
 738     #[stable(feature = "rust1", since = "1.0.0")]
 739     pub fn unwrap(self) -> T {
 740         match self {
 741             Ok(t) => t,
 742             Err(e) =>
 743                 panic!("called `Result::unwrap()` on an `Err` value: {:?}", e)
 744         }
 745     }
 746 }
 747
 748 #[stable(feature = "rust1", since = "1.0.0")]
 749 impl<T: fmt::Debug, E> Result<T, E> {
 750     /// Unwraps a result, yielding the content of an `Err`.
 751     ///
 752     /// # Panics
 753     ///
 754     /// Panics if the value is an `Ok`, with a custom panic message provided
 755     /// by the `Ok`'s value.
 756     ///
 757     /// # Example
 758     ///
 759     /// ```{.should_fail}
 760     /// let x: Result<uint, &str> = Ok(2);
 761     /// x.unwrap_err(); // panics with `2`
 762     /// ```
 763     ///
 764     /// ```
 765     /// let x: Result<uint, &str> = Err("emergency failure");
 766     /// assert_eq!(x.unwrap_err(), "emergency failure");
 767     /// ```
 768     #[inline]
 769     #[stable(feature = "rust1", since = "1.0.0")]
 770     pub fn unwrap_err(self) -> E {
 771         match self {
 772             Ok(t) =>
 773                 panic!("called `Result::unwrap_err()` on an `Ok` value: {:?}", t),
 774             Err(e) => e
 775         }
 776     }
 777 }
 778
 779 /////////////////////////////////////////////////////////////////////////////
 780 // Trait implementations
 781 /////////////////////////////////////////////////////////////////////////////
 782
 783 impl<T, E> AsSlice<T> for Result<T, E> {
 784     /// Convert from `Result<T, E>` to `&[T]` (without copying)
 785     #[inline]
 786     #[stable(feature = "rust1", since = "1.0.0")]
 787     fn as_slice<'a>(&'a self) -> &'a [T] {
 788         match *self {
 789             Ok(ref x) => slice::ref_slice(x),
 790             Err(_) => {
 791                 // work around lack of implicit coercion from fixed-size array to slice
 792                 let emp: &[_] = &[];
 793                 emp
 794             }
 795         }
 796     }
 797 }
 798
 799 /////////////////////////////////////////////////////////////////////////////
 800 // The Result Iterators
 801 /////////////////////////////////////////////////////////////////////////////
 802
 803 /// An iterator over a reference to the `Ok` variant of a `Result`.
 804 #[stable(feature = "rust1", since = "1.0.0")]
 805 pub struct Iter<'a, T: 'a> { inner: Option<&'a T> }
 806
 807 #[stable(feature = "rust1", since = "1.0.0")]
 808 impl<'a, T> Iterator for Iter<'a, T> {
 809     type Item = &'a T;
 810
 811     #[inline]
 812     fn next(&mut self) -> Option<&'a T> { self.inner.take() }
 813     #[inline]
 814     fn size_hint(&self) -> (uint, Option<uint>) {
 815         let n = if self.inner.is_some() {1} else {0};
 816         (n, Some(n))
 817     }
 818 }
 819
 820 #[stable(feature = "rust1", since = "1.0.0")]
 821 impl<'a, T> DoubleEndedIterator for Iter<'a, T> {
 822     #[inline]
 823     fn next_back(&mut self) -> Option<&'a T> { self.inner.take() }
 824 }
 825
 826 #[stable(feature = "rust1", since = "1.0.0")]
 827 impl<'a, T> ExactSizeIterator for Iter<'a, T> {}
 828
 829 impl<'a, T> Clone for Iter<'a, T> {
 830     fn clone(&self) -> Iter<'a, T> { Iter { inner: self.inner } }
 831 }
 832
 833 /// An iterator over a mutable reference to the `Ok` variant of a `Result`.
 834 #[stable(feature = "rust1", since = "1.0.0")]
 835 pub struct IterMut<'a, T: 'a> { inner: Option<&'a mut T> }
 836
 837 #[stable(feature = "rust1", since = "1.0.0")]
 838 impl<'a, T> Iterator for IterMut<'a, T> {
 839     type Item = &'a mut T;
 840
 841     #[inline]
 842     fn next(&mut self) -> Option<&'a mut T> { self.inner.take() }
 843     #[inline]
 844     fn size_hint(&self) -> (uint, Option<uint>) {
 845         let n = if self.inner.is_some() {1} else {0};
 846         (n, Some(n))
 847     }
 848 }
 849
 850 #[stable(feature = "rust1", since = "1.0.0")]
 851 impl<'a, T> DoubleEndedIterator for IterMut<'a, T> {
 852     #[inline]
 853     fn next_back(&mut self) -> Option<&'a mut T> { self.inner.take() }
 854 }
 855
 856 #[stable(feature = "rust1", since = "1.0.0")]
 857 impl<'a, T> ExactSizeIterator for IterMut<'a, T> {}
 858
 859 /// An iterator over the value in a `Ok` variant of a `Result`.
 860 #[stable(feature = "rust1", since = "1.0.0")]
 861 pub struct IntoIter<T> { inner: Option<T> }
 862
 863 #[stable(feature = "rust1", since = "1.0.0")]
 864 impl<T> Iterator for IntoIter<T> {
 865     type Item = T;
 866
 867     #[inline]
 868     fn next(&mut self) -> Option<T> { self.inner.take() }
 869     #[inline]
 870     fn size_hint(&self) -> (uint, Option<uint>) {
 871         let n = if self.inner.is_some() {1} else {0};
 872         (n, Some(n))
 873     }
 874 }
 875
 876 #[stable(feature = "rust1", since = "1.0.0")]
 877 impl<T> DoubleEndedIterator for IntoIter<T> {
 878     #[inline]
 879     fn next_back(&mut self) -> Option<T> { self.inner.take() }
 880 }
 881
 882 #[stable(feature = "rust1", since = "1.0.0")]
 883 impl<T> ExactSizeIterator for IntoIter<T> {}
 884
 885 /////////////////////////////////////////////////////////////////////////////
 886 // FromIterator
 887 /////////////////////////////////////////////////////////////////////////////
 888
 889 #[stable(feature = "rust1", since = "1.0.0")]
 890 impl<A, E, V: FromIterator<A>> FromIterator<Result<A, E>> for Result<V, E> {
 891     /// Takes each element in the `Iterator`: if it is an `Err`, no further
 892     /// elements are taken, and the `Err` is returned. Should no `Err` occur, a
 893     /// container with the values of each `Result` is returned.
 894     ///
 895     /// Here is an example which increments every integer in a vector,
 896     /// checking for overflow:
 897     ///
 898     /// ```rust
 899     /// use std::uint;
 900     ///
 901     /// let v = vec!(1, 2);
 902     /// let res: Result<Vec<uint>, &'static str> = v.iter().map(|&x: &uint|
 903     ///     if x == uint::MAX { Err("Overflow!") }
 904     ///     else { Ok(x + 1) }
 905     /// ).collect();
 906     /// assert!(res == Ok(vec!(2, 3)));
 907     /// ```
 908     #[inline]
 909     fn from_iter<I: Iterator<Item=Result<A, E>>>(iter: I) -> Result<V, E> {
 910         // FIXME(#11084): This could be replaced with Iterator::scan when this
 911         // performance bug is closed.
 912
 913         struct Adapter<Iter, E> {
 914             iter: Iter,
 915             err: Option<E>,
 916         }
 917
 918         impl<T, E, Iter: Iterator<Item=Result<T, E>>> Iterator for Adapter<Iter, E> {
 919             type Item = T;
 920
 921             #[inline]
 922             fn next(&mut self) -> Option<T> {
 923                 match self.iter.next() {
 924                     Some(Ok(value)) => Some(value),
 925                     Some(Err(err)) => {
 926                         self.err = Some(err);
 927                         None
 928                     }
 929                     None => None,
 930                 }
 931             }
 932         }
 933
 934         let mut adapter = Adapter { iter: iter, err: None };
 935         let v: V = FromIterator::from_iter(adapter.by_ref());
 936
 937         match adapter.err {
 938             Some(err) => Err(err),
 939             None => Ok(v),
 940         }
 941     }
 942 }
 943
 944 /////////////////////////////////////////////////////////////////////////////
 945 // FromIterator
 946 /////////////////////////////////////////////////////////////////////////////
 947
 948 /// Perform a fold operation over the result values from an iterator.
 949 ///
 950 /// If an `Err` is encountered, it is immediately returned.
 951 /// Otherwise, the folded value is returned.
 952 #[inline]
 953 #[unstable(feature = "core")]
 954 pub fn fold<T,
 955             V,
 956             E,
 957             F: FnMut(V, T) -> V,
 958             Iter: Iterator<Item=Result<T, E>>>(
 959             mut iterator: Iter,
 960             mut init: V,
 961             mut f: F)
 962             -> Result<V, E> {
 963     for t in iterator {
 964         match t {
 965             Ok(v) => init = f(init, v),
 966             Err(u) => return Err(u)
 967         }
 968     }
 969     Ok(init)
 970 }