Struct rocket::form::Error

source ·
pub struct Error<'v> {
    pub name: Option<NameBuf<'v>>,
    pub value: Option<Cow<'v, str>>,
    pub kind: ErrorKind<'v>,
    pub entity: Entity,
}
Expand description

A form error, potentially tied to a specific form field.

An Error is returned by FromForm, FromFormField, and validate procedures, typically as a collection of Errors. It potentially identifies a specific field that triggered the error via Error::name and the field’s value via Error::value.

An Error can occur because of a field’s value that failed to parse or because other parts of a field or form were malformed; the Error::entity identifies the part of the form that resulted in the error.

Constructing

An Error can be constructed via Error::validation(), Error::custom(), or anything that an ErrorKind can be constructed from. See ErrorKind.

use rocket::form::Error;

fn at_most_10_not_even() -> Result<usize, Error<'static>> {
    // Using `From<PartIntError> => ErrorKind::Int`.
    let i: usize = "foo".parse()?;

    if i > 10 {
        // `From<(Option<isize>, Option<isize>)> => ErrorKind::OutOfRange`
        return Err((None, Some(10isize)).into());
    } else if i % 2 == 0 {
        return Err(Error::validation("integer cannot be even"));
    }

    Ok(i)
}

Setting Field Metadata

When implementing FromFormField, nothing has to be done for a field’s metadata to be set: the blanket FromForm implementation sets it automatically.

When constructed from an ErrorKind, the entity is set to Entity::default_for() by default. Occasionally, the error’s entity may need to be set manually. Return what would be useful to the end-consumer.

Matching Errors to Fields

To determine whether an error corresponds to a given field, use Error::is_for(). For example, to get all of the errors that correspond to the field foo.bar, you might write the following:

use rocket::form::Errors;

let errors = Errors::new();
let errors_for_foo = errors.iter().filter(|e| e.is_for("foo.bar"));

Serialization

When a value of this type is serialized, a struct or map with the following fields is emitted:

fieldtypedescription
nameOption<&str>the erroring field’s name, if known
valueOption<&str>the erroring field’s value, if known
entity&strstring representation of the erroring Entity
msg&strconcise message of the error

Fields§

§name: Option<NameBuf<'v>>

The name of the field, if it is known.

§value: Option<Cow<'v, str>>

The field’s value, if it is known.

§kind: ErrorKind<'v>

The kind of error that occurred.

§entity: Entity

The entity that caused the error.

Implementations§

source§

impl<'v> Error<'v>

source

pub fn custom<E>(error: E) -> Selfwhere E: Error + Send + 'static,

Creates a new Error with ErrorKind::Custom.

For validation errors, use Error::validation().

Example
use rocket::form::Error;

fn from_fmt(error: std::fmt::Error) -> Error<'static> {
    Error::custom(error)
}
source

pub fn validation<S: Into<Cow<'v, str>>>(msg: S) -> Self

Creates a new Error with ErrorKind::Validation and message msg.

Example
use rocket::form::error::{Error, ErrorKind, Entity};

let error = Error::validation("invalid foo: need bar");
assert!(matches!(error.kind, ErrorKind::Validation(_)));
assert_eq!(error.entity, Entity::Value);
source

pub fn with_entity(self, entity: Entity) -> Self

Consumes self and returns a new Error with the entity set to entity.

Example
use rocket::form::error::{Error, ErrorKind, Entity};

let error = Error::from(ErrorKind::Missing);
assert_eq!(error.entity, Entity::Field);

let error = error.with_entity(Entity::Key);
assert_eq!(error.entity, Entity::Key);
source

pub fn set_entity(&mut self, entity: Entity)

Sets the error’s entity to entity.

Example
use rocket::form::error::{Error, ErrorKind, Entity};

let mut error = Error::from(ErrorKind::Missing);
assert_eq!(error.entity, Entity::Field);

error.set_entity(Entity::Key);
assert_eq!(error.entity, Entity::Key);
source

pub fn with_name<N: Into<NameBuf<'v>>>(self, name: N) -> Self

Consumes self and returns a new Error with the field name set to name if it was not already set.

Example
use rocket::form::error::{Error, ErrorKind};

let error = Error::from(ErrorKind::Missing);
assert!(error.name.is_none());

let error = error.with_name("foo");
assert_eq!(error.name.as_ref().unwrap(), "foo");

let error = error.with_name("bar");
assert_eq!(error.name.as_ref().unwrap(), "foo");
source

pub fn set_name<N: Into<NameBuf<'v>>>(&mut self, name: N)

Sets the field name of self to name if it is not already set.

Example
use rocket::form::error::{Error, ErrorKind};

let mut error = Error::from(ErrorKind::Missing);
assert!(error.name.is_none());

error.set_name("foo");
assert_eq!(error.name.as_ref().unwrap(), "foo");

let error = error.with_name("bar");
assert_eq!(error.name.as_ref().unwrap(), "foo");
source

