Struct GErr 

pub struct GErr<C: Config = DefaultConfig, D = NoData> { /* private fields */ }

GErr - Structured Error Type.

It’s generically configurable with id, code, data, etc.

Error location is automatically generated.

It contains stack-trace if backtrace feature is enabled.

It provides 2 type parameters C and D:

• C is for error config. It bounds with Config trait containing error id and code.
  • Id type: defining error id type.
  • id() function: defining auto-generation function for id.
  • CODE code constant: automatically set error code at construction.
  • display function: for Display trait.
• D is for error data.

GErr contains error as having these attributes:

• id: The error id. This is to identify the error. It can be autogenerated or from outside(e.g. request id).
• code: The error code. Acts as label/category/group of errors.
• message: The error message.
• sources: The sources of current error. Errors can be linked/chained from multiple errors, serial or parallel.
• tags: The error tags. Things related to the error. For easy querying.
• data: The error data. This is additional data about the error. It can be error kinds(enum), user data triggering the errors, etc.
• help: Hint about how to solve the error.
• location: Where the error happen.
• backtrace: The error stacktrace, feature-gated behind backtrace.

Note

Set aside size of error ID and Data:

• GErr<DefaultConfig, NoData> is approximately 160 bytes.
• Enabling the backtrace feature increases this to approximately 208 bytes (+48 bytes from Backtrace).

Clippy’s result_large_err lint is intentionally allowed for this crate. Users requiring a smaller error representation may box GErr in their own APIs or using provided GErrBox.

Implementations

impl<C: Config, D> GErr<C, D>

pub fn new<M>(message: M) -> Self

where M: Into<Cow<'static, str>>,

Constructs new GErr with message and auto-generated id.

pub fn from_error<E>(err: E) -> Self

where E: Error + Send + Sync + 'static,

Constructs new GErr from any error implementing trait Error

Id is auto-generated and only contains message, location and the error as source.

pub fn new_with_id<M>(id: C::Id, message: M) -> Self

where M: Into<Cow<'static, str>>,

Constructs new GErr with id and message.

This is to set error id manually.

pub fn from_error_with_id<E>(id: C::Id, err: E) -> Self

where E: Error + Send + Sync + 'static,

Constructs new GErr from any error implementing trait Error

Id is manually-set and only contains message, location and the error as source.

impl<C: Config, D> GErr<C, D>

pub fn set_id(self, id: C::Id) -> Self

Set error id.

pub fn set_code<T>(self, code: T) -> Self

where T: Into<Cow<'static, str>>,

set error code.

pub fn set_sources<I>(self, sources: I) -> Self

where I: IntoIterator<Item = Source>,

Set list of sources.

pub fn add_source<E>(self, source: E) -> Self

where E: Error + Send + Sync + 'static,

Add general error(non-gerr) into list of sources.

pub fn add_source_gerr<E>(self, gerr: E) -> Self

where E: Into<GErrSource> + Error + Send + Sync + 'static,

Add GErr as error source.

Any errors implementing Into<GErrSource> pass.

pub fn add_tag<T>(self, tag: T) -> Self

where T: Into<Cow<'static, str>>,

Add tag to GErr.

pub fn add_tags<I, T>(self, tags: I) -> Self

where I: IntoIterator<Item = T>, T: Into<Cow<'static, str>>,

Add multiple tags at once to GErr.

pub fn set_data(self, data: D) -> Self

Set error data.

pub fn set_help<H>(self, help: H) -> Self

where H: Into<Cow<'static, str>>,

Set help.

pub fn with_config<T: Config>(self) -> GErr<T, D>

Override config type and auto-generate id and code.

This will overwrite previous id and code with auto-generated ones.

pub fn with_data_type<T>(self) -> GErr<C, T>

Override Data(D) type.

pub fn with_data<T>(self, data: T) -> GErr<C, T>

Override Data(D) value and type.

This returns new GErr with different type of Data.

pub fn id(&self) -> Option<&C::Id>

Error id.

pub fn message(&self) -> &str

Error message.

pub fn code(&self) -> Option<&str>

Error code.

