Struct rocket::form::Form

source ·
pub struct Form<T>(/* private fields */);
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.

Errors

A Form<T> data guard may fail, forward, or succeed.

If a request’s content-type is neither ContentType::Form nor ContentType::FormData, the guard forwards.

If the request ContentType does identify as a form but the form data does not parse as T, according to T’s FromForm implementation, the guard fails. The Failure variant contains of the Errors emitted by T’s FromForm parser. If the error is not caught by a form::Result<T> or Option<Form<T>> data guard, the status code is set to Errors::status(), and the corresponding error catcher is called.

Otherwise the guard succeeds.

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 commutative 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§

source§

impl<T> Form<T>

source

pub fn into_inner(self) -> T

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
}
source§

impl<'r, T: FromForm<'r>> Form<T>

source

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

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);
source

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

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);
source§

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

source

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

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);
source§

impl Form<()>

source

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

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§

source§

impl<T: Debug> Debug for Form<T>

source§

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

Formats the value using the given formatter. Read more
source§

impl<T> Deref for Form<T>

§

type Target = T

The resulting type after dereferencing.
source§

fn deref(&self) -> &Self::Target

Dereferences the value.
source§

impl<T> DerefMut for Form<T>

source§

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

Mutably dereferences the value.
source§

impl<T> From<T> for Form<T>

source§

fn from(val: T) -> Form<T>

Converts to this type from the input type.
source§

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

§

type Error = Errors<'r>

The associated error to be returned when the guard fails.
source§

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 Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

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

impl<T: Ord> Ord for Form<T>

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval. Read more
source§

impl<T: PartialEq> PartialEq<Form<T>> for Form<T>

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl<T: PartialOrd> PartialOrd<Form<T>> for Form<T>

source§

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

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl<T: Eq> Eq for Form<T>

source§

impl<T> StructuralEq for Form<T>

source§

impl<T> StructuralPartialEq for Form<T>

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§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<Q, K> Comparable<K> for Qwhere Q: Ord + ?Sized, K: Borrow<Q> + ?Sized,

source§

fn compare(&self, key: &K) -> Ordering

Compare self to key and return their ordering.
source§

impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
source§

impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

source§

fn equivalent(&self, key: &K) -> bool

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

impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

source§

fn equivalent(&self, key: &K) -> bool

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

impl<T> From<!> for T

source§

fn from(t: !) -> T

Converts to this type from the input type.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

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

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoCollection<T> for T

source§

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

Converts self into a collection.
source§

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

source§

impl<T> Paint for Twhere T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Clear.

Example
println!("{}", value.clear());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> Formattable for Twhere T: Deref, <T as Deref>::Target: Formattable,

source§

impl<T> Parsable for Twhere T: Deref, <T as Deref>::Target: Parsable,