Struct Error

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

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:

field	type	description
name	Option<&str>	the erroring field’s name, if known
value	Option<&str>	the erroring field’s value, if known
entity	&str	string representation of the erroring Entity
msg	&str	concise 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

impl<'v> Error<'v>

pub fn custom<E>(error: E) -> Self

where 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)
}

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

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

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

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

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

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

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

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

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

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

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

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

Formats the value using the given formatter.

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

type Target = ErrorKind<'v>

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for Error<'_>

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

Formats the value using the given formatter.

impl From<Error<'_>> for Error<'_>

Available on crate feature json only.

fn from(e: Error<'_>) -> Self

Converts to this type from the input type.

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

fn from(error: Error) -> Self

Converts to this type from the input type.

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

fn from(k: T) -> Self

Converts to this type from the input type.

impl IntoOwned for Error<'_>

type Owned = Error<'static>

The owned version of the type.

fn into_owned(self) -> Self::Owned

Converts self into an owned version of itself.

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

fn eq(&self, other: &Error<'v>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'v> Serialize for Error<'v>

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

Serialize this value into the given Serde serializer.

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