W3cubDocs

/Rust

Enum std::result::Result

#[must_use = "this `Result` may be an `Err` variant, which should be handled"]
pub enum Result<T, E> {
    Ok(T),
    Err(E),
}

Result is a type that represents either success (Ok) or failure (Err).

See the std::result module documentation for details.

Variants

Ok(T)

Contains the success value

Err(E)

Contains the error value

Methods

impl<T, E> Result<T, E>[src]

pub fn is_ok(&self) -> bool[src]

Returns true if the result is Ok.

Examples

Basic usage:

let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);

pub fn is_err(&self) -> bool[src]

Returns true if the result is Err.

Examples

Basic usage:

let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);

pub fn ok(self) -> Option<T>[src]

Converts from Result<T, E> to Option<T>.

Converts self into an Option<T>, consuming self, and discarding the error, if any.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);

pub fn err(self) -> Option<E>[src]

Converts from Result<T, E> to Option<E>.

Converts self into an Option<E>, consuming self, and discarding the success value, if any.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
assert_eq!(x.err(), None);

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.err(), Some("Nothing here"));

pub fn as_ref(&self) -> Result<&T, &E>[src]

Converts from &Result<T, E> to Result<&T, &E>.

Produces a new Result, containing a reference into the original, leaving the original in place.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));

pub fn as_mut(&mut self) -> Result<&mut T, &mut E>[src]

Converts from &mut Result<T, E> to Result<&mut T, &mut E>.

Examples

Basic usage:

fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);

pub fn map<U, F>(self, op: F) -> Result<U, E> where
    F: FnOnce(T) -> U, [src]

Maps a Result<T, E> to Result<U, E> by applying a function to a contained Ok value, leaving an Err value untouched.

This function can be used to compose the results of two functions.

Examples

Print the numbers on each line of a string multiplied by two.

let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{}", n),
        Err(..) => {}
    }
}

pub fn map_or_else<U, M, F>(self, fallback: F, map: M) -> U where
    F: FnOnce(E) -> U,
    M: FnOnce(T) -> U, [src]

🔬 This is a nightly-only experimental API. (result_map_or_else #53268)

Maps a Result<T, E> to U by applying a function to a contained Ok value, or a fallback function to a contained Err value.

This function can be used to unpack a successful result while handling an error.

Examples

Basic usage:

#![feature(result_map_or_else)]
let k = 21;

let x : Result<_, &str> = Ok("foo");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);

let x : Result<&str, _> = Err("bar");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);

pub fn map_err<F, O>(self, op: O) -> Result<T, F> where
    O: FnOnce(E) -> F, [src]

Maps a Result<T, E> to Result<T, F> by applying a function to a contained Err value, leaving an Ok value untouched.

This function can be used to pass through a successful result while handling an error.

Examples

Basic usage:

fn stringify(x: u32) -> String { format!("error code: {}", x) }

let x: Result<u32, u32> = Ok(2);
assert_eq!(x.map_err(stringify), Ok(2));

let x: Result<u32, u32> = Err(13);
assert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));

pub fn iter(&self) -> Iter<T>[src]

ⓘImportant traits for Iter<'a, T>
impl<'a, T> Iterator for Iter<'a, T>
    type Item = &'a T;

Returns an iterator over the possibly contained value.

The iterator yields one value if the result is Result::Ok, otherwise none.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter().next(), Some(&7));

let x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter().next(), None);

pub fn iter_mut(&mut self) -> IterMut<T>[src]

ⓘImportant traits for IterMut<'a, T>
impl<'a, T> Iterator for IterMut<'a, T>
    type Item = &'a mut T;

Returns a mutable iterator over the possibly contained value.

The iterator yields one value if the result is Result::Ok, otherwise none.

Examples

Basic usage:

let mut x: Result<u32, &str> = Ok(7);
match x.iter_mut().next() {
    Some(v) => *v = 40,
    None => {},
}
assert_eq!(x, Ok(40));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);

pub fn and<U>(self, res: Result<U, E>) -> Result<U, E>[src]

Returns res if the result is Ok, otherwise returns the Err value of self.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &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<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));

pub fn and_then<U, F>(self, op: F) -> Result<U, E> where
    F: FnOnce(T) -> Result<U, E>, [src]

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.

Examples

Basic usage:

fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
fn err(x: u32) -> Result<u32, u32> { 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));

pub fn or<F>(self, res: Result<T, F>) -> Result<T, F>[src]

Returns res if the result is Err, otherwise returns the Ok value of self.

Arguments passed to or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use or_else, which is lazily evaluated.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));

pub fn or_else<F, O>(self, op: O) -> Result<T, F> where
    O: FnOnce(E) -> Result<T, F>, [src]

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.

Examples

Basic usage:

fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
fn err(x: u32) -> Result<u32, u32> { 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));

pub fn unwrap_or(self, optb: T) -> T[src]

Unwraps a result, yielding the content of an Ok. Else, it returns optb.

Arguments passed to unwrap_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use unwrap_or_else, which is lazily evaluated.

