Trait rocket::request::FromFormValue
source · pub trait FromFormValue<'v>: Sized {
type Error;
// Required method
fn from_form_value(form_value: &'v RawStr) -> Result<Self, Self::Error>;
// Provided method
fn default() -> Option<Self> { ... }
}Expand description
Trait to parse a typed value from a form value.
This trait is used by Rocket’s code generation in two places:
- Fields in structs deriving
FromFormare required to implement this trait. - Types of dynamic query parameters (
?<param>) are required to implement this trait.
§FromForm Fields
When deriving the FromForm trait, Rocket uses the FromFormValue
implementation of each field’s type to validate the form input. To
illustrate, consider the following structure:
#[derive(FromForm)]
struct Person {
name: String,
age: u16
}The FromForm implementation generated by Rocket will call
String::from_form_value for the name field, and u16::from_form_value
for the age field. The Person structure can only be created from a form
if both calls return successfully.
§Dynamic Query Parameters
Types of dynamic query parameters are required to implement this trait. The
FromFormValue implementation is used to parse and validate each parameter
according to its target type:
#[get("/item?<id>&<size>")]
fn item(id: usize, size: Size) { /* ... */ }To generate values for id and size, Rocket calls
usize::from_form_value() and Size::from_form_value(), respectively.
§Validation Errors
It is sometimes desired to prevent a validation error from forwarding a
request to another route. The FromFormValue implementation for Option<T>
and Result<T, T::Error> make this possible. Their implementations always
return successfully, effectively “catching” the error.
For instance, if we wanted to know if a user entered an invalid age in the
form corresponding to the Person structure in the first example, we could
use the following structure:
struct Person<'r> {
name: String,
age: Result<u16, &'r RawStr>
}The Err value in this case is &RawStr since u16::from_form_value
returns a Result<u16, &RawStr>.
§Provided Implementations
Rocket implements FromFormValue for many standard library types. Their
behavior is documented here.
-
- Primitive types: f32, f64, isize, i8, i16, i32, i64, i128, usize, u8, u16, u32, u64, u128
IpAddrandSocketAddrtypes: IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, SocketAddrNonZero*types: NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroIsize, NonZeroU8, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU128, NonZeroUsize
A value is validated successfully if the
from_strmethod for the given type returns successfully. Otherwise, the raw form value is returned as theErrvalue. -
bool
A value is validated successfully as
trueif the the form value is"true"or"on", and as afalsevalue if the form value is"false","off", or not present. In any other case, the raw form value is returned in theErrvalue. -
This implementation always returns successfully.
The raw, undecoded string is returned directly without modification.
-
String
URL decodes the form value. If the decode is successful, the decoded string is returned. Otherwise, an
Errwith the original form value is returned. -
Option<T> where T: FromFormValue
This implementation always returns successfully.
The form value is validated by
T’sFromFormValueimplementation. If the validation succeeds, aSome(validated_value)is returned. Otherwise, aNoneis returned. -
Result<T, T::Error> where T: FromFormValue
This implementation always returns successfully.
The from value is validated by
T’sFromFormvalueimplementation. The returnedResultvalue is returned.
§Example
This trait is generally implemented to parse and validate form values. While
Rocket provides parsing and validation for many of the standard library
types such as u16 and String, you can implement FromFormValue for a
custom type to get custom validation.
Imagine you’d like to verify that some user is over some age in a form. You
might define a new type and implement FromFormValue as follows:
use rocket::request::FromFormValue;
use rocket::http::RawStr;
struct AdultAge(usize);
impl<'v> FromFormValue<'v> for AdultAge {
type Error = &'v RawStr;
fn from_form_value(form_value: &'v RawStr) -> Result<AdultAge, &'v RawStr> {
match form_value.parse::<usize>() {
Ok(age) if age >= 21 => Ok(AdultAge(age)),
_ => Err(form_value),
}
}
}The type can then be used in a FromForm struct as follows:
#[derive(FromForm)]
struct Person {
name: String,
age: AdultAge
}A form using the Person structure as its target will only parse and
validate if the age field contains a usize greater than 21.
Required Associated Types§
Required Methods§
sourcefn from_form_value(form_value: &'v RawStr) -> Result<Self, Self::Error>
fn from_form_value(form_value: &'v RawStr) -> Result<Self, Self::Error>
Parses an instance of Self from an HTTP form field value or returns an
Error if one cannot be parsed.