[][src]Trait rocket::request::FromFormValue

pub trait FromFormValue<'v>: Sized {
    type Error;
    fn from_form_value(form_value: &'v RawStr) -> Result<Self, Self::Error>;

    fn default() -> Option<Self> { ... }
}

Trait to parse a typed value from a form value.

This trait is used by Rocket's code generation in two places:

  1. Fields in structs deriving FromForm are required to implement this trait.
  2. 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.

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.

Associated Types

type Error

The associated error which can be returned from parsing. It is a good idea to have the return type be or contain an &'v str so that the unparseable string can be examined after a bad parse.

Loading content...

Required methods

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.

Loading content...

Provided methods

fn default() -> Option<Self>

Returns a default value to be used when the form field does not exist. If this returns None, then the field is required. Otherwise, this should return Some(default_value). The default implementation simply returns None.

Loading content...

Implementations on Foreign Types

impl<'v> FromFormValue<'v> for String[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for bool[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for f32[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for f64[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for isize[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for i8[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for i16[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for i32[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for i64[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for i128[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for usize[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for u8[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for u16[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for u32[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for u64[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for u128[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for IpAddr[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for Ipv4Addr[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for Ipv6Addr[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for SocketAddrV4[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for SocketAddrV6[src]

type Error = &'v RawStr

impl<'v> FromFormValue<'v> for SocketAddr[src]

type Error = &'v RawStr

impl<'v, T: FromFormValue<'v>> FromFormValue<'v> for Option<T>[src]

type Error = !

impl<'v, T: FromFormValue<'v>> FromFormValue<'v> for Result<T, T::Error>[src]

type Error = !

Loading content...

Implementors

impl<'v> FromFormValue<'v> for &'v RawStr[src]

type Error = !

Loading content...