FinalizeBuild
Turning a fully-built partial record back into the concrete struct.
Overview
FinalizeBuild is where a build ends when Context-Generic Programming (CGP) assembles a
struct generically, one named field at a time. What makes it the family's safety argument is not the
method but where the impl exists. It is implemented for exactly one configuration of a partial
record, the one in which every field is IsPresent, so calling it on an incomplete value is a
missing impl, not a runtime check that fails:
let person = Person::builder()
.build_field(PhantomData::<Symbol!("first_name")>, first)
.build_field(PhantomData::<Symbol!("last_name")>, last)
.finalize_build(); // resolves only here
Delete a middle line and this does not compile. There is nothing to run and nothing to panic: the method is not in scope for a value with a field still absent.
The destination type comes from its supertrait PartialData, which every
configuration implements. That division is deliberate: one names where you are going, the other says
you have arrived.
Definition
FinalizeBuild has one method and a supertrait:
pub trait FinalizeBuild: PartialData {
fn finalize_build(self) -> Self::Target;
}
finalize_build takes self by value, so it consumes the partial record, and returns
Self::Target, the concrete struct being built. Target is not declared here: it comes from the
supertrait PartialData, which every configuration of a partial record
implements, so the destination is nameable at any point in a build. FinalizeBuild adds the method,
and its impl exists for only one configuration (every field IsPresent), which is the safety
argument the rest of this page works out.
Usage
It is not in the prelude. Import it from cgp::core::field::traits.
finalize_build consumes the partial value and returns Self::Target. It takes only self:
nothing is left to decide by the time it applies.
Bounding on it is how generic builder code says it will produce a finished value, as the
assemble function in the example does with FinalizeBuild<Target = Target>.
The impls come from #[derive(BuildField)], which emits exactly one
per record.
Examples
A generic finalize over any complete builder, including a fieldless record:
use cgp::core::field::traits::{BuildField, FinalizeBuild, HasBuilder};
use cgp::prelude::*;
#[derive(Debug, PartialEq, BuildField)]
pub struct Person {
pub first_name: String,
pub last_name: String,
}
#[derive(Debug, PartialEq, BuildField)]
pub struct Empty {}
pub fn assemble<Partial, Target>(partial: Partial) -> Target
where
Partial: FinalizeBuild<Target = Target>,
{
partial.finalize_build()
}
pub fn demo() {
let person: Person = assemble(
Person::builder()
.build_field(PhantomData::<Symbol!("first_name")>, "Alice".to_owned())
.build_field(PhantomData::<Symbol!("last_name")>, "Chen".to_owned()),
);
assert_eq!(person.last_name, "Chen");
// A fieldless record's builder is complete from the start.
let empty: Empty = assemble(Empty::builder());
assert_eq!(empty, Empty {});
}
assemble names only FinalizeBuild, yet it can bind Target, because the projection comes from
the supertrait PartialData. Empty lacks markers to fill, so its builder is
already at the one configuration the impl covers.
When to use it
Call it at the end of every build; bound on it when the code is generic over the record.
- Bound on
HasBuilder+BuildField+FinalizeBuildto write a routine that assembles a record it does not name. - Use
CanFinalizeWithDefaultwhen unset fields should be filled fromDefaultrather than rejected. It re-marks every field toIsPresentand then calls this, so the strict check still runs and always passes. - Use
FinalizeOptionalwhen absence should be reported at run time rather than caught at compile time. It returns aResultnaming a missing field. - Stay with
FinalizeBuildwhen every field is genuinely required. Moving to either of the other two gives up the compile-time completeness check, which is the reason the family exists.
Under the hood
The derive emits one impl, with every marker fixed. cargo cgp expand on the example's Person
shows it beside its supertrait's impl, which leaves every marker generic:
impl<__F0__: MapType, __F1__: MapType> PartialData for __PartialPerson<__F0__, __F1__> {
type Target = Person;
}
impl FinalizeBuild for __PartialPerson<IsPresent, IsPresent> {
fn finalize_build(self) -> Self::Target {
Person {
first_name: self.first_name,
last_name: self.last_name,
}
}
}
So a partial value always knows its destination and only sometimes has a way to reach it. Because
IsPresent::Map<T> is T, the body is a field-by-field move with nothing to unwrap. This is why
the error for an incomplete build is a missing method rather than a missing field: method
resolution looks for finalize_build on __PartialPerson<IsPresent, IsNothing>, does not find an
impl, and reports that, so the marker list in the type is the diagnostic.
The optional layer reaches this same impl rather than replacing it:
CanFinalizeWithDefault runs a
TransformMapFields walk to IsPresent first, so the
strict, all-present impl remains the only way a partial value becomes a concrete struct.
Common Mistakes
"No method named finalize_build" is the expected error for an incomplete build. Setting only
first_name on the example's Person and finalizing:
let person: Person = Person::builder()
.build_field(PhantomData::<Symbol!("first_name")>, "Alice".to_owned())
.finalize_build();
fails with:
error[E0599]: no method named `finalize_build` found for struct `__PartialPerson<__F0__, __F1__>` in the current scope
...
| | -^^^^^^^^^^^^^^ method not found in `__PartialPerson<IsPresent, IsNothing>`
The field whose marker is still IsNothing is the one missing.
It consumes the partial value, so the builder cannot be reused afterwards.
It supertraits PartialData, so naming both in a bound is redundant, and
Target is projected from the supertrait.
It lacks a fallible variant. Reporting absence at run time is
FinalizeOptional, a different trait in a different crate.
A fieldless struct finalizes immediately. Its companion lacks markers, so
builder().finalize_build() compiles, which is legal and useless.
The enum side has its own ending. FinalizeExtract discharges an exhausted
extractor, and it is sound for the opposite reason: the value cannot exist, rather than being complete.
Related constructs
PartialData: the supertrait naming the destination.HasBuilderandIntoBuilder: where a partial value comes from.BuildFieldandTakeField: what moves it between configurations.UpdateField: the primitive underneath both.CanFinalizeWithDefaultandFinalizeOptional: the two relaxed endings.MapType: theIsPresentmarker every field must reach.FinalizeExtract: the enum family's ending, sound for the opposite reason.#[derive(BuildField)]: generates this impl.
The ideas behind it:
- Extensible records: partial records and the extensible builder pattern.
Source
build_field.rs:FinalizeBuildandBuildField
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.