Examples

Basic usage:

let optb = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(optb), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(optb), optb);

pub fn unwrap_or_else<F>(self, op: F) -> T where
    F: FnOnce(E) -> T, [src]

Unwraps a result, yielding the content of an Ok. If the value is an Err then it calls op with its value.

Examples

Basic usage:

fn count(x: &str) -> usize { x.len() }

assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);

impl<T, E> Result<T, E> where
    E: Debug, [src]

pub fn unwrap(self) -> T[src]

Unwraps a result, yielding the content of an Ok.

Panics

Panics if the value is an Err, with a panic message provided by the Err's value.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`

pub fn expect(self, msg: &str) -> T[src]1.4.0

Unwraps a result, yielding the content of an Ok.

Panics

Panics if the value is an Err, with a panic message including the passed message, and the content of the Err.

Examples

Basic usage:

let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`

impl<T, E> Result<T, E> where
    T: Debug, [src]

pub fn unwrap_err(self) -> E[src]

Unwraps a result, yielding the content of an Err.

Panics

Panics if the value is an Ok, with a custom panic message provided by the Ok's value.

Examples

let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");

pub fn expect_err(self, msg: &str) -> E[src]1.17.0

Unwraps a result, yielding the content of an Err.

Panics

Panics if the value is an Ok, with a panic message including the passed message, and the content of the Ok.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(10);
x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`

impl<T, E> Result<T, E> where
    T: Default, [src]

pub fn unwrap_or_default(self) -> T[src]1.16.0

Returns the contained value or a default

Consumes the self argument then, if Ok, returns the contained value, otherwise if Err, returns the default value for that type.

Examples

Converts a string to an integer, turning poorly-formed strings into 0 (the default value for integers). parse converts a string to any other type that implements FromStr, returning an Err on error.

let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);

impl<T, E> Result<T, E> where
    T: Deref, [src]

pub fn deref_ok(&self) -> Result<&<T as Deref>::Target, &E>[src]

🔬 This is a nightly-only experimental API. (inner_deref #50264)newly added

Converts from &Result<T, E> to Result<&T::Target, &E>.

Leaves the original Result in-place, creating a new one with a reference to the original one, additionally coercing the Ok arm of the Result via Deref.

impl<T, E> Result<T, E> where
    E: Deref, [src]

pub fn deref_err(&self) -> Result<&T, &<E as Deref>::Target>[src]

🔬 This is a nightly-only experimental API. (inner_deref #50264)newly added

Converts from &Result<T, E> to Result<&T, &E::Target>.

Leaves the original Result in-place, creating a new one with a reference to the original one, additionally coercing the Err arm of the Result via Deref.

impl<T, E> Result<T, E> where
    E: Deref,
    T: Deref, [src]

pub fn deref(&self) -> Result<&<T as Deref>::Target, &<E as Deref>::Target>[src]

🔬 This is a nightly-only experimental API. (inner_deref #50264)newly added

Converts from &Result<T, E> to Result<&T::Target, &E::Target>.

Leaves the original Result in-place, creating a new one with a reference to the original one, additionally coercing both the Ok and Err arms of the Result via Deref.

impl<T, E> Result<Option<T>, E>[src]

pub fn transpose(self) -> Option<Result<T, E>>[src]1.33.0

Transposes a Result of an Option into an Option of a Result.

Ok(None) will be mapped to None. Ok(Some(_)) and Err(_) will be mapped to Some(Ok(_)) and Some(Err(_)).

Examples

#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);

Trait Implementations

impl<T, U, E> Sum<Result<U, E>> for Result<T, E> where
    T: Sum<U>, [src]1.16.0

fn sum<I>(iter: I) -> Result<T, E> where
    I: Iterator<Item = Result<U, E>>, [src]

Takes each element in the Iterator: if it is an Err, no further elements are taken, and the Err is returned. Should no Err occur, the sum of all elements is returned.

Examples

This sums up every integer in a vector, rejecting the sum if a negative element is encountered:

let v = vec![1, 2];
let res: Result<i32, &'static str> = v.iter().map(|&x: &i32|
    if x < 0 { Err("Negative element found") }
    else { Ok(x) }
).sum();
assert_eq!(res, Ok(3));

impl<T, E> Copy for Result<T, E> where
    E: Copy,
    T: Copy, [src]

impl<T, E> Hash for Result<T, E> where
    E: Hash,
    T: Hash, [src]

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, [src]1.3.0

Feeds a slice of this type into the given [Hasher]. Read more

impl<T, E> Clone for Result<T, E> where
    E: Clone,
    T: Clone, [src]

impl<T, E> Eq for Result<T, E> where
    E: Eq,
    T: Eq, [src]

impl<T, E> Try for Result<T, E>[src]

type Ok = T

🔬 This is a nightly-only experimental API. (try_trait #42327)

The type of this value when viewed as successful.

type Error = E

🔬 This is a nightly-only experimental API. (try_trait #42327)

The type of this value when viewed as failed.

impl<T, E> PartialOrd<Result<T, E>> for Result<T, E> where
    E: PartialOrd<E>,
    T: PartialOrd<T>, [src]

impl<T, E> IntoIterator for Result<T, E>[src]

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<T>[src]

ⓘImportant traits for IntoIter<T>
impl<T> Iterator for IntoIter<T>
    type Item = T;

Returns a consuming iterator over the possibly contained value.

The iterator yields one value if the result is Result::Ok, otherwise none.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);

impl<'a, T, E> IntoIterator for &'a Result<T, E>[src]1.4.0

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

ⓘImportant traits for Iter<'a, T>
impl<'a, T> Iterator for Iter<'a, T>
    type Item = &'a T;

impl<'a, T, E> IntoIterator for &'a mut Result<T, E>[src]1.4.0

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

ⓘImportant traits for IterMut<'a, T>
impl<'a, T> Iterator for IterMut<'a, T>
    type Item = &'a mut T;

impl<T, E> Ord for Result<T, E> where
    E: Ord,
    T: Ord, [src]

fn max(self, other: Self) -> Self[src]1.21.0

Compares and returns the maximum of two values. Read more

fn min(self, other: Self) -> Self[src]1.21.0

Compares and returns the minimum of two values. Read more

fn clamp(self, min: Self, max: Self) -> Self[src]

🔬 This is a nightly-only experimental API. (clamp #44095)

Restrict a value to a certain interval. Read more

impl<T, U, E> Product<Result<U, E>> for Result<T, E> where
    T: Product<U>, [src]1.16.0

fn product<I>(iter: I) -> Result<T, E> where
    I: Iterator<Item = Result<U, E>>, [src]

Takes each element in the Iterator: if it is an Err, no further elements are taken, and the Err is returned. Should no Err occur, the product of all elements is returned.

impl<T, E> Debug for Result<T, E> where
    E: Debug,
    T: Debug, [src]

impl<T, E> PartialEq<Result<T, E>> for Result<T, E> where
    E: PartialEq<E>,
    T: PartialEq<T>, [src]

impl<A, E, V> FromIterator<Result<A, E>> for Result<V, E> where
    V: FromIterator<A>, [src]

fn from_iter<I>(iter: I) -> Result<V, E> where
    I: IntoIterator<Item = Result<A, E>>, [src]

Takes each element in the Iterator: if it is an Err, no further elements are taken, and the Err is returned. Should no Err occur, a container with the values of each Result is returned.

Here is an example which increments every integer in a vector, checking for overflow:

let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));

Here is another example that tries to subtract one from another list of integers, this time checking for underflow:

let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));

