Skip to main content

MatchFirstWithHandlers

Match an enum that arrives together with extra arguments, passing the arguments to every handler.

Overview​

MatchFirstWithHandlers<Handlers> is the matcher for an input of the form (Input, Args): the enum being matched, first, and extra arguments that every per-variant handler needs, such as a scale factor or a target buffer. Context-Generic Programming (CGP) lets a context choose the handler for each variant, and MatchFirstWithHandlers keeps those per-variant choices while the arguments ride along. It works like MatchWithHandlers on a context, the type the implementation runs against, except that Args travels with the extractor through the loop, so on a miss the next handler still receives the arguments. Like every CGP provider, it carries no runtime value; the handler list rides in PhantomData.

Usage​

Import it from cgp::extra::dispatch. It takes one type parameter, a Product! list of per-variant adapters built from the first-argument forms ExtractFirstFieldAndHandle and HandleFirstFieldValue, which carry Args alongside the payload:

use cgp::extra::dispatch::{
ExtractFirstFieldAndHandle, HandleFirstFieldValue, MatchFirstWithHandlers,
};

delegate_components! {
App {
ComputerComponent:
MatchFirstWithHandlers<Product![
ExtractFirstFieldAndHandle<Symbol!("Circle"), HandleFirstFieldValue<ScaledArea>>,
ExtractFirstFieldAndHandle<Symbol!("Rectangle"), HandleFirstFieldValue<ScaledArea>>,
]>,
}
}

Each payload handler then computes over (Circle, Args) or (Rectangle, Args). Two borrowed forms take the same list: MatchFirstWithHandlersRef<Handlers> over (&Input, Args) and MatchFirstWithHandlersMut<Handlers> over (&mut Input, Args). All three implement Computer and AsyncComputer, and nothing else.

Examples​

A Shape enum whose area is scaled by a factor passed with it:

use cgp::extra::handler::{Computer, ComputerComponent};
use cgp::prelude::*;
use cgp::extra::dispatch::{
ExtractFirstFieldAndHandle, HandleFirstFieldValue, MatchFirstWithHandlers,
};
use cgp::extra::handler::CanCompute;

pub struct Circle {
pub radius: f64,
}

pub struct Rectangle {
pub width: f64,
pub height: f64,
}

#[derive(CgpData)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}

#[cgp_new_provider]
impl<Context, Code> Computer<Context, Code, (Circle, f64)> for ScaledArea {
type Output = f64;

fn compute(
_context: &Context,
_code: PhantomData<Code>,
(circle, scale): (Circle, f64),
) -> f64 {
core::f64::consts::PI * circle.radius * circle.radius * scale * scale
}
}

#[cgp_provider]
impl<Context, Code> Computer<Context, Code, (Rectangle, f64)> for ScaledArea {
type Output = f64;

fn compute(
_context: &Context,
_code: PhantomData<Code>,
(rectangle, scale): (Rectangle, f64),
) -> f64 {
rectangle.width * rectangle.height * scale * scale
}
}

pub struct App;

delegate_components! {
App {
ComputerComponent:
MatchFirstWithHandlers<Product![
ExtractFirstFieldAndHandle<Symbol!("Circle"), HandleFirstFieldValue<ScaledArea>>,
ExtractFirstFieldAndHandle<Symbol!("Rectangle"), HandleFirstFieldValue<ScaledArea>>,
]>,
}
}

check_components! {
App {
ComputerComponent: ((), (Shape, f64)),
}
}

pub fn demo() {
let code = PhantomData::<()>;
let rectangle = Shape::Rectangle(Rectangle {
width: 3.0,
height: 4.0,
});

assert_eq!(App.compute(code, (rectangle, 2.0)), 48.0); // 12 * 2 * 2
}

The Circle arm misses and hands the extractor and the 2.0 on together, so ScaledArea receives the Rectangle payload beside its scale factor. App is an environmental context.

When to use it​

Reach for MatchFirstWithHandlers when every per-variant handler needs the same extra arguments. When the handlers need only the payload, MatchWithHandlers is simpler. When every payload goes to one provider, the convenience aliases build the list from the enum: MatchFirstWithValueHandlers<ScaledArea> answers the example above without the list, and MatchFirstWithFieldHandlers keeps each payload tagged. They come in the same three input modes as their plain counterparts, MatchWithValueHandlers and MatchWithFieldHandlers. Both forms are imported from cgp::extra::dispatch.

Under the hood​

MatchFirstWithHandlers<Handlers> carries the list in PhantomData. Its Computer impl runs the shared matcher loop over (Input::Extractor, Args), so each miss returns (Remainder, Args) and the arguments stay with the extractor, and it discharges the leftover remainder once every variant is ruled out:

pub struct MatchFirstWithHandlers<Handlers>(pub PhantomData<Handlers>);

#[cgp_provider]
impl<Context, Code, Input, Args, Output, Remainder, Handlers> Computer<Context, Code, (Input, Args)>
for MatchFirstWithHandlers<Handlers>
where
Input: HasExtractor,
DispatchMatchers<Handlers>: Computer<
Context,
Code,
(Input::Extractor, Args),
Output = Result<Output, (Remainder, Args)>,
>,
Remainder: FinalizeExtract,
{
type Output = Output;

fn compute(context: &Context, code: PhantomData<Code>, (input, args): (Input, Args)) -> Output {
let res = DispatchMatchers::compute(context, code, (input.to_extractor(), args));
match res {
Ok(output) => output,
Err((remainder, _)) => remainder.finalize_extract(),
}
}
}

The loop is the DispatchMatchers alias described on MatchWithHandlers. The AsyncComputer impl has the same bounds over AsyncComputer. The convenience aliases are UseInputDelegate tables keyed on (Input, Args), and on (&'a Input, Args) and (&'a mut Input, Args) for the borrowed forms, each mapping the input to this matcher over a list built from the enum's variants.

Common Mistakes​

The mistakes of the plain matcher apply unchanged. A list that misses a variant fails the FinalizeExtract bound, and the matcher cannot fill a TryComputer or Handler slot without a promotion; MatchWithHandlers shows both.

The ideas behind it:

  • Dispatching — routing a value, with extra arguments, to per-variant handlers.

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.