Skip to main content

FieldMapper

The provider-side mirror of MapField.

info

Generated machinery​

You are not expected to implement FieldMapper. It is a blanket impl over every FieldGetter, and ChainGetters is the provider that calls it to descend into a nested value. The one case for naming it is a getter provider of your own that has to read through another provider's field, as the example on this page does.

Overview​

In Context-Generic Programming (CGP), MapField reads through a field of a generic context, the type the method runs on, which supplies the values it needs as its fields, by handing the borrowed field to a closure rather than returning it. FieldMapper is the same operation in provider shape, with a provider as Self and the context as an explicit type argument. This is the form a getter provider needs, because a provider trait's method has its lifetimes fixed by the trait, so a chained read inside it cannot take the lifetime bound a free function could. The group's two-by-two shape holds here too:

you bound againstyou wire
plain readHasFieldFieldGetter
read throughMapFieldFieldMapper

Definition​

FieldMapper<Context, Tag> mirrors MapField, with the context as an explicit type argument:

pub trait FieldMapper<Context, Tag>: FieldGetter<Context, Tag> {
fn map_field<T>(
context: &Context,
_tag: PhantomData<Tag>,
mapper: impl for<'a> FnOnce(&'a Self::Value) -> &'a T,
) -> &T;
}

Self is the provider and Context is the type being read from. It is a supertrait extension of FieldGetter, so Value comes from there, and the for<'a> bound on mapper ties the returned &T to the context's borrow.

Usage​

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

use cgp::core::field::traits::FieldMapper;

Nothing implements it by hand: a blanket impl gives it to every FieldGetter whose provider and tag are 'static, so every field-getter provider can be read through. A provider of your own bounds an inner provider on FieldMapper and calls map_field on it.

Examples​

A two-step getter provider that reads through the field one provider returns with another, wired for a getter, and a direct call through UseContext:

use cgp::core::component::{UseContext, WithProvider};
use cgp::core::field::impls::UseField;
use cgp::core::field::traits::{FieldGetter, FieldMapper, HasField};
use cgp::prelude::*;

pub struct ThenGet<First, Second>(pub PhantomData<(First, Second)>);

impl<Context, Tag, First, Second, Mid, Value> FieldGetter<Context, Tag> for ThenGet<First, Second>
where
First: FieldMapper<Context, Tag, Value = Mid>,
Second: FieldGetter<Mid, Tag, Value = Value>,
{
type Value = Value;

fn get_field(context: &Context, tag: PhantomData<Tag>) -> &Value {
First::map_field(context, tag, |mid| Second::get_field(mid, tag))
}
}

#[cgp_getter(NameGetter)]
pub trait HasName {
fn name(&self) -> &String;
}

#[derive(HasField)]
pub struct Inner {
pub name: String,
}

#[derive(HasField)]
pub struct Outer {
pub inner: Inner,
}

delegate_components! {
Outer {
NameGetterComponent:
WithProvider<ThenGet<UseField<Symbol!("inner")>, UseField<Symbol!("name")>>>,
}
}

check_components! {
Outer {
NameGetterComponent,
}
}

pub fn demo() {
let outer = Outer {
inner: Inner {
name: "Alice".to_owned(),
},
};

assert_eq!(outer.name(), "Alice");

let name = <UseContext as FieldMapper<Outer, Symbol!("inner")>>::map_field(
&outer,
PhantomData,
|inner| inner.get_field(PhantomData::<Symbol!("name")>),
);
assert_eq!(name, "Alice");
}

ThenGet is a two-element ChainGetters, written out to show the mechanism; in real wiring use ChainGetters itself. Its get_field could not be written as Second::get_field(First::get_field(context, tag), tag): that fails with E0311, because Mid is not known to outlive the borrow. Outer is a value context.

When to use it​

Reach for ChainGetters to give a getter a nested field by wiring. Name FieldMapper only when writing a getter provider of your own that must read through another provider's field, and use MapField when the descent is on a generic context in an ordinary function.

Under the hood​

FieldMapper is a blanket impl over every FieldGetter:

impl<Getter, Context, Tag> FieldMapper<Context, Tag> for Getter
where
Getter: FieldGetter<Context, Tag> + 'static,
Tag: 'static,
{
fn map_field<T>(
context: &Context,
tag: PhantomData<Tag>,
mapper: impl for<'a> FnOnce(&'a Self::Value) -> &'a T,
) -> &T {
mapper(Getter::get_field(context, tag))
}
}

Both 'static bounds are on types that are 'static in practice, the tag and the provider, a zero-sized marker; the field's value stays free. ChainGetters nests these calls, one per step, so a chain of any length stays free of lifetime bounds.

Common Mistakes​

A chained get_field inside a provider fails. As the example notes, a provider that calls one getter's get_field on another's result fails with E0311 on the intermediate type; call map_field on the first getter instead.

Self is the provider, not the context. The context is the first type parameter.

A provider with a non-'static parameter loses the blanket impl. The bound on Self holds for an ordinary marker type and not for one carrying a lifetime, a rare shape and a puzzling failure when it happens.

  • MapField: the consumer-side twin, where the lifetime problem is explained in full.
  • FieldGetter: the supertrait, and the plain wired read.
  • ChainGetters: the provider built on this trait.
  • UseField and UseContext: the providers a chain is usually built from.

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.