doc: Methods for result::Result.
This commit is contained in:
Jonas Hietala
parent
9b49ad238d
commit
e53db0b5c9
@ -311,14 +311,13 @@ impl<T, E> Result<T, E> {
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ~~~
|
||||
/// use std::io::{File, Open, Write};
|
||||
/// ```
|
||||
/// let x: Result<int, &str> = Ok(-3);
|
||||
/// assert_eq!(x.is_ok(), true);
|
||||
///
|
||||
/// # 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> = Err("Some error message");
|
||||
/// assert_eq!(x.is_ok(), false);
|
||||
/// ```
|
||||
#[inline]
|
||||
#[stable]
|
||||
pub fn is_ok(&self) -> bool {
|
||||
@ -332,14 +331,13 @@ pub fn is_ok(&self) -> bool {
|
||||
///
|
||||
/// # 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 @@ pub fn is_err(&self) -> bool {
|
||||
/// 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>`.
|
||||
/// # Example
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
/// let x: Result<uint, &str> = Ok(2);
|
||||
/// assert_eq!(x.ok(), Some(2));
|
||||
///
|
||||
/// ~~~{.should_fail}
|
||||
/// use std::io::{File, IoResult};
|
||||
///
|
||||
/// 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 @@ pub fn ok(self) -> Option<T> {
|
||||
///
|
||||
/// 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 @@ pub fn err(self) -> Option<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 @@ pub fn as_ref<'r>(&'r self) -> Result<&'r T, &'r 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 @@ pub fn as_mut<'r>(&'r mut self) -> Result<&'r mut T, &'r mut 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 @@ pub fn map<U>(self, op: |T| -> U) -> Result<U,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 @@ pub fn map_err<F>(self, op: |E| -> F) -> Result<T,F> {
|
||||
/////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// 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 @@ pub fn mut_iter<'r>(&'r mut self) -> Item<&'r mut T> {
|
||||
}
|
||||
|
||||
/// 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 @@ pub fn move_iter(self) -> Item<T> {
|
||||
}
|
||||
|
||||
/// 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 @@ pub fn into_iter(self) -> Item<T> {
|
||||
/////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// 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 @@ pub fn and<U>(self, res: Result<U, E>) -> Result<U, 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 @@ pub fn and_then<U>(self, op: |T| -> Result<U, E>) -> Result<U, 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 @@ pub fn or(self, res: Result<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 @@ pub fn or_else<F>(self, op: |E| -> Result<T, F>) -> Result<T, F> {
|
||||
|
||||
/// 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 @@ pub fn unwrap_or(self, optb: T) -> T {
|
||||
|
||||
/// 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 @@ fn as_slice<'a>(&'a self) -> &'a [T] {
|
||||
|
||||
/// 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"]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user