Skip to main content

ExtractField

Pulling one variant out of an extractor, or narrowing what remains.

Overview​

In Context-Generic Programming (CGP), a match on a concrete enum is checked for exhaustiveness. Code that is generic over the enum cannot write one, so it falls back on a wildcard arm and an unreachable!(), losing exactly the guarantee you wanted.

ExtractField is the operation that recovers it. Each attempt either yields the payload or hands back a remainder whose type has that variant ruled out, and the impl exists only while the requested variant is still possible, so attempting the same variant twice is a compile error rather than a guaranteed miss.

Keep going and the remainder narrows. Once every variant has been ruled out its type is uninhabited (a value of it cannot exist), and FinalizeExtract closes the chain without a wildcard or a panic path. Add a variant to the enum and the final remainder becomes inhabited again, so the code stops compiling until it is handled.

The family is the mirror of the builder: a builder tracks which fields are present, an extractor tracks which variants are still possible.

Definition​

ExtractField<Tag> takes one variant, named by a type-level tag, out of an extractor:

pub trait ExtractField<Tag> {
type Value;
type Remainder;

fn extract_field(self, _tag: PhantomData<Tag>) -> Result<Self::Value, Self::Remainder>;
}

Self is an extractor rather than the enum. Tag is the variant's name as a Symbol!, Value is that variant's payload type, and Remainder is the same extractor with this one variant ruled out. extract_field consumes the extractor and takes a PhantomData<Tag> to name the variant, returning Ok(value) when the runtime value is that variant and Err(remainder) when it is not.

Usage​

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

Self is an extractor rather than the enum, so a chain begins by obtaining one: to_extractor to consume the value, extractor_ref to borrow it, or extractor_mut to borrow it mutably. Which one you pick decides whether the payloads come out owned, shared, or mutable; the narrowing is identical in all three.

The PhantomData<Tag> argument names the variant, keyed by Symbol! of its name.

The impls come from #[derive(ExtractField)], also available through #[derive(CgpVariant)] and #[derive(CgpData)].

Examples​

The chain reads as a sequence of attempts, each handling one variant, closed by finalize_extract_result, written here in both orders:

use cgp::core::field::traits::{ExtractField, FinalizeExtractResult, HasExtractor};
use cgp::prelude::*;

#[derive(Debug, PartialEq)]
pub struct Circle {
pub radius: f64,
}

#[derive(Debug, PartialEq)]
pub struct Rectangle {
pub width: f64,
pub height: f64,
}

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

pub fn area(shape: Shape) -> f64 {
match shape.to_extractor().extract_field(PhantomData::<Symbol!("Circle")>) {
Ok(circle) => core::f64::consts::PI * circle.radius * circle.radius,
Err(remainder) => {
// `remainder` can no longer be a `Circle`.
let rect = remainder
.extract_field(PhantomData::<Symbol!("Rectangle")>)
.finalize_extract_result();
rect.width * rect.height
}
}
}

// The same chain with the extractions the other way round.
pub fn perimeter(shape: Shape) -> f64 {
match shape.to_extractor().extract_field(PhantomData::<Symbol!("Rectangle")>) {
Ok(rect) => 2.0 * (rect.width + rect.height),
Err(remainder) => {
let circle = remainder
.extract_field(PhantomData::<Symbol!("Circle")>)
.finalize_extract_result();
2.0 * core::f64::consts::PI * circle.radius
}
}
}

pub fn demo() {
assert_eq!(area(Shape::Rectangle(Rectangle { width: 3.0, height: 4.0 })), 12.0);
assert_eq!(perimeter(Shape::Rectangle(Rectangle { width: 3.0, height: 4.0 })), 14.0);
assert!(area(Shape::Circle(Circle { radius: 1.0 })) > 3.14);
}

After the second extraction both variants are ruled out, so the remainder's type is uninhabited and the finalize is accepted without a wildcard arm. The type enforces this: finalize after only the first extraction and the code does not compile. The two functions try the variants in opposite orders, which works because each step changes only its own variant's marker.

In practice you rarely write these chains. The dispatch combinators build them from a set of per-variant implementations, which is the extensible visitor pattern: a chain like the one above, generated, with one implementation per variant chosen by wiring.

When to use it​

