Skip to main content

HasExtractorRef

Obtaining an extractor that borrows the value rather than consuming it.

Overview​

In Context-Generic Programming (CGP), HasExtractor consumes an enum to produce an extractor with owned payloads. Code that only reads a variant (checking it, measuring it, rendering it) should not have to give up the value. HasExtractorRef is the borrowing accessor.

Payloads come out as shared references and the original survives. The narrowing works identically: ExtractField rules variants out of a borrowed extractor exactly as it does an owned one, and the chain ends the same way.

It is the weakest of the three accessors, so prefer it wherever it suffices.

Definition​

HasExtractorRef produces a borrowing extractor:

pub trait HasExtractorRef {
type ExtractorRef<'a>
where
Self: 'a;

fn extractor_ref(&self) -> Self::ExtractorRef<'_>;
}

Self is the enum. ExtractorRef<'a> is a generic associated type: the borrowed extractor, a second companion enum beside the owned one, with every payload held for the lifetime 'a. The where Self: 'a clause keeps the borrowed extractor from outliving the value it came from. extractor_ref takes a shared borrow of the value and returns the extractor at the anonymous lifetime, which is why the call reads without a written lifetime.

Usage​

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

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

Examples​

Reading through a borrow, as a single attempt and as a full chain, leaves the value intact:

use cgp::core::field::traits::{ExtractField, FinalizeExtractResult, HasExtractorRef};
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 radius(shape: &Shape) -> Option<f64> {
shape
.extractor_ref()
.extract_field(PhantomData::<Symbol!("Circle")>)
.map(|circle| circle.radius)
.ok()
}

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

pub fn demo() {
let shape = Shape::Rectangle(Rectangle { width: 3.0, height: 4.0 });
assert_eq!(radius(&shape), None);
assert_eq!(area(&shape), 12.0);

// `shape` is still usable here.
assert_eq!(shape, Shape::Rectangle(Rectangle { width: 3.0, height: 4.0 }));
}

The payloads arrive as &Circle and &Rectangle, so fields read through the borrow and nothing is moved. The full chain narrows and finalizes exactly as an owned one does, with each remainder also borrowing.

When to use it​

Reach for it whenever the value must survive, which is most read-only code over an enum.

  • HasExtractorRef for a read-only operation. Prefer it over consuming, since requiring ownership narrows what a caller can pass without any benefit.
  • HasExtractorMut to change a payload in place.
  • HasExtractor only when the payload must be moved out.
  • A match when the enum is concrete. This family is for code that cannot name it.
  • ToFieldsRef when what you want is the value's borrowed shape rather than a narrowing chain: the same borrow-rather-than-consume idea, applied to the whole-shape view.

Under the hood​

The borrowing accessors use a second companion enum, __PartialRefShape, beside the owned __PartialShape. cargo cgp expand on the example's Shape shows it:

///The borrowed partial extractor for [`Shape`].
pub enum __PartialRefShape<'__a__, __R__: MapTypeRef, __F0__: MapType, __F1__: MapType> {
Circle(<__F0__ as MapType>::Map<<__R__ as MapTypeRef>::Map<'__a__, Circle>>),
Rectangle(<__F1__ as MapType>::Map<<__R__ as MapTypeRef>::Map<'__a__, Rectangle>>),
}

and this trait's impl, which fixes the MapTypeRef marker to IsRef and every variant to still possible:

impl HasExtractorRef for Shape {
type ExtractorRef<'__a__> = __PartialRefShape<'__a__, IsRef, IsPresent, IsPresent>
where
Self: '__a__;
fn extractor_ref<'__a__>(&'__a__ self) -> <Self as HasExtractorRef>::ExtractorRef<'__a__> {
match self {
Self::Circle(value) => __PartialRefShape::Circle(value),
Self::Rectangle(value) => __PartialRefShape::Rectangle(value),
}
}
}

Read the payload type outward: the MapTypeRef marker decides how a payload is held (IsRef::Map<'a, T> is &'a T), and the per-variant MapType marker decides whether it is still possible. The two axes are independent, which is why narrowing behaves the same through a borrow as through an owned value. The derive emits the per-variant ExtractField impls and the all-IsVoid FinalizeExtract impl on this enum too, generic over the MapTypeRef marker, so a borrowed chain finalizes exactly as an owned one does.

The trait lacks a from_extractor counterpart: a borrowed extractor cannot rebuild an owned enum, and the original is still there anyway.

Common Mistakes​

It cannot rebuild the enum. HasExtractor's from_extractor lacks a borrowing equivalent, which is rarely a problem since the value was never consumed.

Payloads are &T, so a chain cannot move one out. A routine that must take ownership of a payload needs HasExtractor.

The where Self: 'a clause propagates. A signature that stores or returns ExtractorRef<'a> usually has to spell the lifetime out rather than elide it.

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

The borrowed and owned extractors are different enums, __PartialRefShape and __PartialShape. Code generic over "an extractor" is generic over the extractor type itself, with ExtractField bounds on it, rather than over a marker.

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.