Skip to main content

TransformOptional

The transform marker that makes every field optional.

info

Generated machinery​

You are not expected to name TransformOptional directly. It is the marker ToOptional and HasOptionalBuilder drive, and you write a call to one of those. This page explains the conversion behind them, and why it needs less of a field's type than its defaulting counterpart does. The one case for naming it is writing an operation of your own that drives the optional conversion.

Overview​

Context-Generic Programming (CGP) tracks each field of a partial record with a type-level marker, and ToOptional re-marks every field to IsOptional, so it can then be set freely and finalized either way. TransformOptional is the marker carrying the per-field conversions that make that possible.

It is the exact mirror of TransformMapDefault, which targets IsPresent instead: same walk, different destination. That symmetry is why the defaulted and optional workflows behave so alike.

You name it only when extending the layer. Using the optional workflow means calling optional_builder() or to_optional(), without naming the marker.

Definition​

TransformOptional is a zero-sized marker type:

pub struct TransformOptional;

It stores nothing. It becomes a transform by implementing TransformMap once for each state a core builder's field can be in, both impls targeting IsOptional:

a field currentlybecomes
IsPresentSome(value)
IsNothingNone

Because both impls target IsOptional, applying the marker across a record leaves every field optional, the configuration SetOptional requires. Unlike its defaulting counterpart it needs nothing of the field types, since wrapping a value in Some and producing None do not require Default. The impl bodies are in Under the hood. The marker is not in the prelude; import it from cgp-field-extra.

Usage​

It is not in the prelude. Import it from cgp::extra::field::impls:

use cgp::extra::field::impls::TransformOptional;

There is nothing to call. The marker is named in a TransformMapFields bound, which is where an operation says which conversion it drives:

Builder: TransformMapFields<TransformOptional, IsOptional>

Unlike its defaulting counterpart, it requires nothing of the field types: wrapping a value in Some and producing None need neither Default nor any other bound, which is why the optional path applies to records the defaulting path does not.

Examples​

A generic function that drives the optional conversion across any builder, and a partly built core builder passed through it:

use cgp::core::field::impls::IsOptional;
use cgp::core::field::traits::{BuildField, HasBuilder, TransformMapFields};
use cgp::extra::field::impls::{FinalizeOptional, SetOptional, TransformOptional};
use cgp::prelude::*;

#[derive(Debug, PartialEq, CgpData)]
pub struct Context {
pub foo: String,
pub bar: u64,
}

pub fn relax<Builder>(builder: Builder) -> Builder::Output
where
Builder: TransformMapFields<TransformOptional, IsOptional>,
{
builder.transform_map_fields()
}

pub fn demo() {
let optional =
relax(Context::builder().build_field(PhantomData::<Symbol!("foo")>, "foo".to_owned()));
let context = optional
.set(PhantomData::<Symbol!("bar")>, 42)
.finalize_optional()
.unwrap();
assert_eq!(context.foo, "foo");
}

relax is ToOptional's whole impl written as a function. Swap the marker for TransformMapDefault and the target for IsPresent, add a finalize_build, and you have CanFinalizeWithDefault.

When to use it​

Name it only when writing an operation that drives the optional conversion.

Under the hood​

The marker is zero-sized and carries two TransformMap impls, distinguished by their source marker, each targeting IsOptional:

impl<T> TransformMap<IsPresent, IsOptional, T> for TransformOptional {
fn transform_mapped(value: T) -> Option<T> {
Some(value)
}
}

impl<T> TransformMap<IsNothing, IsOptional, T> for TransformOptional {
fn transform_mapped(_value: ()) -> Option<T> {
None
}
}

Note what is absent: a Default bound. Its counterpart TransformMapDefault needs one on two of its three impls, because filling an absent field means producing a value from nothing. Producing None does not, so this conversion applies to every field type. Also absent is an impl from IsOptional, which TransformMapDefault has: a field that is already optional has no conversion here, so the marker cannot be applied to an optional builder.

TransformMapFields applies it, visiting each field of the target's HasFields shape and using UpdateField twice per field: once to take the value out and learn its marker, once to write it back under IsOptional.

The result is a partial value at a configuration the core builder never reaches on its own, which is what makes SetOptional resolve and the strict FinalizeBuild not.

Common Mistakes​

It is not in the prelude. Import from cgp::extra::field::impls.

It always targets IsOptional. Reaching IsPresent is TransformMapDefault's job.

It lacks a conversion from IsOptional, so a builder that is already optional cannot be relaxed again; ToOptional shows the error.

It is a marker, not an operation. It lacks a method and needs nothing wired. It is named in a bound.

It requires nothing of the field types, where TransformMapDefault needs Default for every field not already IsPresent. The missing IsOptional impl is the other difference, in the opposite direction.

Converting gives up the compile-time completeness check, since every field becomes optional whether it was set or not.

A field whose type is already Option<T> becomes Option<Option<T>>. The outer layer is the builder's presence tracking, and the two are easy to conflate in an error.

The ideas behind it:

Source​

  • to_optional.rs: TransformOptional, ToOptional, and HasOptionalBuilder

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.