Here is a variation on the previous example, showing that no further elements are taken from iter after the first Err.

let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);

Since the third element caused an underflow, no further elements were taken, so the final value of shared is 6 (= 3 + 2 + 1), not 16.

impl<E: Debug> Termination for Result<(), E>[src]

impl<E: Debug> Termination for Result<!, E>[src]

Auto Trait Implementations

impl<T, E> UnwindSafe for Result<T, E> where
    E: UnwindSafe,
    T: UnwindSafe, 

impl<T, E> RefUnwindSafe for Result<T, E> where
    E: RefUnwindSafe,
    T: RefUnwindSafe, 

impl<T, E> Unpin for Result<T, E> where
    E: Unpin,
    T: Unpin, 

impl<T, E> Send for Result<T, E> where
    E: Send,
    T: Send, 

impl<T, E> Sync for Result<T, E> where
    E: Sync,
    T: Sync, 

Blanket Implementations

impl<T, U> TryFrom<U> for T where
    U: Into<T>, [src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<I> IntoIterator for I where
    I: Iterator, [src]

type Item = <I as Iterator>::Item

The type of the elements being iterated over.

type IntoIter = I

Which kind of iterator are we turning this into?

impl<T, U> Into<U> for T where
    U: From<T>, [src]

impl<T> From<T> for T[src]

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<T> Borrow<T> for T where
    T: ?Sized, [src]

ⓘImportant traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where
    F: Unpin + Future + ?Sized, 
    type Output = <F as Future>::Output;
impl<'_, I> Iterator for &'_ mut I where
    I: Iterator + ?Sized, 
    type Item = <I as Iterator>::Item;
impl<'_, R: Read + ?Sized> Read for &'_ mut R
impl<'_, W: Write + ?Sized> Write for &'_ mut W

impl<T> BorrowMut<T> for T where
    T: ?Sized, [src]

ⓘImportant traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where
    F: Unpin + Future + ?Sized, 
    type Output = <F as Future>::Output;
impl<'_, I> Iterator for &'_ mut I where
    I: Iterator + ?Sized, 
    type Item = <I as Iterator>::Item;
impl<'_, R: Read + ?Sized> Read for &'_ mut R
impl<'_, W: Write + ?Sized> Write for &'_ mut W

impl<T> Any for T where
    T: 'static + ?Sized, [src]

impl<T> ToOwned for T where
    T: Clone, [src]

type Owned = T

The resulting type after obtaining ownership.

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/result/enum.Result.html