Skip to main content

TransformMap

The per-field function that converts a value from one marker's storage to another's.

Overview​

Context-Generic Programming (CGP) tracks each field of a partial record with a type-level marker, and MapType only names each marker's storage type: it says that an IsNothing field holds () and an IsPresent field holds its value, and nothing about how you get from one to the other. TransformMap carries that missing half: the function that performs the conversion.

This is the extension point of the whole partial-type scheme, and it is genuinely usable. Defining a new way to re-mark a record means writing one impl per source state and then applying it with TransformMapFields.

Definition​

TransformMap is parameterized by a source marker, a target marker, and a value type, and carries one method:

pub trait TransformMap<M1: MapType, M2: MapType, T> {
fn transform_mapped(value: M1::Map<T>) -> M2::Map<T>;
}

Self is a transform marker of your own naming. M1 is the field's current state and M2 the state it should end in, both MapType markers, and T is the field's value type. transform_mapped takes the field's value as stored under M1 (M1::Map<T>) and returns it as stored under M2 (M2::Map<T>). So one impl answers one question: given a field currently in state M1, produce the same field in state M2.

Usage​

It is not in the prelude. Import it from cgp::core::field::traits, along with any non-prelude marker you name; IsOptional comes from cgp::core::field::impls:

use cgp::core::field::impls::IsOptional;
use cgp::core::field::traits::TransformMap;

The trait is implemented on a transform marker, a zero-sized type you declare. It stores nothing and exists only to name the set of conversions, exactly as a provider does elsewhere in CGP.

A transform needs an impl for every source marker a field might currently be in. That rule decides how many impls you write, and getting it wrong is the usual failure, shown in Common Mistakes.

Examples​

A marker that fills absent fields from Default, one impl per source state, applied to a builder with one field set:

use cgp::core::field::impls::{IsNothing, IsOptional, IsPresent};
use cgp::core::field::traits::{BuildField, FinalizeBuild, HasBuilder, TransformMap, TransformMapFields};
use cgp::prelude::*;

pub struct FillDefaults;

impl<T> TransformMap<IsPresent, IsPresent, T> for FillDefaults {
fn transform_mapped(value: T) -> T {
value
}
}

impl<T: Default> TransformMap<IsNothing, IsPresent, T> for FillDefaults {
fn transform_mapped(_value: ()) -> T {
T::default()
}
}

impl<T: Default> TransformMap<IsOptional, IsPresent, T> for FillDefaults {
fn transform_mapped(value: Option<T>) -> T {
value.unwrap_or_default()
}
}

#[derive(Debug, PartialEq, CgpData)]
pub struct Config {
pub port: u16,
pub verbose: bool,
}

pub fn with_defaults() -> Config {
let partial = Config::builder().build_field(PhantomData::<Symbol!("port")>, 8080);

TransformMapFields::<FillDefaults, IsPresent>::transform_map_fields(partial)
.finalize_build()
}

pub fn demo() {
assert_eq!(
with_defaults(),
Config {
port: 8080,
verbose: false,
}
);
}

Read the impls as three cases of one rule: a present field passes through, an absent one becomes its default, and an optional one becomes its contents or the default. Each argument type is the source marker's Map<T> (T, then (), then Option<T>), which keeps the three impls from overlapping. Because all three target IsPresent, applying FillDefaults through transform_map_fields leaves every field present, the configuration FinalizeBuild accepts, so verbose comes out as false.

That is not hypothetical: it is how CanFinalizeWithDefault works, and reading it here is the shortest route to understanding that layer.

When to use it​

Implement it to define a new per-field conversion, and reach for the existing layer otherwise.

  • Use the optional-field layer if what you want is defaulted or optional finalization. Both already exist, built on exactly this, and TransformMapDefault and TransformOptional are the two markers it ships.
  • Implement TransformMap for a conversion those do not cover: a validating transform, one that logs, or one that fills from something other than Default.
  • Use TransformMapFields to apply what you have written. This trait converts one field; that one walks a whole record.
  • Do not implement MapType for a new marker and expect the derives to use it. A fifth state marker is reachable only through update_field and a transform; a new transform marker, by contrast, works immediately.

Under the hood​

The signature's argument and return types are projections through the two markers, so the concrete types differ per impl even though the trait is the same. TransformMap<IsNothing, IsPresent, T> has an argument type of <IsNothing as MapType>::Map<T>, which normalizes to (), and a return type of T. That lets three impls for one marker coexist without overlapping: they differ in M1.

TransformMapFields calls this. For each field of the target's HasFields shape, it uses UpdateField to take the field out (learning the marker it was in), applies Transform::transform_mapped, and writes the result back under the target marker.

Two consequences follow from that construction, and both explain limits you might otherwise trip over. The transform must have an impl for every source marker a field might currently be in, which is why FillDefaults above needs three rather than one. And the walk is driven by the target's shape, so it re-marks exactly the fields the concrete struct declares.

Nothing here has a runtime representation beyond the field values themselves: the markers are zero-sized, and transform_mapped is an associated function without a receiver.

Common Mistakes​

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

It needs an impl per source state. Writing only the IsNothing case, as pub struct OnlyAbsent; with a single TransformMap<IsNothing, IsPresent, T> impl, and applying it to a Config builder whose port is already set:

let partial = Config::builder().build_field(PhantomData::<Symbol!("port")>, 8080);
let _ = TransformMapFields::<OnlyAbsent, IsPresent>::transform_map_fields(partial);

fails with two errors. The first is a misleading mismatch on the walk's internal UpdateField step; the second names the missing impl, identifying the field by its value type rather than its name:

error[E0271]: type mismatch resolving `<__PartialConfig<IsPresent, IsPresent> as UpdateField<Symbol<4, Chars<'p', Chars<'o', Chars<'r', Chars<'t', Nil>>>>>, IsNothing>>::Mapper == IsNothing`
...
error[E0277]: the trait bound `OnlyAbsent: TransformMap<IsPresent, IsPresent, u16>` is not satisfied

Read the second: the source marker is the case to add.

The argument type is the source marker's projection, not T. An impl from IsNothing takes (), one from IsOptional takes Option<T>. Writing T there is the most common mistake.

It converts one field. Applying it to a record is TransformMapFields's job.

A transform whose impls do not all target the same marker will not compose into a finalize. The layer's payoff comes from every field landing in one state, usually IsPresent.

It is an associated function, not a method. It does not take a receiver; the marker exists only as a name.

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.