Struct Error 

pub struct Error {
    pub profile: Option<Profile>,
    pub metadata: Option<Metadata>,
    pub path: Vec<String>,
    pub kind: Kind,
    /* private fields */
}

An error that occured while producing data or extracting a configuration.

Constructing Errors

An Error will generally be constructed indirectly via its implementations of serde’s de::Error and ser::Error, that is, as a result of serialization or deserialization errors. When implementing Provider, however, it may be necessary to construct an Error directly.

Broadly, there are two ways to construct an Error:

• With an error message, as Error impls From<String> and From<&str>:

  use figment::Error;
  
  Error::from(format!("{} is invalid", 1));
  
  Error::from("whoops, something went wrong!");

• With a Kind, as Error impls From<Kind>:

  use figment::{error::{Error, Kind}, value::Value};
  
  let value = Value::serialize(&100).unwrap();
  if !value.as_str().is_some() {
      let kind = Kind::InvalidType(value.to_actual(), "string".into());
      let error = Error::from(kind);
  }

As always, ? can be used to automatically convert into an Error using the available From implementations:

use std::fs::File;

fn try_read() -> Result<(), figment::Error> {
    let x = File::open("/tmp/foo.boo").map_err(|e| e.to_string())?;
    Ok(())
}

Display

By default, Error uses all of the available information about the error, including the Metadata, path, and profile to display a message that resembles the following, where $ is error. for some error: Error:

$kind: `$metadata.interpolate($path)` in $($metadata.sources())*

Concretely, such an error may look like:

invalid type: found sequence, expected u16: `staging.port` in TOML file Config.toml

Iterator

An Error may contain more than one error. To process all errors, iterate over an Error:

fn with_error(error: figment::Error) {
    for error in error {
        println!("error: {}", error);
    }
}

Fields

profile: Option<Profile>

The profile that was selected when the error occured, if any.

metadata: Option<Metadata>

The metadata for the provider of the value that errored, if known.

path: Vec<String>

The path to the configuration key that errored, if known.

kind: Kind

The error kind.

Implementations

impl Error

pub fn missing(&self) -> bool

Returns true if the error’s kind is MissingField.

Example

use figment::error::{Error, Kind};

let error = Error::from(Kind::MissingField("path".into()));
assert!(error.missing());

pub fn with_path(self, path: &str) -> Self

Append the string path to the error’s path.

Example

use figment::Error;

let error = Error::from("an error message").with_path("some_path");
assert_eq!(error.path, vec!["some_path"]);

let error = Error::from("an error message").with_path("some.path");
assert_eq!(error.path, vec!["some", "path"]);

pub fn chain(self, error: Error) -> Self

Prepends self to error and returns error.

use figment::error::Error;

let e1 = Error::from("1");
let e2 = Error::from("2");
let e3 = Error::from("3");

let error = e1.chain(e2).chain(e3);
assert_eq!(error.count(), 3);

let unchained = error.into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>();
assert_eq!(unchained, vec!["3", "2", "1"]);

let e1 = Error::from("1");
let e2 = Error::from("2");
let e3 = Error::from("3");
let error = e3.chain(e2).chain(e1);
assert_eq!(error.count(), 3);

let unchained = error.into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>();
assert_eq!(unchained, vec!["1", "2", "3"]);

pub fn count(&self) -> usize

Returns the number of errors represented by self.

Example

use figment::{Figment, providers::{Format, Toml}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Base.toml", r#"
        cat = [1
    "#)?;

    jail.create_file("Release.toml", r#"
        cat = "
    "#)?;

    let figment = Figment::from(Toml::file("Base.toml"))
        .merge(Toml::file("Release.toml"));

    let error = figment.extract_inner::<String>("cat").unwrap_err();
    assert_eq!(error.count(), 2);

    Ok(())
});

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

fn custom<T: Display>(msg: T) -> Self

Raised when there is general error when deserializing a type.

fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a type different from what it was expecting.

fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a value of the right type but that is wrong for some other reason.

fn invalid_length(len: usize, exp: &dyn Expected) -> Self

Raised when deserializing a sequence or map and the input data contains too many or too few elements.

fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize enum type received a variant with an unrecognized name.

fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize struct type received a field with an unrecognized name.

fn missing_field(field: &'static str) -> Self

Raised when a Deserialize struct type expected to receive a required field with a particular name but that field was not present in the input.

fn duplicate_field(field: &'static str) -> Self

Raised when a Deserialize struct type received more than one of the same field.

impl Error for Error

fn custom<T: Display>(msg: T) -> Self

Used when a Serialize implementation encounters any error while serializing a type.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<&str> for Error

fn from(string: &str) -> Error

Converts to this type from the input type.

impl From<Kind> for Error

fn from(kind: Kind) -> Error

Converts to this type from the input type.

impl From<String> for Error

fn from(string: String) -> Error

Converts to this type from the input type.

impl IntoIterator for Error

type Item = Error

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Error

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

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 208 bytes