Skip to main content

CanDowncastFields

Continuing a narrowing chain on a remainder.

Overview​

Context-Generic Programming (CGP) can narrow a Rust enum into a smaller one by its variant names. CanDowncast does so and, when it fails, hands back a remainder: the same value with the attempted variants ruled out in its type. You then pass that remainder to CanDowncastFields, so a value can be tried against a second target, a third, and so on.

The two traits do the same narrowing and differ in one thing: where the walk starts. CanDowncast is called on an enum and converts it to an extractor first; CanDowncastFields is called on an extractor it is already given. Since a remainder is an extractor, that is exactly the shape a chain needs.

So the pair is the construct, and this half is almost always the continuation. A chain reads as one downcast followed by one downcast_fields per additional candidate. It applies to any extractor that can yield each target variant, so it also works on a fresh to_extractor(), where it does exactly what downcast does.

Definition​

CanDowncastFields has the same signature as CanDowncast:

pub trait CanDowncastFields<Target> {
type Remainder;

fn downcast_fields(self, _tag: PhantomData<Target>) -> Result<Target, Self::Remainder>;
}

Target is the enum being narrowed to. Self here is an extractor rather than an enum, in practice the remainder a prior downcast returned, and the method takes it by value, returning Result<Target, Remainder> as downcast does. The returned Remainder is narrower again, so each call in a chain has a different, progressively smaller Self type.

Usage​

It is not in the prelude. Import it from cgp::core::field::impls, alongside CanDowncast, which it nearly always follows:

use cgp::core::field::impls::{CanDowncast, CanDowncastFields};
use core::marker::PhantomData;

Examples​

Trying a value against three candidate targets in turn:

use cgp::prelude::*;
use cgp::core::field::impls::{CanDowncast, CanDowncastFields};
use cgp::core::field::traits::FinalizeExtractResult;

#[derive(Debug, Eq, PartialEq, CgpData)]
pub enum FooBarBaz {
Foo(u64),
Bar(String),
Baz(bool),
}

#[derive(Debug, Eq, PartialEq, CgpData)]
pub enum JustFoo {
Foo(u64),
}

#[derive(Debug, Eq, PartialEq, CgpData)]
pub enum JustBar {
Bar(String),
}

#[derive(Debug, Eq, PartialEq, CgpData)]
pub enum JustBaz {
Baz(bool),
}

pub fn classify(value: FooBarBaz) -> &'static str {
match value.downcast(PhantomData::<JustFoo>) {
Ok(_) => "foo",
// `remainder` can no longer be a `Foo`.
Err(remainder) => match remainder.downcast_fields(PhantomData::<JustBar>) {
Ok(_) => "bar",
Err(remainder) => {
// Every variant is now covered, so the last attempt cannot fail.
let JustBaz::Baz(_) = remainder
.downcast_fields(PhantomData::<JustBaz>)
.finalize_extract_result();
"baz"
}
},
}
}

pub fn demo() {
assert_eq!(classify(FooBarBaz::Foo(1)), "foo");
assert_eq!(classify(FooBarBaz::Bar("hi".to_owned())), "bar");
assert_eq!(classify(FooBarBaz::Baz(true)), "baz");
}

The first call starts the chain and each later one continues it on the remainder. The three candidates cover every variant of FooBarBaz, so the last remainder is uninhabited and the final step closes with finalize_extract_result instead of a match, exactly as an extraction chain does.

When to use it​

Reach for it as the continuation of a CanDowncast chain. Its Self is an extractor, and in practice that is the remainder a prior downcast returned.

  • Use one downcast and then one downcast_fields per further candidate. That is the whole pattern.
  • Prefer the extractor family when what you want is the payload of whichever variant is present rather than another enum. It narrows identically and ends with a checked, wildcard-free discharge through FinalizeExtract.
  • Prefer a match when the enum is concrete and the candidates are few. A cast chain pays off when the targets are type parameters or the chain is long.

Under the hood​

Its one impl applies to any Source the target's variant walk can extract from, and hands it straight to that walk:

impl<Source, Target, Remainder> CanDowncastFields<Target> for Source
where
Target: HasFields,
Target::Fields: FieldsExtractor<Source, Target, Remainder = Remainder>,
{
type Remainder = Remainder;

fn downcast_fields(self, _tag: PhantomData<Target>) -> Result<Target, Self::Remainder> {
Target::Fields::extract_from(self)
}
}

FieldsExtractor is the same recursion CanDowncast uses: it tries each target variant against the extractor, threading the shrunken remainder into the next attempt, with the terminal Void impl returning the whole remainder as Err. The only difference is the entry point: CanDowncast calls to_extractor on an enum to obtain the extractor, and this trait takes one it is handed.

Because the remainder type narrows at every step, a chain's types are all distinct, and the compiler knows at each point exactly which variants remain, the same narrowing a hand-written extraction chain performs. So once the candidates have covered every variant, the last remainder is uninhabited and the final Result closes with finalize_extract_result, as the example's last step does.

Common Mistakes​

It is not in the prelude. Import from cgp::core::field::impls.

It cannot be called on an enum, and downcast cannot be called on a remainder. Self here is an extractor, and downcast needs an enum to call to_extractor on. Writing the second step of the example as remainder.downcast(PhantomData::<JustBar>) fails with:

error[E0599]: the method `downcast` exists for enum `__PartialFooBarBaz<IsVoid, IsPresent, IsPresent>`, but its trait bounds were not satisfied
...
note: the trait `HasExtractor` must be implemented

Start a chain with CanDowncast and continue it with this trait.

.ok() on an intermediate step ends the chain. Discarding the remainder discards the input the next attempt needs.

A remainder carries none of the enum's attributes, so a Result holding one is neither Debug nor PartialEq.

Each step has a different Self type, so a chain cannot be written as a loop or collected into a Vec of attempts: it is unrolled by construction.

The ideas behind it:

Source​

  • cast.rs: CanDowncastFields and the FieldsExtractor recursion

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.