Struct rocket::form::Form[][src]

pub struct Form<T>(_);
Expand description

A data guard for FromForm types.

This type implements the FromData trait. It provides a generic means to parse arbitrary structures from incoming form data.

See the forms guide for general form support documentation.

Leniency

A Form<T> will parse successfully from an incoming form if the form contains a superset of the fields in T. Said another way, a Form<T> automatically discards extra fields without error. For instance, if an incoming form contains the fields “a”, “b”, and “c” while T only contains “a” and “c”, the form will parse as Form<T>. To parse strictly, use the Strict form guard.

Usage

This type can be used with any type that implements the FromForm trait. The trait can be automatically derived; see the FromForm documentation for more information on deriving or implementing the trait.

Because Form implements FromData, it can be used directly as a target of the data = "<param>" route parameter as long as its generic type implements the FromForm trait:

use rocket::form::Form;
use rocket::http::RawStr;

#[derive(FromForm)]
struct UserInput<'r> {
    value: &'r str
}

#[post("/submit", data = "<user_input>")]
fn submit_task(user_input: Form<UserInput<'_>>) -> String {
    format!("Your value: {}", user_input.value)
}

A type of Form<T> automatically dereferences into an &T or &mut T, though you can also transform a Form<T> into a T by calling into_inner(). Thanks to automatic dereferencing, you can access fields of T transparently through a Form<T>, as seen above with user_input.value.

Data Limits

The total amount of data accepted by the Form data guard is limited by the following limits:

Limit NameDefaultDescription
form32KiBtotal limit for url-encoded forms
data-form2MiBtotal limit for multipart forms
*N/Aeach field type has its own limits

As noted above, each form field type (a form guard) typically imposes its own limits. For example, the &str form guard imposes a data limit of string when multipart data is streamed.

URL-Encoded Forms

The form limit specifies the data limit for an entire url-encoded form data. It defaults to 32KiB. URL-encoded form data is percent-decoded, stored in-memory, and parsed into ValueFields. If the incoming data exceeds this limit, the Form data guard fails without attempting to parse fields with a 413: Payload Too Large error.

Multipart Forms

The data-form limit specifies the data limit for an entire multipart form data stream. It defaults to 2MiB. Multipart data is streamed, and form fields are processed into DataFields or ValueFields as they arrive. If the commulative data received while streaming exceeds the limit, parsing is aborted, an error is created and pushed via FromForm::push_error(), and the form is finalized.

Individual Fields

Individual fields may have data limits as well. The type of the field determines whether there is a data limit. For instance, the &str type imposes the string data limit. Consult the type’s documentation or FromFormField for details.

Changing Limits

To change data limits, set the limits.form and/or limits.data-form configuration parameters. For instance, to increase the URL-encoded forms limit to 128KiB for all environments, you might add the following to your Rocket.toml:

[global.limits]
form = 128KiB

See the Limits and config docs for more.

Implementations

impl<T> Form<T>[src]

pub fn into_inner(self) -> T[src]

Consumes self and returns the inner value.

Note that since Form implements Deref and DerefMut with target T, reading and writing an inner value can be accomplished transparently.

Example

use rocket::form::Form;

#[derive(FromForm)]
struct MyForm {
    field: String,
}

#[post("/submit", data = "<form>")]
fn submit(form: Form<MyForm>) -> String {
    // We can read or mutate a value transparently:
    let field: &str = &form.field;

    // To gain ownership, however, use `into_inner()`:
    form.into_inner().field
}

impl<'r, T: FromForm<'r>> Form<T>[src]

pub fn parse(string: &'r str) -> Result<'r, T>[src]

Leniently parses a T from a percent-decoded x-www-form-urlencoded form string. Specifically, this method implements §5.1 of the WHATWG URL Living Standard with the exception of steps 3.4 and 3.5, which are assumed to already be reflected in string, and then parses the fields as T.

Example

use rocket::form::{Form, FromForm};

#[derive(FromForm)]
struct Pet<'r> {
    name: &'r str,
    wags: bool,
}

let string = "name=Benson Wagger!&wags=true";
let pet: Pet<'_> = Form::parse(string).unwrap();
assert_eq!(pet.name, "Benson Wagger!");
assert_eq!(pet.wags, true);

pub fn parse_iter<I>(fields: I) -> Result<'r, T> where
    I: IntoIterator<Item = ValueField<'r>>, 
[src]

Leniently parses a T from the percent-decoded fields. Specifically, this method implements §5.1 of the WHATWG URL Living Standard with the exception of step 3.

Example

use rocket::form::{Form, FromForm, ValueField};

#[derive(FromForm)]
struct Pet<'r> {
    name: &'r str,
    wags: bool,
}

let fields = vec![
    ValueField::parse("name=Bob, the cat. :)"),
    ValueField::parse("wags=no"),
];

