diff options
| -rw-r--r-- | src/libcore/result.rs | 256 |
1 files changed, 228 insertions, 28 deletions
diff --git a/src/libcore/result.rs b/src/libcore/result.rs index 9b533a72ad7..9f347aacedc 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -311,14 +311,13 @@ impl<T, E> Result<T, E> { /// /// # Example /// - /// ~~~ - /// use std::io::{File, Open, Write}; - /// - /// # fn do_not_run_example() { // creates a file - /// let mut file = File::open_mode(&Path::new("secret.txt"), Open, Write); - /// assert!(file.write_line("it's cold in here").is_ok()); - /// # } - /// ~~~ + /// ``` + /// let x: Result<int, &str> = Ok(-3); + /// assert_eq!(x.is_ok(), true); + /// + /// let x: Result<int, &str> = Err("Some error message"); + /// assert_eq!(x.is_ok(), false); + /// ``` #[inline] #[stable] pub fn is_ok(&self) -> bool { @@ -332,14 +331,13 @@ impl<T, E> Result<T, E> { /// /// # Example /// - /// ~~~ - /// use std::io::{File, Open, Read}; + /// ``` + /// let x: Result<int, &str> = Ok(-3); + /// assert_eq!(x.is_err(), false); /// - /// // When opening with `Read` access, if the file does not exist - /// // then `open_mode` returns an error. - /// let bogus = File::open_mode(&Path::new("not_a_file.txt"), Open, Read); - /// assert!(bogus.is_err()); - /// ~~~ + /// let x: Result<int, &str> = Err("Some error message"); + /// assert_eq!(x.is_err(), true); + /// ``` #[inline] #[stable] pub fn is_err(&self) -> bool { @@ -356,18 +354,15 @@ impl<T, E> Result<T, E> { /// Converts `self` into an `Option<T>`, consuming `self`, /// and discarding the error, if any. /// - /// To convert to an `Option` without discarding the error value, - /// use `as_ref` to first convert the `Result<T, E>` into a - /// `Result<&T, &E>`. - /// - /// # Examples + /// # Example /// - /// ~~~{.should_fail} - /// use std::io::{File, IoResult}; + /// ``` + /// let x: Result<uint, &str> = Ok(2); + /// assert_eq!(x.ok(), Some(2)); /// - /// let bdays: IoResult<File> = File::open(&Path::new("important_birthdays.txt")); - /// let bdays: File = bdays.ok().expect("unable to open birthday file"); - /// ~~~ + /// let x: Result<uint, &str> = Err("Nothing here"); + /// assert_eq!(x.ok(), None); + /// ``` #[inline] #[stable] pub fn ok(self) -> Option<T> { @@ -381,6 +376,16 @@ impl<T, E> Result<T, E> { /// /// Converts `self` into an `Option<T>`, consuming `self`, /// and discarding the value, if any. + /// + /// # Example + /// + /// ``` + /// let x: Result<uint, &str> = Ok(2); + /// assert_eq!(x.err(), None); + /// + /// let x: Result<uint, &str> = Err("Nothing here"); + /// assert_eq!(x.err(), Some("Nothing here")); + /// ``` #[inline] #[stable] pub fn err(self) -> Option<E> { @@ -398,6 +403,14 @@ impl<T, E> Result<T, E> { /// /// Produces a new `Result`, containing a reference /// into the original, leaving the original in place. + /// + /// ``` + /// let x: Result<uint, &str> = Ok(2); + /// assert_eq!(x.as_ref(), Ok(&2)); + /// + /// let x: Result<uint, &str> = Err("Error"); + /// assert_eq!(x.as_ref(), Err(&"Error")); + /// ``` #[inline] #[stable] pub fn as_ref<'r>(&'r self) -> Result<&'r T, &'r E> { @@ -408,6 +421,23 @@ impl<T, E> Result<T, E> { } /// Convert from `Result<T, E>` to `Result<&mut T, &mut E>` + /// + /// ``` + /// fn mutate(r: &mut Result<int, int>) { + /// match r.as_mut() { + /// Ok(&ref mut v) => *v = 42, + /// Err(&ref mut e) => *e = 0, + /// } + /// } + /// + /// let mut x: Result<int, int> = Ok(2); + /// mutate(&mut x); + /// assert_eq!(x.unwrap(), 42); + /// + /// let mut x: Result<int, int> = Err(13); + /// mutate(&mut x); + /// assert_eq!(x.unwrap_err(), 0); + /// ``` #[inline] #[unstable = "waiting for mut conventions"] pub fn as_mut<'r>(&'r mut self) -> Result<&'r mut T, &'r mut E> { @@ -418,6 +448,20 @@ impl<T, E> Result<T, E> { } /// Convert from `Result<T, E>` to `&mut [T]` (without copying) + /// + /// ``` + /// let mut x: Result<&str, uint> = Ok("Gold"); + /// { + /// let v = x.as_mut_slice(); + /// assert!(v == ["Gold"]); + /// v[0] = "Silver"; + /// assert!(v == ["Silver"]); + /// } + /// assert_eq!(x, Ok("Silver")); + /// + /// let mut x: Result<&str, uint> = Err(45); + /// assert!(x.as_mut_slice() == []); + /// ``` #[inline] #[unstable = "waiting for mut conventions"] pub fn as_mut_slice<'r>(&'r mut self) -> &'r mut [T] { @@ -479,6 +523,18 @@ impl<T, E> Result<T, E> { /// /// This function can be used to pass through a successful result while handling /// an error. + /// + /// # Example + /// + /// ``` + /// fn stringify(x: uint) -> String { format!("error code: {}", x) } + /// + /// let x: Result<uint, uint> = Ok(2u); + /// assert_eq!(x.map_err(stringify), Ok(2u)); + /// + /// let x: Result<uint, uint> = Err(13); + /// assert_eq!(x.map_err(stringify), Err("error code: 13".to_string())); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn map_err<F>(self, op: |E| -> F) -> Result<T,F> { @@ -494,6 +550,16 @@ impl<T, E> Result<T, E> { ///////////////////////////////////////////////////////////////////////// /// Returns an iterator over the possibly contained value. + /// + /// # Example + /// + /// ``` + /// let x: Result<uint, &str> = Ok(7); + /// assert_eq!(x.iter().next(), Some(&7)); + /// + /// let x: Result<uint, &str> = Err("nothing!"); + /// assert_eq!(x.iter().next(), None); + /// ``` #[inline] #[unstable = "waiting for iterator conventions"] pub fn iter<'r>(&'r self) -> Item<&'r T> { @@ -507,6 +573,20 @@ impl<T, E> Result<T, E> { } /// Returns a mutable iterator over the possibly contained value. + /// + /// # Example + /// + /// ``` + /// let mut x: Result<uint, &str> = Ok(7); + /// match x.iter_mut().next() { + /// Some(&ref mut x) => *x = 40, + /// None => {}, + /// } + /// assert_eq!(x, Ok(40)); + /// + /// let mut x: Result<uint, &str> = Err("nothing!"); + /// assert_eq!(x.iter_mut().next(), None); + /// ``` #[inline] #[unstable = "waiting for iterator conventions"] pub fn iter_mut<'r>(&'r mut self) -> Item<&'r mut T> { @@ -520,6 +600,18 @@ impl<T, E> Result<T, E> { } /// Returns a consuming iterator over the possibly contained value. + /// + /// # Example + /// + /// ``` + /// let x: Result<uint, &str> = Ok(5); + /// let v: Vec<uint> = x.into_iter().collect(); + /// assert_eq!(v, vec![5u]); + /// + /// let x: Result<uint, &str> = Err("nothing!"); + /// let v: Vec<uint> = x.into_iter().collect(); + /// assert_eq!(v, vec![]); + /// ``` #[inline] #[unstable = "waiting for iterator conventions"] pub fn into_iter(self) -> Item<T> { @@ -531,6 +623,26 @@ impl<T, E> Result<T, E> { ///////////////////////////////////////////////////////////////////////// /// Returns `res` if the result is `Ok`, otherwise returns the `Err` value of `self`. + /// + /// # Example + /// + /// ``` + /// let x: Result<uint, &str> = Ok(2); + /// let y: Result<&str, &str> = Err("late error"); + /// assert_eq!(x.and(y), Err("late error")); + /// + /// let x: Result<uint, &str> = Err("early error"); + /// let y: Result<&str, &str> = Ok("foo"); + /// assert_eq!(x.and(y), Err("early error")); + /// + /// let x: Result<uint, &str> = Err("not a 2"); + /// let y: Result<&str, &str> = Err("late error"); + /// assert_eq!(x.and(y), Err("not a 2")); + /// + /// let x: Result<uint, &str> = Ok(2); + /// let y: Result<&str, &str> = Ok("different result type"); + /// assert_eq!(x.and(y), Ok("different result type")); + /// ``` #[inline] #[stable] pub fn and<U>(self, res: Result<U, E>) -> Result<U, E> { @@ -542,7 +654,19 @@ impl<T, E> Result<T, E> { /// Calls `op` if the result is `Ok`, otherwise returns the `Err` value of `self`. /// - /// This function can be used for control flow based on result values + /// This function can be used for control flow based on result values. + /// + /// # Example + /// + /// ``` + /// fn sq(x: uint) -> Result<uint, uint> { Ok(x * x) } + /// fn err(x: uint) -> Result<uint, uint> { Err(x) } + /// + /// assert_eq!(Ok(2).and_then(sq).and_then(sq), Ok(16)); + /// assert_eq!(Ok(2).and_then(sq).and_then(err), Err(4)); + /// assert_eq!(Ok(2).and_then(err).and_then(sq), Err(2)); + /// assert_eq!(Err(3).and_then(sq).and_then(sq), Err(3)); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn and_then<U>(self, op: |T| -> Result<U, E>) -> Result<U, E> { @@ -553,6 +677,26 @@ impl<T, E> Result<T, E> { } /// Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`. + /// + /// # Example + /// + /// ``` + /// let x: Result<uint, &str> = Ok(2); + /// let y: Result<uint, &str> = Err("late error"); + /// assert_eq!(x.or(y), Ok(2)); + /// + /// let x: Result<uint, &str> = Err("early error"); + /// let y: Result<uint, &str> = Ok(2); + /// assert_eq!(x.or(y), Ok(2)); + /// + /// let x: Result<uint, &str> = Err("not a 2"); + /// let y: Result<uint, &str> = Err("late error"); + /// assert_eq!(x.or(y), Err("late error")); + /// + /// let x: Result<uint, &str> = Ok(2); + /// let y: Result<uint, &str> = Ok(100); + /// assert_eq!(x.or(y), Ok(2)); + /// ``` #[inline] #[stable] pub fn or(self, res: Result<T, E>) -> Result<T, E> { @@ -564,7 +708,19 @@ impl<T, E> Result<T, E> { /// Calls `op` if the result is `Err`, otherwise returns the `Ok` value of `self`. /// - /// This function can be used for control flow based on result values + /// This function can be used for control flow based on result values. + /// + /// # Example + /// + /// ``` + /// fn sq(x: uint) -> Result<uint, uint> { Ok(x * x) } + /// fn err(x: uint) -> Result<uint, uint> { Err(x) } + /// + /// assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2)); + /// assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2)); + /// assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9)); + /// assert_eq!(Err(3).or_else(err).or_else(err), Err(3)); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn or_else<F>(self, op: |E| -> Result<T, F>) -> Result<T, F> { @@ -576,6 +732,17 @@ impl<T, E> Result<T, E> { /// Unwraps a result, yielding the content of an `Ok`. /// Else it returns `optb`. + /// + /// # Example + /// + /// ``` + /// let optb = 2u; + /// let x: Result<uint, &str> = Ok(9u); + /// assert_eq!(x.unwrap_or(optb), 9u); + /// + /// let x: Result<uint, &str> = Err("error"); + /// assert_eq!(x.unwrap_or(optb), optb); + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap_or(self, optb: T) -> T { @@ -587,6 +754,15 @@ impl<T, E> Result<T, E> { /// Unwraps a result, yielding the content of an `Ok`. /// If the value is an `Err` then it calls `op` with its value. + /// + /// # Example + /// + /// ``` + /// fn count(x: &str) -> uint { x.len() } + /// + /// assert_eq!(Ok(2u).unwrap_or_else(count), 2u); + /// assert_eq!(Err("foo").unwrap_or_else(count), 3u); + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap_or_else(self, op: |E| -> T) -> T { @@ -611,6 +787,18 @@ impl<T, E: Show> Result<T, E> { /// /// Fails if the value is an `Err`, with a custom failure message provided /// by the `Err`'s value. + /// + /// # Example + /// + /// ``` + /// let x: Result<uint, &str> = Ok(2u); + /// assert_eq!(x.unwrap(), 2u); + /// ``` + /// + /// ```{.should_fail} + /// let x: Result<uint, &str> = Err("emergency failure"); + /// x.unwrap(); // fails with `emergency failure` + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap(self) -> T { @@ -629,6 +817,18 @@ impl<T: Show, E> Result<T, E> { /// /// Fails if the value is an `Ok`, with a custom failure message provided /// by the `Ok`'s value. + /// + /// # Example + /// + /// ```{.should_fail} + /// let x: Result<uint, &str> = Ok(2u); + /// x.unwrap_err(); // fails with `2` + /// ``` + /// + /// ``` + /// let x: Result<uint, &str> = Err("emergency failure"); + /// assert_eq!(x.unwrap_err(), "emergency failure"); + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap_err(self) -> E { @@ -666,7 +866,7 @@ impl<T, E> Slice<T> for Result<T, E> { /// A `Result` iterator that yields either one or zero elements /// -/// The `Item` iterator is returned by the `iter`, `mut_iter` and `move_iter` +/// The `Item` iterator is returned by the `iter`, `iter_mut` and `into_iter` /// methods on `Result`. #[deriving(Clone)] #[unstable = "waiting for iterator conventions"] |