pub fn with_value(self, value: &'v str) -> Self

Consumes self and returns a new Error with the value set to value if it was not already set.

Example
use rocket::form::error::{Error, ErrorKind};

let error = Error::from(ErrorKind::Missing);
assert!(error.value.is_none());

let error = error.with_value("foo");
assert_eq!(error.value.as_ref().unwrap(), "foo");

let error = error.with_value("bar");
assert_eq!(error.value.as_ref().unwrap(), "foo");
source

pub fn set_value(&mut self, value: &'v str)

Set the field value of self to value if it is not already set.

Example
use rocket::form::error::{Error, ErrorKind};

let mut error = Error::from(ErrorKind::Missing);
assert!(error.value.is_none());

error.set_value("foo");
assert_eq!(error.value.as_ref().unwrap(), "foo");

error.set_value("bar");
assert_eq!(error.value.as_ref().unwrap(), "foo");
source

pub fn is_for<N: AsRef<Name>>(&self, name: N) -> bool

Returns true if this error applies to a field named name. This is different than simply comparing name.

Unlike Error::is_for_exactly(), this method returns true if the error’s field name is a prefix of name. This is typically what is desired as errors apply to a field and its children: a.b applies to the nested fields a.b.c, a.b.d and so on.

Returns false if self has no field name.

Example
use rocket::form::Error;

// returns `false` without a field name
let error = Error::validation("bad `foo`");
assert!(!error.is_for_exactly("a.b"));

// `a.b` is a prefix all of these field names
let error = error.with_name("a.b");
assert!(error.is_for("a.b"));
assert!(error.is_for("a[b]"));
assert!(error.is_for("a.b.c"));
assert!(error.is_for("a.b[c]"));
assert!(error.is_for("a.b.c[d]"));
assert!(error.is_for("a.b.c.d.foo"));

// ...but not of these.
assert!(!error.is_for("a.c"));
assert!(!error.is_for("a"));
source

pub fn is_for_exactly<N: AsRef<Name>>(&self, name: N) -> bool

Returns true if this error applies to exactly the field named name. Returns false if self has no field name.

Unlike Error::is_for(), this method returns true only when the error’s field name is exactly name. This is not typically what is desired.

Example
use rocket::form::Error;

// returns `false` without a field name
let error = Error::validation("bad `foo`");
assert!(!error.is_for_exactly("a.b"));

let error = error.with_name("a.b");
assert!(error.is_for_exactly("a.b"));
assert!(error.is_for_exactly("a[b]"));

// does not return `true` when the name is a prefix
assert!(!error.is_for_exactly("a.b.c"));
assert!(!error.is_for_exactly("a.b[c]"));
assert!(!error.is_for_exactly("a.b.c[d]"));
assert!(!error.is_for_exactly("a.b.c.d.foo"));

// does not return `true` when the name is different
assert!(!error.is_for("a.c"));
assert!(!error.is_for("a"));
source

pub fn status(&self) -> Status

Returns the most reasonable Status associated with this error.

For an ErrorKind::Custom, this is the variant’s Status, which defaults to Status::UnprocessableEntity. For all others, it is:

  • PayloadTooLarge if the error kind is:
    • InvalidLength with min of None
    • Multipart(FieldSizeExceeded) or Multipart(StreamSizeExceeded)
  • InternalServerError if the error kind is:
    • Unknown
  • BadRequest if the error kind is:
    • Io with an entity of Form
  • UnprocessableEntity for all other variants
Example
use rocket::form::error::{Error, ErrorKind, Entity};
use rocket::http::Status;

let error = Error::validation("bad `foo`");
assert_eq!(error.status(), Status::UnprocessableEntity);

let error = Error::from((None, Some(10u64)));
assert_eq!(error.status(), Status::PayloadTooLarge);

let error = Error::from(ErrorKind::Unknown);
assert_eq!(error.status(), Status::InternalServerError);

// default entity for `io::Error` is `Form`.
let error = Error::from(std::io::Error::last_os_error());
assert_eq!(error.status(), Status::BadRequest);

let error = error.with_entity(Entity::Value);
assert_eq!(error.status(), Status::UnprocessableEntity);

Trait Implementations§

source§

impl<'v> Debug for Error<'v>

source§

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

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

impl<'v> Deref for Error<'v>

§

type Target = ErrorKind<'v>

The resulting type after dereferencing.
source§

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

Dereferences the value.
source§

impl Display for Error<'_>

source§

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

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

impl<'a> From<Error> for Error<'a>

source§

fn from(error: Error) -> Self

Converts to this type from the input type.
source§

impl<'v, T: Into<ErrorKind<'v>>> From<T> for Error<'v>

source§

fn from(k: T) -> Self

Converts to this type from the input type.
source§

impl IntoOwned for Error<'_>

§

type Owned = Error<'static>

The owned version of the type.
source§

fn into_owned(self) -> Self::Owned

Converts self into an owned version of itself.
source§

impl<'v> PartialEq<Error<'v>> for Error<'v>

source§

fn eq(&self, other: &Error<'v>) -> 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<'v> Serialize for Error<'v>

source§

fn serialize<S: Serializer>(&self, ser: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer. Read more
source§

impl<'v> StructuralPartialEq for Error<'v>

Auto Trait Implementations§

§

impl<'v> !RefUnwindSafe for Error<'v>

§

impl<'v> Send for Error<'v>

§

impl<'v> !Sync for Error<'v>

§

impl<'v> Unpin for Error<'v>

§

impl<'v> !UnwindSafe for Error<'v>

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<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> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
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