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.
Related constructs
MatchWithHandlers— the plain matcher, for handlers that need only the payload.ExtractFieldAndHandle,HandleFieldValue— document the first-argument adapters its list is built from.MatchWithValueHandlers— the convenience matcher whoseMatchFirstWith…forms build this list automatically.HasExtractor,FinalizeExtract— the traits it stands on.
The ideas behind it:
- Dispatching — routing a value, with extra arguments, to per-variant handlers.
Source
providers/with_handlers/match_first_with_handlers.rs, with the borrowed forms inmatch_first_with_handlers_ref.rsandmatch_first_with_handlers_mut.rs, and the convenience aliases inproviders/matchers/match_first_with_field_handlers.rs.
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.