Skip to main content

ReturnError

Raise a source error that already is the context's abstract error, so raising is the identity.

Overview​

Under Context-Generic Programming (CGP), a context chooses the raiser for each source error, and ReturnError is the ErrorRaiser provider for the case where the source error is exactly the abstract error the context chose, where the context is the type the implementation runs against. Raising then has nothing to convert: it returns its argument untouched. A context uses it when generic code raises a value that is already of the context's own error type. Like every CGP provider, ReturnError carries no runtime value.

Usage​

Import the provider from cgp::extra::error and the wiring key ErrorRaiserComponent from cgp::core::error; neither is in the prelude. It takes no type parameter, and it type-checks only for the one source type that equals the context's Error:

use cgp::core::error::ErrorRaiserComponent;
use cgp::extra::error::ReturnError;

delegate_components! {
App {
ErrorRaiserComponent: ReturnError,
}
}

Examples​

ReturnError most often sits in a per-source table as the entry for the context's own error type, beside other raisers for the foreign types:

use core::num::ParseIntError;
use cgp::prelude::*;
use cgp::core::error::{ErrorRaiserComponent, ErrorTypeProviderComponent};
use cgp::extra::error::{DebugError, RaiseFrom, ReturnError};

#[derive(Debug, PartialEq)]
pub struct AppError {
pub message: String,
}

impl From<String> for AppError {
fn from(message: String) -> Self {
AppError { message }
}
}

#[cgp_component(PortChecker)]
#[use_type(HasErrorType.Error)]
pub trait CanCheckPort {
fn check_port(&self, raw: &str) -> Result<u16, Error>;
}

#[cgp_impl(new CheckPort)]
#[uses(CanRaiseError<AppError>, CanRaiseError<ParseIntError>)]
#[use_type(HasErrorType.{Error = AppError})]
impl PortChecker {
fn check_port(&self, raw: &str) -> Result<u16, AppError> {
let port: u16 = raw.parse().map_err(Self::raise_error)?;

if port == 0 {
return Err(Self::raise_error(AppError {
message: "port 0 is reserved".to_owned(),
}));
}

Ok(port)
}
}

pub struct App;

delegate_components! {
App {
open ErrorRaiserComponent;

ErrorTypeProviderComponent: UseType<AppError>,
PortCheckerComponent: CheckPort,

@ErrorRaiserComponent.AppError: ReturnError,
@ErrorRaiserComponent.String: RaiseFrom,
@ErrorRaiserComponent.ParseIntError: DebugError,
}
}

check_components! {
App {
PortCheckerComponent,
}
}

pub fn demo() {
assert_eq!(App.check_port("8080"), Ok(8080));
assert_eq!(
App.check_port("0"),
Err(AppError { message: "port 0 is reserved".to_owned() })
);
assert!(App.check_port("http").unwrap_err().message.contains("ParseIntError"));
}

CheckPort pins the error to AppError with #[use_type]'s equality form, so it can construct one and raise it. App is an environmental context whose table routes each source: the AppError through ReturnError, and a ParseIntError through DebugError, which formats it and forwards the resulting String to the String entry, where RaiseFrom converts it through AppError's From<String>.

When to use it​

Reach for ReturnError when generic code raises a value that is already the context's error type. The standard library's reflexive impl<T> From<T> for T means RaiseFrom would also work here; ReturnError states the intent directly and needs no From bound.

For a source the error can absorb through From, use RaiseFrom. For a printable source with no From impl, use DebugError or DisplayError.

Under the hood​

ReturnError implements ErrorRaiser<Context, E> only when the context's Error is exactly E:

#[cgp_new_provider]
impl<Context, E> ErrorRaiser<Context, E> for ReturnError
where
Context: HasErrorType<Error = E>,
{
fn raise_error(e: E) -> E {
e
}
}

The HasErrorType<Error = E> bound ties the source type to the abstract error, so raise_error returns its argument. The generated IsProviderFor impl carries the same bound.

The ideas behind it:

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.