Trait FromParam

Source

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

    // Required method
    fn from_param(param: &'a str) -> 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.

§Deriving

The FromParam trait can be automatically derived for C-like enums. See FromParam derive for more information.

§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 422 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>, Result<T, T::Error>, or Either<A, B> can be used, which implement FromParam themselves.

Option<T> where T: FromParam

Always returns successfully.

If the conversion to T fails, None is returned. If the conversion succeeds, Some(value) is returned.
Result<T, T::Error> where T: FromParam

Always returns successfully.

If the conversion to T fails, Err(error) is returned. If the conversion succeeds, Ok(value) is returned.
Either<A, B> where A: FromParam and B: FromParam

Fails only when both A::from_param and B::from_param fail. If one of the two succeeds, the successful value is returned in Either::Left(A) or Either::Right(B) variant, respectively. If both fail, the error values from both calls are returned in a tuple in the Err variant.

Either<A, B> is particularly useful with a B type of &str, allowing you to retrieve the invalid path segment. Because &str’s implementation of FromParam always succeeds, the Right variant of the Either will always contain the path segment in case of failure.

For instance, consider the following route and handler:

use rocket::either::{Either, Left, Right};

#[get("/<id>")]
fn hello(id: Either<usize, &str>) -> String {
    match id {
        Left(id_num) => format!("usize: {}", id_num),
        Right(string) => format!("Not a usize: {}", string)
    }
}

In the above example, if the dynamic path segment cannot be parsed into a usize, the raw path segment is returned in the Right variant of the Either<usize, &str> value.

§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.
&str, String

This implementation always returns successfully.

Returns the percent-decoded path segment with invalid UTF-8 byte sequences replaced by � U+FFFD.
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;

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 {
    ...
}

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 str) -> 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.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait FromParamCopy item path

§Deriving

§Forwarding

§Catching Errors

§Provided Implementations

§Example

Required Associated Types§

type Error: Debug

Required Methods§

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

Dyn Compatibility§

Implementations on Foreign Types§

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

type Error = Empty

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

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

type Error = <IpAddr as FromStr>::Err

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

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

type Error = <SocketAddr as FromStr>::Err

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

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

type Error = <bool as FromStr>::Err

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

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

type Error = <f32 as FromStr>::Err

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

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

type Error = <f64 as FromStr>::Err

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

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

type Error = <i8 as FromStr>::Err

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

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

type Error = <i16 as FromStr>::Err

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

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

type Error = <i32 as FromStr>::Err

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

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

type Error = <i64 as FromStr>::Err

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

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

type Error = <i128 as FromStr>::Err

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

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

type Error = <isize as FromStr>::Err

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

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

type Error = <u8 as FromStr>::Err

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

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

type Error = <u16 as FromStr>::Err

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

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

type Error = <u32 as FromStr>::Err

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

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

type Error = <u64 as FromStr>::Err

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

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

type Error = <u128 as FromStr>::Err

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

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

type Error = <usize as FromStr>::Err

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

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

type Error = <Ipv4Addr as FromStr>::Err

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

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

type Error = <Ipv6Addr as FromStr>::Err

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

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

type Error = <SocketAddrV4 as FromStr>::Err

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

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

type Error = <SocketAddrV6 as FromStr>::Err

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

impl<'a> FromParam<'a> for PathBuf

type Error = PathError

Trait FromParam