Skip to content

Commit

Permalink
doc: Methods for result::Result.
Browse files Browse the repository at this point in the history
  • Loading branch information
@treeman
treeman committed Sep 17, 2014
1 parent 9b49ad2 commit e53db0b
Showing 1 changed file with 228 additions and 28 deletions.
256 changes: 228 additions & 28 deletions src/libcore/result.rs
View file
Expand Up @@ -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 {
Expand All @@ -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 {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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] {
Expand Down Expand Up @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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> {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand Down Expand Up @@ -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"]
Expand Down

0 comments on commit e53db0b

Please sign in to comment.