HasBuilder
Starting an empty builder for a record.
Overview
A struct literal supplies every field at once, in one place that names the type.
Context-Generic Programming (CGP) builds structs generically, by their field names, and
HasBuilder is its entry point for the case where a literal is impossible: the fields come from
several independent places, none of which should know the whole struct, and the result must still be
checked at compile time.
builder() hands back a partial value with every field absent. Filling it is
BuildField, and turning it back into the concrete struct is
FinalizeBuild, which is implemented only for the fully-present
configuration, so finalizing early is a missing impl rather than a runtime panic:
let person = Person::builder() // every field absent
.build_field(PhantomData::<Symbol!("first_name")>, first)
.build_field(PhantomData::<Symbol!("last_name")>, last)
.finalize_build(); // all present: this resolves
Delete a middle line and this does not compile. Field presence lives in the type, which is the defining idea of the whole family.
Definition
HasBuilder is a small trait: one associated type and one associated function.
pub trait HasBuilder {
type Builder;
fn builder() -> Self::Builder;
}
Self is the concrete record being built. Builder is the partial companion type the derive
generates for it, the record carrying one MapType presence marker per
field. builder() is an associated function, so it does not take a receiver, and it returns that
companion at its all-absent configuration, ready to fill.
Usage
It is not in the prelude. Import it from cgp::core::field::traits.
builder() is called without a receiver, as Person::builder() or T::builder() in generic code.
You rarely name the Builder type yourself, but it appears in an error when a build is incomplete.
The impls come from #[derive(BuildField)], also available through
#[derive(CgpRecord)] and
#[derive(CgpData)].
Its counterpart is IntoBuilder, which starts from an existing value with every
field present rather than from nothing. The two differ only in where they begin, and the choice is
about whether you are assembling a record or redistributing one.
Examples
A record extended from a narrower one, and a field read back off a still-incomplete builder:
use cgp::core::field::impls::CanBuildFrom;
use cgp::core::field::traits::{BuildField, FinalizeBuild, HasBuilder, HasField};
use cgp::prelude::*;
// `build_from` walks the *source's* field list, so the source needs `HasFields` too.
#[derive(HasFields, BuildField)]
pub struct FooBar {
pub foo: u64,
pub bar: String,
}
#[derive(Debug, PartialEq, BuildField)]
pub struct FooBarBaz {
pub foo: u64,
pub bar: String,
pub baz: bool,
}
pub fn extend(foo_bar: FooBar) -> FooBarBaz {
FooBarBaz::builder()
.build_from(foo_bar)
.build_field(PhantomData::<Symbol!("baz")>, true)
.finalize_build()
}
pub fn demo() {
// A set field can be read back off a still-incomplete builder.
let partial = FooBarBaz::builder().build_field(PhantomData::<Symbol!("baz")>, true);
assert!(*partial.get_field(PhantomData::<Symbol!("baz")>));
let foo_bar_baz = extend(FooBar {
foo: 1,
bar: "bar".to_owned(),
});
assert_eq!(
foo_bar_baz,
FooBarBaz {
foo: 1,
bar: "bar".to_owned(),
baz: true,
}
);
}
Every step changes the partial type, and finalize_build type-checks only because every marker
has reached IsPresent; moving it before the baz step is a compile error. A set field can be read
back mid-build because the derive emits a HasField impl on the
partial type for each field once it is present.
When to use it
Call builder() freely in concrete code; bound on the trait only in generic code. In concrete code
you call it and never name a trait. The bound matters when you write code that is generic over the
record being built, which is the extensible builder pattern, and the reason the family exists.
- Bound on
HasBuilder+BuildField+FinalizeBuildto write a routine that assembles some record it does not name. - Use
IntoBuilderwhen you start from an existing value rather than from nothing. - Do not reach for any of it for a struct you build with a literal. A literal is already checked for completeness, reads better, and generates nothing. This family buys decoupling, and with nothing to decouple it is pure cost.
Two boundaries are worth stating plainly. This is not a conventional builder: it tracks presence
and nothing else, without defaults, validation at finalize, or optional fields unless the field's
own type is optional. The optional-field extensions cover the
defaulted and optional cases, and a hand-written builder remains better when the logic is the
point. And the enum counterparts are a different family:
ExtractField for taking a value apart and
FromVariant for constructing one.
Under the hood
#[derive(BuildField)] generates a companion struct, __Partial{Name}, with one
MapType parameter per field and each field's type wrapped in that
parameter's projection. cargo cgp expand on a two-field Person shows it:
///The partial builder for [`Person`].
pub struct __PartialPerson<__F0__: MapType, __F1__: MapType> {
pub first_name: <__F0__ as MapType>::Map<String>,
pub last_name: <__F1__ as MapType>::Map<String>,
}
HasBuilder fixes the starting configuration to all-absent, where each field is stored as ():
impl HasBuilder for Person {
type Builder = __PartialPerson<IsNothing, IsNothing>;
fn builder() -> Self::Builder {
__PartialPerson {
first_name: (),
last_name: (),
}
}
}
and FinalizeBuild exists only at the opposite end:
impl FinalizeBuild for __PartialPerson<IsPresent, IsPresent> {
fn finalize_build(self) -> Self::Target {
Person {
first_name: self.first_name,
last_name: self.last_name,
}
}
}
That pair is the whole safety argument. builder() starts at all-absent, each
build_field flips one marker, and nothing is checked at the end: the
impl is absent for an incomplete value. Everything between the two ends reduces to one primitive,
UpdateField, which is what the derive writes per field;
BuildField and TakeField are library blanket impls over
it in opposite directions.
Common Mistakes
"No method named finalize_build" is the expected error for an incomplete build. A missing
field means the all-present impl does not apply, so the compiler reports a missing method rather
than a missing field. Finalizing a Person with only first_name set:
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 marker still IsNothing is the missing field, here last_name.
build_from needs HasFields on the source. It walks the source's
field list, so a source with only #[derive(BuildField)]:
#[derive(BuildField)]
pub struct FooBar {
pub foo: u64,
}
#[derive(BuildField)]
pub struct FooBaz {
pub foo: u64,
pub baz: bool,
}
let _ = FooBaz::builder()
.build_from(FooBar { foo: 1 })
.build_field(PhantomData::<Symbol!("baz")>, true)
.finalize_build();
fails on the source rather than on the builder:
error[E0277]: the trait bound `FooBar: HasFields` is not satisfied
...
= note: required for `__PartialFooBaz<IsNothing, IsNothing>` to implement `CanBuildFrom<FooBar>`
The example derives both on its FooBar.
The partial type cannot be printed or cloned. The derive drops the original's struct-level
attributes, so it lacks Debug, Clone, and every other derive the record carries. Read a set
field through the partial type's HasField impl instead.
Each field keeps only its documentation, so a field helper attribute such as
#[serde(rename = "...")] does not reach the partial type.
It neither defaults nor validates. Presence is all that is tracked. A field with a sensible default still has to be set, unless you reach for the optional-field extensions.
builder() is an associated function. It does not take a receiver, so it is Person::builder()
rather than anything called on a value. Starting from a value is IntoBuilder.
A fieldless struct's builder is immediately finalizable, since there is nothing to track.
Empty::builder().finalize_build() compiles for a struct Empty {}, which is legal and useless.
Related constructs
IntoBuilder: the other entry point, starting from a complete value.BuildField: setting one absent field.TakeField: the reverse, removing one present field.UpdateField: the primitive both are built from.PartialDataandFinalizeBuild: naming the destination, and reaching it.CanBuildFrom: merging every field of another record into the builder.#[derive(BuildField)]: generates the partial type and every impl in the family.MapType: theIsPresent/IsNothingmarkers presence is encoded in.HasField: how a set field is read back off a partial value.- Optional fields: defaulted and optional finalization.
ExtractFieldandFromVariant: the enum counterparts.
The ideas behind it:
- Extensible records: partial records and the extensible builder pattern.
Source
has_builder.rs:HasBuilderandIntoBuilder
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.