pub fn tags(&self) -> Option<&[Cow<'static, str>]>

Error tags.

pub fn iter_tags(&self) -> impl Iterator<Item = &str>

Iterate over tags.

pub fn data(&self) -> Option<&D>

Error data.

pub fn sources(&self) -> Option<&[Source]>

Error sources.

pub fn location(&self) -> &ErrorLocation

Error location.

pub fn help(&self) -> Option<&str>

Error help hint.

pub fn backtrace(&self) -> &Backtrace

Error stacktrace, if backtrace enabled.

pub fn result<T>(self) -> Result<T, C, D>

Returns GErr as Result<T, GErr<ID, P, D>>.

pub fn boxed(self) -> GErrBox<C, D>

Box GErr

impl<C: Config, D> GErr<C, D>

pub fn set_field<K, V>(self, key: K, value: V) -> Self

where D: Default + SetField<K, V>,

Update error data’s fields provided that the data implement Default and SetField.

SetField trait implementation is user-defined.

impl<C: Config, D> GErr<C, D>

where C::Id: Serialize + IdSource + 'static, D: Serialize + DataSource + 'static,

pub fn into_gerr_source(self) -> GErrSource

Converts GErr into GErrSource.

impl<C: Config, D> GErr<C, D>

where C::Id: Display + Serialize, D: Debug + Serialize,

pub fn report(&self) -> String

Reports error in pretty format.

pub fn report_as<R>(&self) -> String

where R: Report,

Reports error as specified format.

impl<C: Config, D> GErr<C, D>

where C::Id: Serialize, D: Serialize,

pub fn json_data(&self) -> JsonData

JSON data of GErr.

pub fn display_json_data(&self) -> DisplayJsonData

Public JSON data of GErr.

impl<C: Config, D> GErr<C, D>

where C::Id: IdSource + 'static, D: DataSource + 'static,

pub fn iter(&self) -> GErrTree<'_, C, D>

Produces iterator of GErr’s nodes(including self).

impl<C: Config, D> GErr<C, D>

where C::Id: IdSource + 'static, D: DataSource + 'static,

pub fn iter_by_code<'a, 'b>( &'a self, code: &'b str, ) -> impl Iterator<Item = GErrNode<'a, C, D>> + 'a

where 'b: 'a,

Iterate over GErr’s codes.

pub fn iter_by_tag<'a, 'b>( &'a self, tag: &'b str, ) -> impl Iterator<Item = GErrNode<'a, C, D>> + 'a

where 'b: 'a,

Iterate over GErr’s tags.

pub fn iter_id<T>(&self) -> impl Iterator<Item = GErrNode<'_, C, D>>

where T: Any,

Iterate over GErr’s id type.

pub fn iter_by_id<'a, 'b, T>( &'a self, value: &'b T, ) -> impl Iterator<Item = GErrNode<'a, C, D>>

where T: Any + PartialEq, 'b: 'a,

Iterate over GErr’s id.

pub fn iter_data<T>(&self) -> impl Iterator<Item = GErrNode<'_, C, D>>

where T: Any,

Iterate over GErr’s data’s type.

pub fn iter_by_data<'a, 'b, T>( &'a self, value: &'b T, ) -> impl Iterator<Item = GErrNode<'a, C, D>>

where T: Any + PartialEq, 'b: 'a,

Iterate over GErr’s data.

pub fn iter_source<E>(&self) -> impl Iterator<Item = GErrNode<'_, C, D>>

where E: Error + 'static,

Iterate over GErr’s sources by source’s type.

Trait Implementations

impl<C: Config, D: Debug> Debug for GErr<C, D>

where C::Id: Debug,

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

Formats the value using the given formatter.

impl<C: Config, D> Display for GErr<C, D>

where C::Id: Display, D: Debug,

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

Formats the value using the given formatter.

impl<C: Config, D> Error for GErr<C, D>

where C::Id: Debug + Display, D: Debug,

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<'a, C: Config, D> From<&'a Box<GErr<C, D>>> for GErrView<'a, C, D>

fn from(err: &'a GErrBox<C, D>) -> Self

Converts to this type from the input type.

impl<'a, C: Config, D> From<&'a GErr<C, D>> for GErrView<'a, C, D>

fn from(err: &'a GErr<C, D>) -> Self

Converts to this type from the input type.

impl<C: Config, D> From<Box<GErr<C, D>>> for GErrSource

where C::Id: Serialize + IdSource + 'static, D: Serialize + DataSource + 'static,

Available on crate feature serde only.

fn from(gerr: Box<GErr<C, D>>) -> Self

Converts to this type from the input type.

impl<T, C: Config, D> From<Box<GErr<C, D>>> for Result<T, GErrBox<C, D>>

fn from(value: GErrBox<C, D>) -> Self

Converts to this type from the input type.

impl<C: Config, D> From<GErr<C, D>> for GErrSource

where C::Id: Serialize + IdSource + 'static, D: Serialize + DataSource + 'static,

Available on crate feature serde only.

fn from(gerr: GErr<C, D>) -> Self

Converts to this type from the input type.

impl<T, C: Config, D> From<GErr<C, D>> for Result<T, GErr<C, D>>

fn from(value: GErr<C, D>) -> Self

Converts to this type from the input type.

impl<'a, C: Config, D> IntoIterator for &'a GErr<C, D>

where C::Id: IdSource + 'static, D: DataSource + 'static,

type Item = GErrNode<'a, C, D>

The type of the elements being iterated over.

type IntoIter = GErrTree<'a, C, D>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<C: Config, D> Serialize for GErr<C, D>

where C::Id: Serialize, D: Serialize, Self: Error + 'static,

Serialize into string.

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<C: Config, D> TryFrom<JsonData> for GErr<C, D>

where C::Id: for<'a> Deserialize<'a>, D: for<'a> Deserialize<'a>,

Convert JsonData into GErr<C, D>.

If id and code are empty from JsonData, C: Config will auto-generate them.

type Error = GErr

The type returned in the event of a conversion error.

fn try_from(value: JsonData) -> Result<Self, Self::Error>

Performs the conversion.