let pet: Pet<'_> = Form::parse_iter(fields).unwrap();
assert_eq!(pet.name, "Bob, the cat. :)");
assert_eq!(pet.wags, false);

impl<T: for<'a> FromForm<'a> + 'static> Form<T>[src]

pub fn parse_encoded(string: &RawStr) -> Result<'static, T>[src]

Leniently parses a T from a raw, x-www-form-urlencoded form string. Specifically, this method implements §5.1 of the WHATWG URL Living Standard. Because percent-decoding might modify the input string, the output type T must be 'static.

Example

use rocket::http::RawStr;
use rocket::form::{Form, FromForm};

#[derive(FromForm)]
struct Pet {
    name: String,
    wags: bool,
}

let string = RawStr::new("name=Benson+Wagger%21&wags=true");
let pet: Pet = Form::parse_encoded(string).unwrap();
assert_eq!(pet.name, "Benson Wagger!");
assert_eq!(pet.wags, true);

impl Form<()>[src]

pub fn values(string: &str) -> impl Iterator<Item = ValueField<'_>>[src]

Returns an iterator of fields parsed from a x-www-form-urlencoded form string. Specifically, this method implements steps 1, 2, and 3.1 - 3.3 of §5.1 of the WHATWG URL Living Standard. Fields in the returned iterator are not percent-decoded.

Example

use rocket::form::{Form, ValueField};

let string = "name=Bobby Brown&&&email=me@rocket.rs";
let mut values = Form::values(string);
assert_eq!(values.next().unwrap(), ValueField::parse("name=Bobby Brown"));
assert_eq!(values.next().unwrap(), ValueField::parse("email=me@rocket.rs"));
assert!(values.next().is_none());

Trait Implementations

impl<T: Debug> Debug for Form<T>[src]

fn fmt(&self, f: &mut Formatter<'_>) -> Result[src]

Formats the value using the given formatter. Read more

impl<T> Deref for Form<T>[src]

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target[src]

Dereferences the value.

impl<T> DerefMut for Form<T>[src]

fn deref_mut(&mut self) -> &mut Self::Target[src]

Mutably dereferences the value.

impl<T> From<T> for Form<T>[src]

fn from(val: T) -> Form<T>[src]

Performs the conversion.

impl<'r, T: FromForm<'r>> FromData<'r> for Form<T>[src]

type Error = Errors<'r>

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>(
    req: &'r Request<'life0>,
    data: Data<'r>
) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>> where
    'r: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 
[src]

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data. Read more

impl<T: Ord> Ord for Form<T>[src]

fn cmp(&self, other: &Form<T>) -> Ordering[src]

This method returns an Ordering between self and other. Read more

#[must_use]
fn max(self, other: Self) -> Self
1.21.0[src]

Compares and returns the maximum of two values. Read more

#[must_use]
fn min(self, other: Self) -> Self
1.21.0[src]

Compares and returns the minimum of two values. Read more

#[must_use]
fn clamp(self, min: Self, max: Self) -> Self
1.50.0[src]

Restrict a value to a certain interval. Read more

impl<T: PartialEq> PartialEq<Form<T>> for Form<T>[src]

fn eq(&self, other: &Form<T>) -> bool[src]

This method tests for self and other values to be equal, and is used by ==. Read more

fn ne(&self, other: &Form<T>) -> bool[src]

This method tests for !=.

impl<T: PartialOrd> PartialOrd<Form<T>> for Form<T>[src]

fn partial_cmp(&self, other: &Form<T>) -> Option<Ordering>[src]

This method returns an ordering between self and other values if one exists. Read more

#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]

This method tests less than (for self and other) and is used by the < operator. Read more

#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]

This method tests greater than (for self and other) and is used by the > operator. Read more

#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

impl<T: Eq> Eq for Form<T>[src]

impl<T> StructuralEq for Form<T>[src]

impl<T> StructuralPartialEq for Form<T>[src]

Auto Trait Implementations

impl<T> RefUnwindSafe for Form<T> where
    T: RefUnwindSafe

impl<T> Send for Form<T> where
    T: Send

impl<T> Sync for Form<T> where
    T: Sync

impl<T> Unpin for Form<T> where
    T: Unpin

impl<T> UnwindSafe for Form<T> where
    T: UnwindSafe

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<Q, K> Equivalent<K> for Q where
    K: Borrow<Q> + ?Sized,
    Q: Eq + ?Sized
[src]

pub fn equivalent(&self, key: &K) -> bool[src]

Compare self to key and return true if they are equal.

impl<T> From<!> for T[src]

pub fn from(t: !) -> T[src]

Performs the conversion.

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T

pub fn into_collection<A>(self) -> SmallVec<A> where
    A: Array<Item = T>, 

Converts self into a collection.

pub fn mapped<U, F, A>(self, f: F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>, 

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 

pub fn vzip(self) -> V