Skip to main content

HasExtractorMut

Obtaining an extractor that can change a payload in place.

Overview​

In Context-Generic Programming (CGP), HasExtractorRef borrows an enum so its variants can be read without consuming it. HasExtractorMut borrows it mutably, so a payload can be changed in place.

Payloads come out as &mut T. The original survives, mutably borrowed for the duration, and the narrowing works exactly as it does for the other two accessors: ExtractField does not care how the payloads are held.

It is the third of the group, and the one to reach for least often:

payloads come out asthe original
HasExtractorownedconsumed
HasExtractorRef&Tsurvives
HasExtractorMut&mut Tsurvives, mutably borrowed

Definition​

HasExtractorMut produces a mutably-borrowing extractor:

pub trait HasExtractorMut {
type ExtractorMut<'a>
where
Self: 'a;

fn extractor_mut(&mut self) -> Self::ExtractorMut<'_>;
}

Self is the enum. ExtractorMut<'a> is a generic associated type: the borrowed extractor, the same companion enum HasExtractorRef uses, with every payload held as a mutable reference for 'a. The where Self: 'a clause keeps it from outliving the value. extractor_mut takes a mutable borrow and returns the extractor at the anonymous lifetime, so the call reads without a written lifetime and the borrow ends where the extractor is dropped.

Usage​

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

The impls come from #[derive(ExtractField)], alongside the owning and shared-borrow accessors.

Examples​

Changing whichever payload is present, without rebuilding the enum:

use cgp::core::field::traits::{ExtractField, FinalizeExtractResult, HasExtractorMut};
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(Debug, PartialEq, ExtractField)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}

pub fn scale(shape: &mut Shape, factor: f64) {
match shape.extractor_mut().extract_field(PhantomData::<Symbol!("Circle")>) {
Ok(circle) => circle.radius *= factor,
Err(remainder) => {
let rect = remainder
.extract_field(PhantomData::<Symbol!("Rectangle")>)
.finalize_extract_result();
rect.width *= factor;
rect.height *= factor;
}
}
}

pub fn demo() {
let mut shape = Shape::Circle(Circle { radius: 1.0 });
scale(&mut shape, 5.0);

// `shape` now holds the updated `Circle`.
assert_eq!(shape, Shape::Circle(Circle { radius: 5.0 }));
}

Each payload arrives as &mut, so the writes land in the original value, and the chain still ends in a checked finalize_extract_result. Written with HasExtractor instead, the same code would consume shape and have to rebuild it.

When to use it​

Reach for it only when a payload must be mutated in place, which is the narrowest of the three cases.

  • HasExtractorRef for a read. Requiring mutable access where a shared borrow would do prevents a caller from holding any other reference to the value.
  • HasExtractor when the payload must be moved out.
  • HasExtractorMut when the value stays where it is and one of its payloads changes.
  • A match on &mut when the enum is concrete. if let Shape::Circle(c) = &mut shape does this in a line, and the family is for code that cannot name the enum.
  • Consider returning a new value instead. Much CGP code threads state through handler outputs rather than mutating in place, which composes better with the handler family.

Under the hood​

It uses the same borrowed companion as HasExtractorRef, with the MapTypeRef marker fixed to IsMut rather than IsRef. cargo cgp expand on the example's Shape shows the impl:

impl HasExtractorMut for Shape {
type ExtractorMut<'__a__> = __PartialRefShape<'__a__, IsMut, IsPresent, IsPresent>
where
Self: '__a__;
fn extractor_mut<'__a__>(&'__a__ mut self) -> <Self as HasExtractorMut>::ExtractorMut<'__a__> {
match self {
Self::Circle(value) => __PartialRefShape::Circle(value),
Self::Rectangle(value) => __PartialRefShape::Rectangle(value),
}
}
}

Since IsMut::Map<'a, T> is &'a mut T, every payload slot becomes a mutable reference while the per-variant MapType markers continue to track possibility. That one marker is the whole difference between the two borrowing accessors, and the same ExtractField and FinalizeExtract impls serve both.

The trait lacks a rebuild counterpart, and needs none, because the value was never taken apart, only borrowed.

Common Mistakes​

It takes &mut self, so nothing else may borrow the value for as long as the extractor or any payload taken from it lives. That is ordinary borrow checking.

Payloads are &mut T, so a chain cannot move one out. Taking ownership needs HasExtractor.

It cannot rebuild the enum. from_extractor belongs to the owning accessor alone.

The where Self: 'a clause propagates, so a signature holding an ExtractorMut<'a> rarely elides its lifetime cleanly.

The owned and borrowed extractors are different enums. The two borrowing accessors share __PartialRefShape and differ in its MapTypeRef marker, while the owned one is __PartialShape, so code generic over "an extractor" is generic over the extractor type itself.

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

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.