pub enum Outcome<S, M, F> {
Success(S),
Mistake(M),
Failure(F),
}
Expand description
Outcome
is a type that represents a Success
, Mistake
, or
Failure
.
See the module documentation for more details.
Example
The following example shows using Outcome to wrap Mutex<T>
to create a
spin lock with exponential backoff, that will not block and is adapted
from the C++ code in the blog post Using locks in real-time audio
processing, safely.
This is not meant to be an example of good API design, but to show how
Outcome
can be used to make retryable APIs easier to work with.
use std::sync::{Mutex, MutexGuard, PoisonError, LockResult, TryLockError};
#[cfg(target_arch = "x86_64")]
use std::arch::x86_64::_mm_pause;
#[cfg(target_arch = "x86")]
use std::arch::x86::_mm_pause;
#[cfg(not(any(target_arch = "x86_64", target_arch="x86")))]
#[inline(never)]
unsafe fn _mm_pause() { }
struct WouldBlock;
struct SpinMutex<T: ?Sized> {
inner: Mutex<T>,
}
type TryLockOutcome<'a, T> = Outcome<
MutexGuard<'a, T>,
WouldBlock,
PoisonError<MutexGuard<'a, T>>
>;
impl<T> SpinMutex<T> {
pub fn try_lock(&self) -> TryLockOutcome<T> {
match self.inner.try_lock() {
Err(TryLockError::Poisoned(f)) => Failure(f),
Err(TryLockError::WouldBlock) => Mistake(WouldBlock),
Ok(s) => Success(s),
}
}
pub fn lock(&self) -> LockResult<MutexGuard<'_, T>> {
for _ in 0..5 {
match self.try_lock() {
Success(s) => { return Ok(s); }
Mistake(_) => { continue; }
Failure(f) => { return Err(f); }
}
}
for _ in 0..10 {
match self.try_lock() {
Success(s) => { return Ok(s); }
Mistake(_) => { unsafe { _mm_pause(); } }
Failure(f) => { return Err(f); }
}
}
let mut n = 0;
loop {
for _ in 0..3000 {
match self.try_lock() {
Success(s) => { return Ok(s); }
Mistake(_) => {
for _ in 0..10 { unsafe { _mm_pause(); } }
continue;
}
Failure(f) => { return Err(f); }
}
}
std::thread::yield_now();
n += 1;
if n >= 2 { break self.inner.lock(); }
}
}
}
Variants
Success(S)
Contains the success value
Mistake(M)
Contains the mistake value
Failure(F)
Contains the failure value
Implementations
sourceimpl<S, M, F> Outcome<S, M, F>
impl<S, M, F> Outcome<S, M, F>
sourcepub fn contains<U>(&self, other: &U) -> bool where
U: PartialEq<S>,
Available on crate feature unstable
only.
pub fn contains<U>(&self, other: &U) -> bool where
U: PartialEq<S>,
unstable
only.Returns true
if the outcome is a Success
value containing the given
value.
Examples
let x: Outcome<u32, f32, &str> = Success(47);
assert_eq!(x.contains(&47), true);
let x: Outcome<u32, f32, &str> = Success(47);
assert_eq!(x.contains(&42), false);
let x: Outcome<u32, f32, &str> = Mistake(0.0f32);
assert_eq!(x.contains(&47), false);
let x: Outcome<u32, f32, &str> = Failure("Some error message");
assert_eq!(x.contains(&47), false);
sourcepub fn contains_mistake<N>(&self, other: &N) -> bool where
N: PartialEq<M>,
Available on crate feature unstable
only.
pub fn contains_mistake<N>(&self, other: &N) -> bool where
N: PartialEq<M>,
unstable
only.Returns true
if the outcome is a Mistake
value containing the given
value.
Examples
let x: Outcome<u32, &str, i32> = Success(47);
assert_eq!(x.contains_mistake(&"Some mistake message"), false);
let x: Outcome<u32, &str, i32> = Mistake("Some mistake message");
assert_eq!(x.contains_mistake(&"Some mistake message"), true);
let x: Outcome<u32, &str, i32> = Mistake("Some other mistake message");
assert_eq!(x.contains_mistake(&"Some mistake message"), false);
let x: Outcome<u32, &str, i32> = Failure(47);
assert_eq!(x.contains_mistake(&"Some error message"), false);
sourcepub fn contains_failure<G>(&self, other: &G) -> bool where
G: PartialEq<F>,
Available on crate feature unstable
only.
pub fn contains_failure<G>(&self, other: &G) -> bool where
G: PartialEq<F>,
unstable
only.Returns true
if the outcome is a Failure
value containing the given
value.
Examples
let x: Outcome<u32, i32, &str> = Success(47);
assert_eq!(x.contains_failure(&"Some error message"), false);
let x: Outcome<u32, i32, &str> = Mistake(47);
assert_eq!(x.contains_failure(&"Some error message"), false);
let x: Outcome<u32, i32, &str> = Failure("Some error message");
assert_eq!(x.contains_failure(&"Some error message"), true);
let x: Outcome<u32, u32, &str> = Failure("Some other error message");
assert_eq!(x.contains_failure(&"Some error message"), false);
sourceimpl<S, M, F> Outcome<Outcome<S, M, F>, M, F>
impl<S, M, F> Outcome<Outcome<S, M, F>, M, F>
sourcepub fn flatten(self) -> Outcome<S, M, F>
Available on crate feature unstable
only.
pub fn flatten(self) -> Outcome<S, M, F>
unstable
only.Converts from Outcome<Outcome<S, M, F>, M, F>
to Outcome<S, M, F>
Examples
let x: Outcome<Outcome<&'static str, u32, u32>, u32, u32> = Success(Success("hello"));
assert_eq!(Success("hello"), x.flatten());
let x: Outcome<Outcome<&'static str, u32, u32>, u32, u32> = Success(Mistake(47));
assert_eq!(Mistake(47), x.flatten());
let x: Outcome<Outcome<&'static str, u32, u32>, u32, u32> = Success(Failure(47));
assert_eq!(Failure(47), x.flatten());
let x: Outcome<Outcome<&'static str, u32, u32>, u32, u32> = Mistake(47);
assert_eq!(Mistake(47), x.flatten());
let x: Outcome<Outcome<&'static str, u32, u32>, u32, u32> = Failure(47);
assert_eq!(Failure(47), x.flatten());
NOTE: Flattening only removes one level of nesting at a time:
type Nested<T> = Outcome<Outcome<Outcome<T, u32, u32>, u32, u32>, u32, u32>;
let x: Nested<&'static str> = Success(Success(Success("hello")));
assert_eq!(Success(Success("hello")), x.flatten());
assert_eq!(Success("hello"), x.flatten().flatten());
sourceimpl<S, M: Into<!>, F: Into<!>> Outcome<S, M, F>
impl<S, M: Into<!>, F: Into<!>> Outcome<S, M, F>
sourcepub fn into_success(self) -> S
Available on crate feature nightly
only.
pub fn into_success(self) -> S
nightly
only.Returns the contained Success
value, but never panics.
Unlike unwrap
, this method is known to never panic on the outcome
types it is implemented for. Therefore, it can be used instead of
unwrap
as a maintainability safeguard that will fail to compile if the
mistake or failure type of the Outcome
is later changed to mistake or
failure that can actually occur.
Examples
fn only_success() -> Outcome<String, !, !> {
Success("This is fine 🐶☕🔥".into())
}
let s: String = only_success().into_success();
assert!(s.contains("This is fine"));
sourceimpl<S: Into<!>, M, F: Into<!>> Outcome<S, M, F>
impl<S: Into<!>, M, F: Into<!>> Outcome<S, M, F>
sourcepub fn into_mistake(self) -> M
Available on crate feature nightly
only.
pub fn into_mistake(self) -> M
nightly
only.Returns the contained Mistake
value, but never panics.
Unlike unwrap_mistake
, this method is known to never panic on the
outcome types it is implemented for. Therefore it can be used instead of
unwrap_mistake
as a maintainibility safeguard that will fail to compile
if the success or failure type of the Outcome
is later changed to a
success or failure that can actually occur.
Examples
fn only_mistake() -> Outcome<!, String, !> {
Mistake("Try another! 🍾🔫🤠".into())
}
let s: String = only_mistake().into_mistake();
assert!(s.contains("Try another!"));
sourceimpl<S: Into<!>, M: Into<!>, F> Outcome<S, M, F>
impl<S: Into<!>, M: Into<!>, F> Outcome<S, M, F>
sourcepub fn into_failure(self) -> F
Available on crate feature nightly
only.
pub fn into_failure(self) -> F
nightly
only.Returns the contained Failure
value, but never panics.
Unlike unwrap_failure
, this method is known to never panic on the
outcome types it is implemented for. Therefore, it can be used instead of
unwrap_failure
as a maintainibility safeguard that will fail to compile
if the success or mistake type of the Outcome
is later changed to a
success or mistake that can actually occur.
fn only_failure() -> Outcome<!, !, String> {
Failure("Catarina! 👦🤚🪑👧".into())
}
let s: String = only_failure().into_failure();
assert!(s.contains("Catarina!"));
sourceimpl<S, M, F> Outcome<S, M, F>
impl<S, M, F> Outcome<S, M, F>
sourcepub fn as_ref(&self) -> Outcome<&S, &M, &F>
pub fn as_ref(&self) -> Outcome<&S, &M, &F>
Converts from &Outcome<S, M, F>
to Outcome<&S, &M, &F>
.
Produces a new Outcome
, containing a reference into the original,
leaving the original in place.
Examples
let x: Outcome<u32, f32, &str> = Success(2);
assert_eq!(x.as_ref(), Success(&2));
let x: Outcome<i32, i32, i32> = Mistake(47);
assert_eq!(x.as_ref(), Mistake(&47));
let x: Outcome<i32, i32, i32> = Failure(42);
assert_eq!(x.as_ref(), Failure(&42));
sourcepub fn as_mut(&mut self) -> Outcome<&mut S, &mut M, &mut F>
pub fn as_mut(&mut self) -> Outcome<&mut S, &mut M, &mut F>
Converts from &mut Outcome<S, M, F>
to Outcome<&mut S, &mut M, &mut F>
.
Examples
fn mutate(o: &mut Outcome<i32, i32, i32>) {
match o.as_mut() {
Success(s) => *s = 47,
Mistake(m) => *m = 19,
Failure(f) => *f = 0,
}
}
let mut x: Outcome<i32, i32, i32> = Success(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 47);
let mut x: Outcome<i32, i32, i32> = Mistake(47);
mutate(&mut x);
assert_eq!(x.unwrap_mistake(), 19);
let mut x: Outcome<i32, i32, i32> = Failure(47);
mutate(&mut x);
assert_eq!(x.unwrap_failure(), 0);
sourcepub fn acclimate(self) -> Result<Concern<S, M>, F>
pub fn acclimate(self) -> Result<Concern<S, M>, F>
Returns a Result<Concern<S, M>, F>
, which allows a user to still rely
on the ?
operator until Try
has been stabilized.
Examples
pub fn invoke() -> Result<u32, &'static str> {
let x: Outcome<u32, f32, &str> = Success(2);
let c = x.acclimate()?;
Ok(match c {
Concern::Success(s) => s,
Concern::Mistake(m) => m as u32,
})
}
sourcepub fn iter(&self) -> Iter<'_, S>ⓘNotable traits for Iter<'a, T>impl<'a, T> Iterator for Iter<'a, T> type Item = &'a T;
pub fn iter(&self) -> Iter<'_, S>ⓘNotable 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 iterators yields one value if the outcome is Success
, otherwise
none.
Examples
Basic usage:
let x: Outcome<i32, f32, &str> = Success(47);
assert_eq!(x.iter().next(), Some(&47));
let x: Outcome<i32, f32, &str> = Mistake(0.0f32);
assert_eq!(x.iter().next(), None);
let x: Outcome<i32, f32, &str> = Failure("nope!");
assert_eq!(x.iter().next(), None);
sourcepub fn iter_mut(&mut self) -> IterMut<'_, S>ⓘNotable traits for IterMut<'a, T>impl<'a, T> Iterator for IterMut<'a, T> type Item = &'a mut T;
pub fn iter_mut(&mut self) -> IterMut<'_, S>ⓘNotable traits for IterMut<'a, T>impl<'a, T> Iterator for IterMut<'a, T> type Item = &'a mut T;
sourcepub fn is_success(&self) -> bool
pub fn is_success(&self) -> bool
sourcepub fn is_mistake(&self) -> bool
pub fn is_mistake(&self) -> bool
sourcepub fn is_failure(&self) -> bool
pub fn is_failure(&self) -> bool
sourcepub fn success(self) -> Option<S>
pub fn success(self) -> Option<S>
Converts from Outcome<S, M, F>
to Option<S>
.
Converts self
into an Option<S>
, consuming self
, and discarding
the mistake or failure, if any.
Examples
let outcome: Outcome<i32, f32, &str> = Success(4);
assert_eq!(outcome.success(), Some(4));
let outcome: Outcome<i32, f32, &str> = Mistake(0.0);
assert_eq!(outcome.success(), None);
let outcome: Outcome<i32, f32, &str> = Failure("failure");
assert_eq!(outcome.success(), None);
sourcepub fn mistake(self) -> Option<M>
pub fn mistake(self) -> Option<M>
Converts from Outcome<S, M, F>
to Option<M>
.
Converts self
into an Option<M>
, consuming self
, and discarding
the success or failure, if any.
Examples
let outcome: Outcome<f32, i32, &str> = Mistake(47);
assert_eq!(outcome.mistake(), Some(47));
let outcome: Outcome<f32, i32, &str> = Success(0.0);
assert_eq!(outcome.mistake(), None);
let outcome: Outcome<f32, i32, &str> = Failure("failure");
assert_eq!(outcome.mistake(), None);
sourcepub fn failure(self) -> Option<F>
pub fn failure(self) -> Option<F>
Converts from Outcome<S, M, F>
to Option<F>
.
Converts self
into an Option<F>
, consuming self
, and discarding
the success or mistake, if any.
Examples
let outcome: Outcome<f32, (), i32> = Success(0.0);
assert_eq!(outcome.failure(), None);
let outcome: Outcome<f32, (), i32> = Mistake(());
assert_eq!(outcome.failure(), None);
let outcome: Outcome<f32, (), i32> = Failure(-1);
assert_eq!(outcome.failure(), Some(-1));
sourcepub unsafe fn unwrap_unchecked(self) -> S
pub unsafe fn unwrap_unchecked(self) -> S
Returns the contained Success
value, consuming the self
value,
without checking that the value is not a Mistake
or Failure
.
Safety
Calling this method on a Mistake
or Failure
is undefined
behavior
Examples
let x: Outcome<u32, f32, &str> = Success(47);
assert_eq!(unsafe { x.unwrap_unchecked() }, 47);
let x: Outcome<u32, f32, &str> = Mistake(0.0f32);
unsafe { x.unwrap_unchecked(); } // Undefined Behavior!
let x: Outcome<u32, f32, &str> = Failure("emergency!");
unsafe { x.unwrap_unchecked(); } // Undefined Behavior!
sourcepub unsafe fn unwrap_mistake_unchecked(self) -> M
pub unsafe fn unwrap_mistake_unchecked(self) -> M
Returns the contained Mistake
value, consuming the self
value,
without checking that the value is not a Success
or Failure
.
Safety
Calling this method on a Success
or Failure
is undefined
behavior
Examples
let x: Outcome<u32, f32, &str> = Success(47);
unsafe { x.unwrap_mistake_unchecked(); } // Undefined Behavior!
let x: Outcome<u32, i32, &str> = Mistake(47);
assert_eq!(unsafe { x.unwrap_mistake_unchecked() }, 47);
let x: Outcome<u32, f32, &str> = Failure("emergency!");
unsafe { x.unwrap_mistake_unchecked(); } // Undefined Behavior!!
sourcepub unsafe fn unwrap_failure_unchecked(self) -> F
pub unsafe fn unwrap_failure_unchecked(self) -> F
Returns the contained Failure
value, consuming the self
value
without checking that the value is not a Success
or Mistake
.
Safety
Calling this method on a Success
or Mistake
is undefined
behavior
Examples
let x: Outcome<u32, f32, &str> = Success(47);
unsafe { x.unwrap_failure_unchecked(); } // Undefined Behavior!
let x: Outcome<u32, i32, &str> = Mistake(47);
unsafe { x.unwrap_failure_unchecked() }; // Undefined Behavior!
let x: Outcome<u32, f32, &str> = Failure("emergency!");
assert_eq!(unsafe { x.unwrap_failure_unchecked() }, "emergency!");
sourcepub fn and_then<T, C>(self, callable: C) -> Outcome<T, M, F> where
C: FnOnce(S) -> Outcome<T, M, F>,
pub fn and_then<T, C>(self, callable: C) -> Outcome<T, M, F> where
C: FnOnce(S) -> Outcome<T, M, F>,
Calls op
if the result is Success
, otherwise returns the
Mistake
or Failure
value of self
.
This function can be used for control flow based on Outcome
values.
Examples
fn square(x: u32) -> Outcome<u32, u32, u32> { Success(x * x) }
fn mistake(x: u32) -> Outcome<u32, u32, u32> { Mistake(x) }
fn failure(x: u32) -> Outcome<u32, u32, u32> { Failure(0) }
assert_eq!(Success(2).and_then(square).and_then(square), Success(16));
assert_eq!(Success(2).and_then(square).and_then(failure), Failure(0));
assert_eq!(Success(2).and_then(square).and_then(mistake), Mistake(4));
assert_eq!(Failure(2).and_then(square).and_then(square), Failure(2));
sourcepub fn map_or<T, C>(self, default: T, callable: C) -> T where
C: FnOnce(S) -> T,
pub fn map_or<T, C>(self, default: T, callable: C) -> T where
C: FnOnce(S) -> T,
Returns the provided default (if Mistake
or Failure
), or applies
a function to the contained value (if Success
).
Arguments passed to map_or
are eagerly evaluated; if you are passing
the result of a function call, it is recommended to use map_or_else
,
which is lazily evaluated.
Examples
let x: Outcome<_, &str, &str> = Success("foo");
assert_eq!(x.map_or(47, |v| v.len()), 3);
let x: Outcome<&str, _, &str> = Mistake("bar");
assert_eq!(x.map_or(47, |v| v.len()), 47);
let x: Outcome<&str, &str, _> = Failure("baz");
assert_eq!(x.map_or(47, |v| v.len()), 47);
sourcepub fn map_or_else<T, D, C>(self, default: D, callable: C) -> T where
D: FnOnce(Aberration<M, F>) -> T,
C: FnOnce(S) -> T,
pub fn map_or_else<T, D, C>(self, default: D, callable: C) -> T where
D: FnOnce(Aberration<M, F>) -> T,
C: FnOnce(S) -> T,
Maps an Outcome<S, M, F>
to T
by applying a fallback function to a
contained Mistake
or Failure
value (by way of an Aberration
),
or a default function to a contained Success
value.
This function can be used to unpack a successful outcome while handling mistakes or failures.
sourcepub fn map_mistake<N, C>(self, callable: C) -> Outcome<S, N, F> where
C: FnOnce(M) -> N,
pub fn map_mistake<N, C>(self, callable: C) -> Outcome<S, N, F> where
C: FnOnce(M) -> N,
Maps an Outcome<S, M, F>
to Outcome<S, N, F>
by applying a function to
a contained Mistake
value, leaving a Success
or Failure
value
untouched.
This function can be used to pass through a successful outcome while handling a mistake.
Examples
let x: Outcome<&str, _, &str> = Mistake("foo");
assert_eq!(x.map_mistake(|v| v.len()), Mistake(3));
let x: Outcome<&str, &str, _> = Failure("bar");
assert_eq!(x.map_mistake(|v| v.len()), Failure("bar"));
let x: Outcome<_, &str, &str> = Success("baz");
assert_eq!(x.map_mistake(|v| v.len()), Success("baz"));
sourcepub fn map_failure<G, C>(self, callable: C) -> Outcome<S, M, G> where
C: FnOnce(F) -> G,
pub fn map_failure<G, C>(self, callable: C) -> Outcome<S, M, G> where
C: FnOnce(F) -> G,
sourceimpl<S: Clone, M, F> Outcome<&mut S, M, F>
impl<S: Clone, M, F> Outcome<&mut S, M, F>
sourcepub fn cloned(self) -> Outcome<S, M, F>
pub fn cloned(self) -> Outcome<S, M, F>
Maps an Outcome<&mut S, M, F>
to an Outcome<S, M, F>
by cloning the
contents of the Success
value.
Examples
let mut val = 47;
let x: Outcome<&mut i32, u32, i32> = Success(&mut val);
assert_eq!(x, Success(&mut 47));
let cloned = x.cloned();
assert_eq!(cloned, Success(47));
sourceimpl<S: Copy, M, F> Outcome<&S, M, F>
impl<S: Copy, M, F> Outcome<&S, M, F>
sourcepub fn copied(self) -> Outcome<S, M, F>
pub fn copied(self) -> Outcome<S, M, F>
Maps an Outcome<&S, M, F>
to an Outcome<S, M, F>
by copying the
contents of the Success
value.
Examples
let value = 47;
let x: Outcome<&i32, i32, i32> = Success(&value);
assert_eq!(x, Success(&47));
let copied = x.copied();
assert_eq!(copied, Success(47));
sourceimpl<S: Copy, M, F> Outcome<&mut S, M, F>
impl<S: Copy, M, F> Outcome<&mut S, M, F>
sourcepub fn copied(self) -> Outcome<S, M, F>
pub fn copied(self) -> Outcome<S, M, F>
Maps an Outcome<&mut S, M, F>
to an Outcome<S, M, F>
by copying the
contents of the Success
value.
Examples
let mut value = 47;
let x: Outcome<&mut i32, i32, i32> = Success(&mut value);
assert_eq!(x, Success(&mut 47));
let copied = x.copied();
assert_eq!(copied, Success(47));
sourceimpl<S: Deref, M, F> Outcome<S, M, F>
impl<S: Deref, M, F> Outcome<S, M, F>
sourcepub fn as_deref(&self) -> Outcome<&S::Target, &M, &F>
pub fn as_deref(&self) -> Outcome<&S::Target, &M, &F>
Converts from Outcome<S, M, F>
(or &Outcome<S, M, F>
) to Outcome<&<S as Deref>::Target, M, F>
.
Coerces the Success
variant of the original Outcome
via Deref
and returns the new Outcome
.
Examples
let x: Outcome<String, u32, u32> = Success("hello".to_string());
let y: Outcome<&str, &u32, &u32> = Success("hello");
assert_eq!(x.as_deref(), y);
sourceimpl<S: DerefMut, M, F> Outcome<S, M, F>
impl<S: DerefMut, M, F> Outcome<S, M, F>
sourcepub fn as_deref_mut(&mut self) -> Outcome<&mut S::Target, &mut M, &mut F>
pub fn as_deref_mut(&mut self) -> Outcome<&mut S::Target, &mut M, &mut F>
Converts from Outcome<S, M, F>
(or &mut Outcome<S, M, F>
) to
Outcome<&mut <S as DerefMut>::Target, &mut M, &mut F>
.
Coerces the Success
variant of the original Outcome
via
DerefMut
and returns the new Outcome
.
Examples
let mut s = "HELLO".to_string();
let mut x: Outcome<String, u32, u32> = Success("hello".to_string());
let y: Outcome<&mut str, &mut u32, &mut u32> = Success(&mut s);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);
sourceimpl<S, M: Debug, F: Debug> Outcome<S, M, F>
impl<S, M: Debug, F: Debug> Outcome<S, M, F>
sourcepub fn unwrap(self) -> S
pub fn unwrap(self) -> S
Returns the contained Success
value, consuming the self
value.
Because this function may panic, its use is generally discourged.
Instead, prefer to use pattern matching and handle the Mistake
or
Failure
case explicitly, or call unwrap_or
, unwrap_or_else
,
or unwrap_or_default
.
Panics
Panics if the value is a Mistake
or Failure
, with a panic message
provided by their value.
Examples
let x: Outcome<u32, &str, &str> = Success(2);
assert_eq!(x.unwrap(), 2);
let x: Outcome<u32, &str, &str> = Mistake("mistake");
x.unwrap(); // panics with `"mistake"`
let x: Outcome<u32, &str, &str> = Failure("emergency failure");
x.unwrap(); // panics with "emergency failure"
sourcepub fn unwrap_or(self, default: S) -> S
pub fn unwrap_or(self, default: S) -> S
Returns the Success
value or a provided default.
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
let x: Outcome<u32, &str, &str> = Success(2);
assert_eq!(x.unwrap_or(3), 2);
let x: Outcome<u32, &str, &str> = Mistake("mistaken");
assert_eq!(x.unwrap_or(3), 3);
let x: Outcome<u32, &str, &str> = Failure("emergency failure");
assert_eq!(x.unwrap_or(3), 3);
sourcepub fn unwrap_or_else(self, op: impl FnOnce(Aberration<M, F>) -> S) -> S
pub fn unwrap_or_else(self, op: impl FnOnce(Aberration<M, F>) -> S) -> S
Returns the contained Success
value or computes it from the closure.
Examples
let x: Outcome<u32, &str, &str> = Success(2);
assert_eq!(x.unwrap_or_else(|_| 3), 2);
let x: Outcome<u32, &str, &str> = Mistake("mistaken");
assert_eq!(x.unwrap_or_else(|_| 3), 3);
let x: Outcome<u32, &str, &str> = Failure("emergency failure");
assert_eq!(x.unwrap_or_else(|_| 3), 3);
sourceimpl<S: Debug, M, F: Debug> Outcome<S, M, F>
impl<S: Debug, M, F: Debug> Outcome<S, M, F>
sourcepub fn unwrap_mistake(self) -> M
pub fn unwrap_mistake(self) -> M
Returns the contained Mistake
value, consuming the self
value.
Panics
Panics if the value is either a Success
or Failure
, with a custom
panic message provided by either value.
Examples
let x: Outcome<u32, &str, &str> = Success(47);
x.unwrap_mistake(); // panics with '47'
let x: Outcome<u32, &str, f32> = Mistake("try again!");
assert_eq!(x.unwrap_mistake(), "try again!");
let x: Outcome<u32, &str, &str> = Failure("emergency failure");
x.unwrap_mistake(); // panics with 'emergency failure'
sourceimpl<S: Debug, M: Debug, F> Outcome<S, M, F>
impl<S: Debug, M: Debug, F> Outcome<S, M, F>
sourcepub fn unwrap_failure(self) -> F
pub fn unwrap_failure(self) -> F
Returns the contained Failure
value, consuming the self
value.
Panics
Panics if the value is either a Success
or Mistake
, with a custom
panic message provided by either value.
Examples
let x: Outcome<u32, &str, &str> = Success(47);
x.unwrap_failure(); // panics with 47
let x: Outcome<u32, &str, f32> = Mistake("try again!");
x.unwrap_failure(); // panics with 'try again!'
let x: Outcome<u32, f32, &str> = Failure("failure!");
assert_eq!(x.unwrap_failure(), "failure!");
sourceimpl<S: Debug, M, F> Outcome<S, M, F>
impl<S: Debug, M, F> Outcome<S, M, F>
sourcepub fn unwrap_error(self) -> Aberration<M, F>
pub fn unwrap_error(self) -> Aberration<M, F>
Returns the contained Mistake
or Failure
value wrapped in an
Aberration
, consuming the self
value.
Panics
Panics if the value is a Success
, with a custom panic message
provided by the contained value.
Examples
let x: Outcome<u32, &str, &str> = Success(47);
x.unwrap_error(); // panics with '47'
let x: Outcome<u32, &str, &str> = Failure("failure!");
let ab = x.unwrap_error();
match ab {
Aberration::Mistake(m) => assert_eq!("mistake!", m),
Aberration::Failure(f) => assert_eq!("failure!", f),
};
sourceimpl<S, M, F> Outcome<Option<S>, M, F>
impl<S, M, F> Outcome<Option<S>, M, F>
sourcepub fn transpose(self) -> Option<Outcome<S, M, F>>
pub fn transpose(self) -> Option<Outcome<S, M, F>>
Transposes an Outcome
of an Option
into an Option
of an Outcome
.
Success(None)
will be mapped toNone
.Success(Some(_))
,Mistake(_)
, andFailure(_)
will be mapped toSome(Success(_))
,Some(Mistake(_))
, andSome(Failure(_))
.
Examples
let x: Outcome<Option<u32>, &str, &str> = Success(Some(5));
let y: Option<Outcome<u32, &str, &str>> = Some(Success(5));
assert_eq!(x.transpose(), y);
Trait Implementations
sourceimpl<S, M, F, N: From<M>, G: From<F>> FromResidual<Aberration<M, F>> for Outcome<S, N, G>
Available on crate feature nightly
only.
impl<S, M, F, N: From<M>, G: From<F>> FromResidual<Aberration<M, F>> for Outcome<S, N, G>
nightly
only.sourcefn from_residual(residual: Aberration<M, F>) -> Self
fn from_residual(residual: Aberration<M, F>) -> Self
try_trait_v2
)Constructs the type from a compatible Residual
type. Read more
sourceimpl<S, M, F, G: From<F>> FromResidual<Outcome<Infallible, Infallible, F>> for Outcome<S, M, G>
Available on crate feature nightly
only.
impl<S, M, F, G: From<F>> FromResidual<Outcome<Infallible, Infallible, F>> for Outcome<S, M, G>
nightly
only.sourcefn from_residual(residual: Outcome<Infallible, Infallible, F>) -> Self
fn from_residual(residual: Outcome<Infallible, Infallible, F>) -> Self
try_trait_v2
)Constructs the type from a compatible Residual
type. Read more
sourceimpl<T, F, E: From<F>> FromResidual<Outcome<Infallible, Infallible, F>> for Result<T, E>
Available on crate feature nightly
only.
impl<T, F, E: From<F>> FromResidual<Outcome<Infallible, Infallible, F>> for Result<T, E>
nightly
only.sourcefn from_residual(residual: Outcome<Infallible, Infallible, F>) -> Self
fn from_residual(residual: Outcome<Infallible, Infallible, F>) -> Self
try_trait_v2
)Constructs the type from a compatible Residual
type. Read more
sourceimpl<S, M, E, F: From<E>> FromResidual<Result<Infallible, E>> for Outcome<S, M, F>
Available on crate feature nightly
only.
impl<S, M, E, F: From<E>> FromResidual<Result<Infallible, E>> for Outcome<S, M, F>
nightly
only.sourcefn from_residual(residual: Result<Infallible, E>) -> Self
fn from_residual(residual: Result<Infallible, E>) -> Self
try_trait_v2
)Constructs the type from a compatible Residual
type. Read more
sourceimpl<'a, S, M, F> IntoIterator for &'a Outcome<S, M, F>
impl<'a, S, M, F> IntoIterator for &'a Outcome<S, M, F>
sourceimpl<'a, S, M, F> IntoIterator for &'a mut Outcome<S, M, F>
impl<'a, S, M, F> IntoIterator for &'a mut Outcome<S, M, F>
sourceimpl<S, M, F> IntoIterator for Outcome<S, M, F>
impl<S, M, F> IntoIterator for Outcome<S, M, F>
sourceimpl<S: Ord, M: Ord, F: Ord> Ord for Outcome<S, M, F>
impl<S: Ord, M: Ord, F: Ord> Ord for Outcome<S, M, F>
sourceimpl<S: PartialEq, M: PartialEq, F: PartialEq> PartialEq<Outcome<S, M, F>> for Outcome<S, M, F>
impl<S: PartialEq, M: PartialEq, F: PartialEq> PartialEq<Outcome<S, M, F>> for Outcome<S, M, F>
sourceimpl<S: PartialOrd, M: PartialOrd, F: PartialOrd> PartialOrd<Outcome<S, M, F>> for Outcome<S, M, F>
impl<S: PartialOrd, M: PartialOrd, F: PartialOrd> PartialOrd<Outcome<S, M, F>> for Outcome<S, M, F>
sourcefn partial_cmp(&self, other: &Outcome<S, M, F>) -> Option<Ordering>
fn partial_cmp(&self, other: &Outcome<S, M, F>) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
sourceimpl<M: Debug, F: Debug> Termination for Outcome<!, M, F>
Available on crate feature nightly
only.
impl<M: Debug, F: Debug> Termination for Outcome<!, M, F>
nightly
only.sourceimpl<S, M, F> Try for Outcome<S, M, F>
Available on crate feature nightly
only.
impl<S, M, F> Try for Outcome<S, M, F>
nightly
only.type Output = Concern<S, M>
type Output = Concern<S, M>
try_trait_v2
)The type of the value produced by ?
when not short-circuiting.
type Residual = Outcome<Infallible, Infallible, F>
type Residual = Outcome<Infallible, Infallible, F>
try_trait_v2
)The type of the value passed to FromResidual::from_residual
as part of ?
when short-circuiting. Read more
sourcefn from_output(output: Self::Output) -> Self
fn from_output(output: Self::Output) -> Self
try_trait_v2
)Constructs the type from its Output
type. Read more
sourcefn branch(self) -> ControlFlow<Self::Residual, Self::Output>
fn branch(self) -> ControlFlow<Self::Residual, Self::Output>
try_trait_v2
)Used in ?
to decide whether the operator should produce a value
(because this returned ControlFlow::Continue
)
or propagate a value back to the caller
(because this returned ControlFlow::Break
). Read more
sourceimpl<S, M, E> WrapFailure for Outcome<S, M, E> where
E: Error + Send + Sync + 'static,
Available on crate feature report
only.
impl<S, M, E> WrapFailure for Outcome<S, M, E> where
E: Error + Send + Sync + 'static,
report
only.sourcefn wrap_failure_with<D, F>(self, message: F) -> Self::Return where
D: Display + Send + Sync + 'static,
F: FnOnce() -> D,
fn wrap_failure_with<D, F>(self, message: F) -> Self::Return where
D: Display + Send + Sync + 'static,
F: FnOnce() -> D,
Wrap the failure value with a new adhoc error that is evaluated lazily only once an error does occur. Read more
sourcefn wrap_failure<D>(self, message: D) -> Self::Return where
D: Display + Send + Sync + 'static,
fn wrap_failure<D>(self, message: D) -> Self::Return where
D: Display + Send + Sync + 'static,
Wrap the failure value with a new adhoc error.
sourceimpl<S, M, E> WrapFailure for Outcome<S, M, E> where
E: Diagnostic + Send + Sync + 'static,
Available on crate feature diagnostic
only.
impl<S, M, E> WrapFailure for Outcome<S, M, E> where
E: Diagnostic + Send + Sync + 'static,
diagnostic
only.sourcefn wrap_failure_with<D, F>(self, message: F) -> Self::Return where
D: Display + Send + Sync + 'static,
F: FnOnce() -> D,
fn wrap_failure_with<D, F>(self, message: F) -> Self::Return where
D: Display + Send + Sync + 'static,
F: FnOnce() -> D,
Wrap the failure value with a new adhoc error that is evaluated lazily only once an error does occur. Read more
sourcefn wrap_failure<D>(self, message: D) -> Self::Return where
D: Display + Send + Sync + 'static,
fn wrap_failure<D>(self, message: D) -> Self::Return where
D: Display + Send + Sync + 'static,
Wrap the failure value with a new adhoc error.
impl<S: Copy, M: Copy, F: Copy> Copy for Outcome<S, M, F>
impl<S: Eq, M: Eq, F: Eq> Eq for Outcome<S, M, F>
impl<S, M, F> StructuralEq for Outcome<S, M, F>
impl<S, M, F> StructuralPartialEq for Outcome<S, M, F>
Auto Trait Implementations
impl<S, M, F> RefUnwindSafe for Outcome<S, M, F> where
F: RefUnwindSafe,
M: RefUnwindSafe,
S: RefUnwindSafe,
impl<S, M, F> Send for Outcome<S, M, F> where
F: Send,
M: Send,
S: Send,
impl<S, M, F> Sync for Outcome<S, M, F> where
F: Sync,
M: Sync,
S: Sync,
impl<S, M, F> Unpin for Outcome<S, M, F> where
F: Unpin,
M: Unpin,
S: Unpin,
impl<S, M, F> UnwindSafe for Outcome<S, M, F> where
F: UnwindSafe,
M: UnwindSafe,
S: UnwindSafe,
Blanket Implementations
sourceimpl<T, U> AttemptFrom<U> for T where
U: Into<T>,
impl<T, U> AttemptFrom<U> for T where
U: Into<T>,
type Mistake = Infallible
type Mistake = Infallible
The retryable error type
type Failure = Infallible
type Failure = Infallible
The failure error type
sourcefn attempt_from(
value: U
) -> Outcome<T, <T as AttemptFrom<U>>::Mistake, <T as AttemptFrom<U>>::Failure>
fn attempt_from(
value: U
) -> Outcome<T, <T as AttemptFrom<U>>::Mistake, <T as AttemptFrom<U>>::Failure>
Performs the conversion
sourceimpl<T, U> AttemptInto<U> for T where
U: AttemptFrom<T>,
impl<T, U> AttemptInto<U> for T where
U: AttemptFrom<T>,
type Mistake = <U as AttemptFrom<T>>::Mistake
type Mistake = <U as AttemptFrom<T>>::Mistake
The type returned in the event of a conversion error where the caller may retry the conversion. Read more
type Failure = <U as AttemptFrom<T>>::Failure
type Failure = <U as AttemptFrom<T>>::Failure
The type returned in the event of a conversion error where the caller may not retry the conversion. Read more
sourcefn attempt_into(
self
) -> Outcome<U, <T as AttemptInto<U>>::Mistake, <T as AttemptInto<U>>::Failure>
fn attempt_into(
self
) -> Outcome<U, <T as AttemptInto<U>>::Mistake, <T as AttemptInto<U>>::Failure>
Performs the conversion.
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more