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 create instance of some type from a form value; expected from field types in structs deriving FromForm.

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.

Catching Validation Errors

Sometimes you want to be informed of validation errors. When this is desired, types of Option<T> or Result<T, T::Error> can be used. These types implement FromFormValue themselves. Their implementations always return successfully, so their validation never fails. They can be used to determine if the from_form_value call failed and to retrieve the error value from the failed call.

For instance, if we wanted to know if a user entered an invalid age in the form corresponding to the Person structure above, 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.

• f32, f64, isize, i8, i16, i32, i64, usize, u8, u16, u32, u64 IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, SocketAddr

  A value is validated successfully if the from_str method for the given type returns successfully. Otherwise, the raw form value is returned as the Err value.

• bool

  A value is validated successfully as true if the the form value is "true" or "on", and as a false value if the form value is "false", "off", or not present. In any other case, the raw form value is returned in the Err value.

• &RawStr

  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 Err with the original form value is returned.

• Option<T> where T: FromFormValue

  This implementation always returns successfully.

  The form value is validated by T's FromFormValue implementation. If the validation succeeds, a Some(validated_value) is returned. Otherwise, a None is returned.

• Result<T, T::Error> where T: FromFormValue

  This implementation always returns successfully.

  The from value is validated by T's FromFormvalue implementation. The returned Result value 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.

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.

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.

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.

Implementations on Foreign Types

impl<'v> FromFormValue<'v> for String

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for bool

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<bool>

impl<'v> FromFormValue<'v> for f32

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for f64

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for isize

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for i8

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for i16

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for i32

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for i64

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for usize

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for u8

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for u16

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for u32

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for u64

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for IpAddr

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for Ipv4Addr

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for Ipv6Addr

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for SocketAddrV4

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for SocketAddrV6

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v> FromFormValue<'v> for SocketAddr

type Error = &'v RawStr

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

impl<'v, T: FromFormValue<'v>> FromFormValue<'v> for Option<T>

type Error = !

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Option<T>>

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

type Error = !

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>

Implementors

impl<'v> FromFormValue<'v> for &'v RawStr

type Error = !

fn from_form_value(v: &'v RawStr) -> Result<Self, Self::Error>

fn default() -> Option<Self>