mirror of https://github.com/rwf2/Rocket.git
Document outcome module.
This commit is contained in:
parent
2a0535e1f7
commit
81f45608a1
|
@ -1,10 +1,94 @@
|
|||
//! Success, failure, and forward handling.
|
||||
//!
|
||||
//! The `Outcome<S, E, F>` type is similar to the standard library's `Result<S,
|
||||
//! E>` type. It is an enum with three variants, each containing a value:
|
||||
//! `Success(S)`, which represents a successful outcome, `Failure(E)`, which
|
||||
//! represents a failing outcome, and `Forward(F)`, which represents neither a
|
||||
//! success or failure, but instead, indicates that processing could not be
|
||||
//! handled and should instead be _forwarded_ to whatever can handle the
|
||||
//! processing next.
|
||||
//!
|
||||
//! The `Outcome` type is the return type of many of the core Rocket traits,
|
||||
//! including [FromRequest](../request/trait.FromRequest.html),
|
||||
//! [FromData](../request/trait.FromData.html), and
|
||||
//! [Responder](../response/trait.Responder.html). It is also the return type of
|
||||
//! request handlers via the [Response](../response/type.Response.html) type
|
||||
//! alias.
|
||||
//!
|
||||
//! # Success
|
||||
//!
|
||||
//! A successful `Outcome<S, E, F>`, `Success(S)`, is returned from functions
|
||||
//! that complete successfully. The meaning of a `Success` outcome depends on
|
||||
//! the context. For instance, the `Outcome` of the `from_data` method of the
|
||||
//! `FromData` trait will be matched against the type expected by the user. For
|
||||
//! example, consider the following handler:
|
||||
//!
|
||||
//! ```rust,ignore
|
||||
//! #[post("/", data = "<my_val>")]
|
||||
//! fn hello(my_val: S) -> ... { }
|
||||
//! ```
|
||||
//!
|
||||
//! The `FromData` implementation for the type `S` returns an `Outcome` with a
|
||||
//! `Success(S)`. If `from_data` returns a `Success`, the `Success` value will
|
||||
//! be unwrapped and the value will be used as the value of `my_val`.
|
||||
//!
|
||||
//! # Failure
|
||||
//!
|
||||
//! A failure `Outcome<S, E, F>`, `Failure(E)`, is returned when a function
|
||||
//! fails with some error and no processing can or should continue as a result.
|
||||
//! The meaning of a failure depends on the context.
|
||||
//!
|
||||
//! It Rocket, a `Failure` generally means that a request is taken out of normal
|
||||
//! processing. The request is then given to the catcher corresponding to some
|
||||
//! status code. users can catch failures by requesting a type of `Result<S, E>`
|
||||
//! or `Option<S>` in request handlers. For example, if a user's handler looks
|
||||
//! like:
|
||||
//!
|
||||
//! ```rust,ignore
|
||||
//! #[post("/", data = "<my_val>")]
|
||||
//! fn hello(my_val: Result<S, E>) -> ... { }
|
||||
//! ```
|
||||
//!
|
||||
//! The `FromData` implementation for the type `S` returns an `Outcome` with a
|
||||
//! `Success(S)` and `Failure(E)`. If `from_data` returns a `Failure`, the
|
||||
//! `Failure` value will be unwrapped and the value will be used as the `Err`
|
||||
//! value of `my_val` while a `Success` will be unwrapped and used the `Ok`
|
||||
//! value.
|
||||
//!
|
||||
//! # Forward
|
||||
//!
|
||||
//! A forward `Outcome<S, E, F>`, `Forward(F)`, is returned when a function
|
||||
//! wants to indicate that the requested processing should be _forwarded_ to the
|
||||
//! next available processor. Again, the exact meaning depends on the context.
|
||||
//!
|
||||
//! In Rocket, a `Forward` generally means that a request is forwarded to the
|
||||
//! next available request handler. For example, consider the following request
|
||||
//! handler:
|
||||
//!
|
||||
//! ```rust,ignore
|
||||
//! #[post("/", data = "<my_val>")]
|
||||
//! fn hello(my_val: S) -> ... { }
|
||||
//! ```
|
||||
//!
|
||||
//! The `FromData` implementation for the type `S` returns an `Outcome` with a
|
||||
//! `Success(S)`, `Failure(E)`, and `Forward(F)`. If the `Outcome` is a
|
||||
//! `Forward`, the `hello` handler isn't called. Instead, the incoming request
|
||||
//! is forwarded, or passed on to, the next matching route, if any. Ultimately,
|
||||
//! if there are no non-forwarding routes, forwarded requests are handled by the
|
||||
//! 404 catcher. Similar to `Failure`s, users can catch `Forward`s by requesting
|
||||
//! a type of `Option<S>`. If an `Outcome` is a `Forward`, the `Option` will be
|
||||
//! `None`.
|
||||
|
||||
use std::fmt;
|
||||
|
||||
use term_painter::Color::*;
|
||||
use term_painter::Color;
|
||||
use term_painter::ToStyle;
|
||||
|
||||
/// An enum representing success (`Success`), failure (`Failure`), or
|
||||
/// forwarding (`Forward`).
|
||||
#[must_use]
|
||||
#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
|
||||
pub enum Outcome<S, E, F> {
|
||||
/// Contains the success value.
|
||||
Success(S),
|
||||
|
@ -19,7 +103,17 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// Panics if the value is not Success.
|
||||
/// Panics if the value is not `Success`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.unwrap(), 10);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn unwrap(self) -> S {
|
||||
match self {
|
||||
|
@ -29,6 +123,22 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
}
|
||||
|
||||
/// Return true if this `Outcome` is a `Success`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.is_success(), true);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.is_success(), false);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Forward(25);
|
||||
/// assert_eq!(x.is_success(), false);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn is_success(&self) -> bool {
|
||||
match *self {
|
||||
|
@ -38,6 +148,22 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
}
|
||||
|
||||
/// Return true if this `Outcome` is a `Failure`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.is_failure(), false);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.is_failure(), true);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Forward(25);
|
||||
/// assert_eq!(x.is_failure(), false);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn is_failure(&self) -> bool {
|
||||
match *self {
|
||||
|
@ -47,6 +173,22 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
}
|
||||
|
||||
/// Return true if this `Outcome` is a `Forward`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.is_forward(), false);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.is_forward(), false);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Forward(25);
|
||||
/// assert_eq!(x.is_forward(), true);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn is_forward(&self) -> bool {
|
||||
match *self {
|
||||
|
@ -59,6 +201,20 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
///
|
||||
/// Returns the `Some` of the `Success` if this is a `Success`, otherwise
|
||||
/// returns `None`. `self` is consumed, and all other values are discarded.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.succeeded(), Some(10));
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.succeeded(), None);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Forward(25);
|
||||
/// assert_eq!(x.succeeded(), None);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn succeeded(self) -> Option<S> {
|
||||
match self {
|
||||
|
@ -71,6 +227,20 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
///
|
||||
/// Returns the `Some` of the `Failure` if this is a `Failure`, otherwise
|
||||
/// returns `None`. `self` is consumed, and all other values are discarded.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.failed(), None);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.failed(), Some("Hi! I'm an error."));
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Forward(25);
|
||||
/// assert_eq!(x.failed(), None);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn failed(self) -> Option<E> {
|
||||
match self {
|
||||
|
@ -83,6 +253,20 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
///
|
||||
/// Returns the `Some` of the `Forward` if this is a `Forward`, otherwise
|
||||
/// returns `None`. `self` is consumed, and all other values are discarded.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.forwarded(), None);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.forwarded(), None);
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Forward(25);
|
||||
/// assert_eq!(x.forwarded(), Some(25));
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn forwarded(self) -> Option<F> {
|
||||
match self {
|
||||
|
@ -91,6 +275,49 @@ impl<S, E, F> Outcome<S, E, F> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Converts from `Outcome<S, E, F>` to `Outcome<&S, &E, &F>`.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// assert_eq!(x.as_ref(), Success(&10));
|
||||
///
|
||||
/// let x: Outcome<i32, &str, usize> = Failure("Hi! I'm an error.");
|
||||
/// assert_eq!(x.as_ref(), Failure(&"Hi! I'm an error."));
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn as_ref(&self) -> Outcome<&S, &E, &F> {
|
||||
match *self {
|
||||
Outcome::Success(ref val) => Outcome::Success(val),
|
||||
Outcome::Failure(ref val) => Outcome::Failure(val),
|
||||
Outcome::Forward(ref val) => Outcome::Forward(val),
|
||||
}
|
||||
}
|
||||
|
||||
/// Converts from `Outcome<S, E, F>` to `Outcome<&mut S, &mut E, &mut F>`.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use rocket::outcome::Outcome;
|
||||
/// # use rocket::outcome::Outcome::*;
|
||||
/// #
|
||||
/// let mut x: Outcome<i32, &str, usize> = Success(10);
|
||||
/// if let Success(val) = x.as_mut() {
|
||||
/// *val = 20;
|
||||
/// }
|
||||
///
|
||||
/// assert_eq!(x.unwrap(), 20);
|
||||
/// ```
|
||||
#[inline(always)]
|
||||
pub fn as_mut(&mut self) -> Outcome<&mut S, &mut E, &mut F> {
|
||||
match *self {
|
||||
Outcome::Success(ref mut val) => Outcome::Success(val),
|
||||
Outcome::Failure(ref mut val) => Outcome::Failure(val),
|
||||
Outcome::Forward(ref mut val) => Outcome::Forward(val),
|
||||
}
|
||||
}
|
||||
|
||||
#[inline(always)]
|
||||
fn formatting(&self) -> (Color, &'static str) {
|
||||
match *self {
|
||||
|
|
Loading…
Reference in New Issue