DisplayError
Raise or wrap any Display source by formatting it into a String and forwarding to the context's own
string handling.
Overview
Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and
DisplayError implements both error components by redirecting through a string. Rather than
producing the abstract error directly, it formats the source error or the detail with the Display
trait through to_string() into a String, then forwards to the
context's own CanRaiseError<String> or
CanWrapError<String>, where the context is the type the implementation runs against. It does not
know the context's error type: it turns a Display value into a String and hands it off, leaving
the final step to whatever provider the context wires for the String key. Like every CGP provider,
DisplayError carries no runtime value.
It is the Display counterpart of DebugError: it carries the source's user-facing
message rather than its debug representation.
Usage
Import the provider from cgp::extra::error and the wiring keys from cgp::core::error; none of them
is in the prelude. DisplayError allocates a String, so it lives behind an alloc feature that is
off by default: enable features = ["alloc"] on the cgp dependency. It takes no type parameter
and is wired to ErrorRaiserComponent, ErrorWrapperComponent, or both, usually per source type
with the open statement:
use core::num::ParseIntError;
use cgp::core::error::ErrorRaiserComponent;
use cgp::extra::error::{DisplayError, RaiseFrom};
delegate_components! {
App {
open ErrorRaiserComponent;
@ErrorRaiserComponent.String: RaiseFrom,
@ErrorRaiserComponent.ParseIntError: DisplayError,
}
}
The String entry must be present, and must be some other provider, for DisplayError to forward to.
Here a raised ParseIntError is formatted and handed to the String entry, which
RaiseFrom converts into the abstract error.
Examples
A provider raises a ParseIntError, and the context formats it with DisplayError into the
String it uses as its error:
use core::num::ParseIntError;
use cgp::prelude::*;
use cgp::core::error::{ErrorRaiserComponent, ErrorTypeProviderComponent};
use cgp::extra::error::{DisplayError, RaiseFrom};
#[cgp_component(PortParser)]
#[use_type(HasErrorType.Error)]
pub trait CanParsePort {
fn parse_port(&self, raw: &str) -> Result<u16, Error>;
}
#[cgp_impl(new ParsePort)]
#[uses(CanRaiseError<ParseIntError>)]
#[use_type(HasErrorType.Error)]
impl PortParser {
fn parse_port(&self, raw: &str) -> Result<u16, Error> {
raw.parse().map_err(Self::raise_error)
}
}
pub struct App;
delegate_components! {
App {
open ErrorRaiserComponent;
ErrorTypeProviderComponent: UseType<String>,
PortParserComponent: ParsePort,
@ErrorRaiserComponent.String: RaiseFrom,
@ErrorRaiserComponent.ParseIntError: DisplayError,
}
}
check_components! {
App {
PortParserComponent,
}
}
pub fn demo() {
assert_eq!(App.parse_port("8080"), Ok(8080));
assert_eq!(
App.parse_port("http"),
Err("invalid digit found in string".to_owned())
);
}
App is an environmental context whose error is
String. The ParseIntError key goes to DisplayError, which produces
"invalid digit found in string" and raises it through the String key, and RaiseFrom returns
that string through the reflexive From<String> for String.
When to use it
Reach for DisplayError when a source implements Display and you want its user-facing message
carried as a string. Pair it with a provider on the String key, since it forwards rather than
finishes.
Reach for DebugError when you want the source's debug form instead, or when the
source implements Debug but not Display. Reach for RaiseFrom when a real From
impl exists, which keeps the source rather than reducing it to a string.
Under the hood
DisplayError implements ErrorRaiser for any Display source over a context that raises
String, and ErrorWrapper for any Display detail over a context that wraps String:
#[cgp_provider]
impl<Context, E> ErrorRaiser<Context, E> for DisplayError
where
Context: CanRaiseError<String>,
E: Display,
{
fn raise_error(e: E) -> Context::Error {
Context::raise_error(e.to_string())
}
}
#[cgp_provider]
impl<Context, Detail> ErrorWrapper<Context, Detail> for DisplayError
where
Context: CanWrapError<String>,
Detail: Display,
{
fn wrap_error(error: Context::Error, detail: Detail) -> Context::Error {
Context::wrap_error(error, detail.to_string())
}
}
Both bounds require the context to already handle the String case, which is the indirection that
reduces any Display source to the one case the context knows. Each impl is paired with a matching
IsProviderFor impl.
Common Mistakes
The String key itself cannot be wired to DisplayError. For a String source, DisplayError
formats it and raises the result through the context's CanRaiseError<String>, which is
DisplayError again, so the lookup never ends. A check reports the overflow:
error[E0275]: overflow evaluating the requirement `DisplayError: ErrorRaiser<App, String>`
The same holds for @ErrorWrapperComponent.String: DisplayError, which forwards to
CanWrapError<String>. Wire the String key to a provider that finishes the job, such as
RaiseFrom for raising or a wrapper written for the context's error type, and route
only the other source types to DisplayError.
Related constructs
DebugError— the same provider formatting withDebuginstead.CanRaiseErrorandCanWrapError— the components it supplies, and theStringforms it forwards to.RaiseFrom— the usual provider on theStringkey that finishes the raise.delegate_components!— itsopenstatement routes the source typesDisplayErrorshould format.
The ideas behind it:
- Modular error handling — formatting providers as a redirect onto one concrete string rule.
Source
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.