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
IpAddrandSocketAddrtypes: IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, SocketAddrNonZero*types: NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroIsize, NonZeroU8, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU128, NonZeroUsize
A value is parsed successfully if the
from_strmethod from the given type returns successfully. Otherwise, the raw path segment is returned in theErrvalue. -
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
Errwith 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
Errwith the original path segment is returned. -
Option<T> where T: FromParam
This implementation always returns successfully.
The path segment is parsed by
T’sFromParamimplementation. If the parse succeeds, aSome(parsed_value)is returned. Otherwise, aNoneis returned. -
Result<T, T::Error> where T: FromParam
This implementation always returns successfully.
The path segment is parsed by
T’sFromParamimplementation. The returnedResultvalue 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 => (¶m[..i], ¶m[(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§
Required Methods§
sourcefn from_param(param: &'a RawStr) -> Result<Self, Self::Error>
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.