Trait rocket::request::FromParam

source ·
pub trait FromParam<'a>: Sized {
    type Error: Debug;

    // Required method
    fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>;
}
Expand description

Trait to convert a dynamic path segment string to a concrete value.

This trait is used by Rocket’s code generation facilities to parse dynamic path segment string values into a given type. That is, when a path contains a dynamic segment <param> where param has some type T that implements FromParam, T::from_param will be called.

§Forwarding

If the conversion fails, the incoming request will be forwarded to the next matching route, if any. For instance, consider the following route and handler for the dynamic "/<id>" path:

#[get("/<id>")]
fn hello(id: usize) -> String {
    ...
}

If usize::from_param returns an Ok(usize) variant, the encapsulated value is used as the id function parameter. If not, the request is forwarded to the next matching route. Since there are no additional matching routes, this example will result in a 404 error for requests with invalid id values.

§Catching Errors

Sometimes, a forward is not desired, and instead, we simply want to know that the dynamic path segment could not be parsed into some desired type T. In these cases, types of Option<T> or Result<T, T::Error> can be used. These types implement FromParam themselves. Their implementations always return successfully, so they never forward. They can be used to determine if the FromParam call failed and to retrieve the error value from the failed from_param call.

For instance, imagine you’ve asked for an <id> as a usize. To determine when the <id> was not a valid usize and retrieve the string that failed to parse, you can use a Result<usize, &RawStr> type for the <id> parameter as follows:

#[get("/<id>")]
fn hello(id: Result<usize, &RawStr>) -> String {
    match id {
        Ok(id_num) => format!("usize: {}", id_num),
        Err(string) => format!("Not a usize: {}", string)
    }
}

§Provided Implementations

Rocket implements FromParam for several standard library types. Their behavior is documented here.

    • Primitive types: f32, f64, isize, i8, i16, i32, i64, i128, usize, u8, u16, u32, u64, u128, bool
    • IpAddr and SocketAddr types: IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, SocketAddr
    • NonZero* types: NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroIsize, NonZeroU8, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU128, NonZeroUsize

    A value is parsed successfully if the from_str method from the given type returns successfully. Otherwise, the raw path segment is returned in the Err value.

  • &RawStr

    This implementation always returns successfully.

    The path segment is passed directly with no modification.

  • String

    Percent decodes the path segment. If the decode is successful, the decoded string is returned. Otherwise, an Err with the original path segment is returned.

  • Cow

    Percent decodes the path segment, allocating only when necessary. If the decode is successful, the decoded string is returned. Otherwise, an Err with the original path segment is returned.

  • Option<T> where T: FromParam

    This implementation always returns successfully.

    The path segment is parsed by T’s FromParam implementation. If the parse succeeds, a Some(parsed_value) is returned. Otherwise, a None is returned.

  • Result<T, T::Error> where T: FromParam

    This implementation always returns successfully.

    The path segment is parsed by T’s FromParam implementation. The returned Result value is returned.

§Example

Say you want to parse a segment of the form:

[a-zA-Z]+:[0-9]+

into the following structure, where the string before the : is stored in key and the number after the colon is stored in value:

struct MyParam<'r> {
    key: &'r str,
    value: usize
}

The following implementation accomplishes this:

use rocket::request::FromParam;
use rocket::http::RawStr;

impl<'r> FromParam<'r> for MyParam<'r> {
    type Error = &'r RawStr;

    fn from_param(param: &'r RawStr) -> Result<Self, Self::Error> {
        let (key, val_str) = match param.find(':') {
            Some(i) if i > 0 => (&param[..i], &param[(i + 1)..]),
            _ => return Err(param)
        };

        if !key.chars().all(|c| (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) {
            return Err(param);
        }

        val_str.parse().map(|value| {
            MyParam {
                key: key,
                value: value
            }
        }).map_err(|_| param)
    }
}

With the implementation, the MyParam type can be used as the target of a dynamic path segment:

#[get("/<key_val>")]
fn hello(key_val: MyParam) -> String {
    ...
}

Required Associated Types§

source

type Error: Debug

The associated error to be returned if parsing/validation fails.

Required Methods§

source

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

Parses and validates an instance of Self from a path parameter string or returns an Error if parsing or validation fails.

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

source§

impl<'a> FromParam<'a> for Cow<'a, str>

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Cow<'a, str>, Self::Error>

source§

impl<'a> FromParam<'a> for IpAddr

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for SocketAddr

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for bool

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for f32

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for f64

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for i8

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for i16

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for i32

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for i64

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for i128

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for isize

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for u8

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for u16

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for u32

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for u64

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for u128

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for usize

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for String

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<String, Self::Error>

source§

impl<'a> FromParam<'a> for Ipv4Addr

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for Ipv6Addr

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for SocketAddrV4

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for SocketAddrV6

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroI8

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroI16

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroI32

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroI64

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroI128

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroIsize

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroU8

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroU16

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroU32

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroU64

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroU128

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a> FromParam<'a> for NonZeroUsize

source§

type Error = &'a RawStr

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a, T: FromParam<'a>> FromParam<'a> for Option<T>

source§

type Error = !

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

source§

impl<'a, T: FromParam<'a>> FromParam<'a> for Result<T, T::Error>

source§

type Error = !

source§

fn from_param(param: &'a RawStr) -> Result<Self, Self::Error>

Implementors§

source§

impl<'a> FromParam<'a> for &'a RawStr