Trait rocket::request::FromParam[][src]

pub trait FromParam<'a>: Sized {
    type Error: Debug;
    fn from_param(param: &'a str) -> Result<Self, Self::Error>;
}

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, &str> type for the <id> parameter as follows:

#[get("/<id>")]
fn hello(id: Result<usize, &str>) -> 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.

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;

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

    fn from_param(param: &'r str) -> Result<Self, Self::Error> {
        // We can convert `param` into a `str` since we'll check every
        // character for safety later.
        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.is_ascii_alphabetic()) {
            return Err(param);
        }

        val_str.parse()
            .map(|value| MyParam { key, 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 {
    ...
}

Associated Types

type Error: Debug[src]

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

Loading content...

Required methods

fn from_param(param: &'a str) -> Result<Self, Self::Error>[src]

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

Loading content...

Implementations on Foreign Types

impl<'a> FromParam<'a> for &'a str[src]

type Error = Infallible

impl<'a> FromParam<'a> for String[src]

type Error = &'a str

impl<'a> FromParam<'a> for i8[src]

type Error = &'a str

impl<'a> FromParam<'a> for i16[src]

type Error = &'a str

impl<'a> FromParam<'a> for i32[src]

type Error = &'a str

impl<'a> FromParam<'a> for i64[src]

type Error = &'a str

impl<'a> FromParam<'a> for i128[src]

type Error = &'a str

impl<'a> FromParam<'a> for isize[src]

type Error = &'a str

impl<'a> FromParam<'a> for u8[src]

type Error = &'a str

impl<'a> FromParam<'a> for u16[src]

type Error = &'a str

impl<'a> FromParam<'a> for u32[src]

type Error = &'a str

impl<'a> FromParam<'a> for u64[src]

type Error = &'a str

impl<'a> FromParam<'a> for u128[src]

type Error = &'a str

impl<'a> FromParam<'a> for usize[src]

type Error = &'a str

impl<'a> FromParam<'a> for f32[src]

type Error = &'a str

impl<'a> FromParam<'a> for f64[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroI8[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroI16[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroI32[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroI64[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroI128[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroIsize[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroU8[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroU16[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroU32[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroU64[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroU128[src]

type Error = &'a str

impl<'a> FromParam<'a> for NonZeroUsize[src]

type Error = &'a str

impl<'a> FromParam<'a> for bool[src]

type Error = &'a str

impl<'a> FromParam<'a> for IpAddr[src]

type Error = &'a str

impl<'a> FromParam<'a> for Ipv4Addr[src]

type Error = &'a str

impl<'a> FromParam<'a> for Ipv6Addr[src]

type Error = &'a str

impl<'a> FromParam<'a> for SocketAddrV4[src]

type Error = &'a str

impl<'a> FromParam<'a> for SocketAddrV6[src]

type Error = &'a str

impl<'a> FromParam<'a> for SocketAddr[src]

type Error = &'a str

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

type Error = Infallible

impl<'a, T: FromParam<'a>> FromParam<'a> for Option<T>[src]

type Error = Infallible

Loading content...

Implementors

Loading content...