Reach for the family when independent code handles one variant each, or when the matching code cannot name the enum. Outside those two cases a match wins on every count: shorter, clearer, already exhaustive, and it generates nothing. This is not an improvement on match; you reach for it only where match is unavailable.

  • Bound on HasExtractor + ExtractField to write a routine that deconstructs an enum it does not name.
  • Pick the accessor by ownership, preferring the weakest that works: extractor_ref for a read-only operation, extractor_mut to mutate a payload, to_extractor only when you genuinely want to consume.
  • Do not use it to test which variant a value holds. matches! or an if let answers that in a line. The family's value is in the chain and what the chain proves.
  • Reach for the dispatch combinators rather than writing the chain, since they derive it from the enum's own variant list instead of repeating it at each site, which keeps "add a variant" from breaking every call site by hand.

The construction counterpart is FromVariant, and the two are commonly wanted together because a generic pipeline usually takes a value apart and puts one back. The struct analogue of the whole family is HasBuilder.

Under the hood​

The derive generates a companion enum with one MapType parameter per variant, each payload wrapped in that parameter's projection. cargo cgp expand on the example's Shape shows it:

///The partial extractor for [`Shape`].
pub enum __PartialShape<__F0__: MapType, __F1__: MapType> {
Circle(<__F0__ as MapType>::Map<Circle>),
Rectangle(<__F1__ as MapType>::Map<Rectangle>),
}

to_extractor starts at the all-IsPresent configuration, where every variant is still possible. The derive then writes one ExtractField impl per variant, and the Circle one shows the whole mechanism:

impl<__F1__: MapType> ExtractField<Symbol!("Circle")>
for __PartialShape<IsPresent, __F1__> {
type Value = Circle;
type Remainder = __PartialShape<IsVoid, __F1__>;
fn extract_field(
self,
_tag: ::core::marker::PhantomData<Symbol!("Circle")>,
) -> Result<
<Self as ExtractField<Symbol!("Circle")>>::Value,
<Self as ExtractField<Symbol!("Circle")>>::Remainder,
> {
match self {
__PartialShape::Circle(value) => Ok(value),
__PartialShape::Rectangle(value) => Err(__PartialShape::Rectangle(value)),
}
}
}

The impl exists only while Circle's marker is IsPresent, and on a miss it returns the remainder with that one marker flipped to IsVoid while __F1__ passes through, which is why extractions may happen in any order. That per-variant scoping is the mirror of BuildField's requirement that a field be IsNothing before it can be set, and it makes a repeated attempt a compile error rather than a guaranteed Err.

The exhaustiveness argument itself belongs to FinalizeExtract, and turns on IsVoid mapping a payload to the uninhabited Void.

The borrowed accessors use a second companion, __PartialRefShape, with a lifetime and an extra MapTypeRef parameter that HasExtractorRef fixes to IsRef and HasExtractorMut to IsMut. The derive emits the same per-variant ExtractField impls on it, so a value can be matched without being moved and the narrowing works identically.

Common Mistakes​

Self is an extractor, not the enum. A chain starts with to_extractor or one of its borrowing siblings.

Attempting the same variant twice does not compile, and the error is not about the variant. Extracting Circle again from the remainder of a failed Circle attempt:

if let Err(remainder) = shape.to_extractor().extract_field(PhantomData::<Symbol!("Circle")>) {
let _ = remainder.extract_field(PhantomData::<Symbol!("Circle")>);
}

leaves only the Rectangle impl applicable, so rustc settles on it and reports the tag argument as the wrong type:

error[E0308]: mismatched types
...
| ------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `9`, found `6`

The two numbers are the lengths of Rectangle and Circle in their Symbol types, and the note lines below spell both out.

Absence is IsVoid here and IsNothing in a builder, and they are not interchangeable. An error naming the wrong one usually means record and variant machinery have been crossed.

A remainder carries none of the enum's attributes. The partial enums are generated without your derives, so a Result<Payload, Remainder> is neither Debug nor PartialEq however the enum is derived. On a Shape deriving both:

assert_eq!(
shape.to_extractor().extract_field(PhantomData::<Symbol!("Circle")>),
Ok(Circle { radius: 1.0 })
);

fails with

error[E0369]: binary operation `==` cannot be applied to type `Result<Circle, __PartialShape<IsVoid, IsPresent>>`
...
error[E0277]: `__PartialShape<IsVoid, IsPresent>` doesn't implement `Debug`

Reach for .ok(), .is_ok(), or a match.

Order is free but the set is not. Each step changes only its own variant's marker, so extractions may be written in any order, but every variant must be tried before the remainder can be finalized.

Adding a variant breaks every hand-written chain, by design. That is the guarantee, and it is the reason to prefer the dispatch combinators.

The ideas behind it:

  • Extensible variants: partial variants, the exhaustiveness argument, and the extensible visitor pattern.
  • Dispatching: routing a variant to the implementation that handles 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.