Skip to main content

PartialData

Naming the concrete type a partial value is on its way to becoming.

info

Generated machinery​

You are not expected to implement PartialData. #[derive(BuildField)] and #[derive(ExtractField)] emit it for every companion type they generate. You meet the projection Self::Target in another trait's signature; this page explains where that projection comes from. The one case for bounding on it is generic code that needs the destination type before the value is complete.

Overview​

Context-Generic Programming (CGP) builds a struct generically through a partial record, a companion type (__PartialPerson<IsNothing, IsPresent>) that tracks which fields are set, and generic code holding one often needs to know what it will become before it is complete: to name the return type of a routine, to state a bound, to decide what to do next. PartialData answers that: its single Target associated type is the concrete struct or enum the partial value corresponds to. It is implemented for every configuration, complete or not, and that coverage is the point: the destination is knowable from the first builder() call, long before any field is set.

That is the division of labour with FinalizeBuild, which is implemented only at the all-present configuration. One says where you are going; the other says you have arrived.

Definition​

PartialData is a single associated type and nothing else:

pub trait PartialData {
type Target;
}

Self is a partial companion type, a record builder or an extraction remainder. Target is the concrete struct or enum it belongs to. It lacks a method, because naming a type is not an operation; the trait exists so that generic code can project Self::Target while holding a value of unknown completeness. FinalizeBuild and FinalizeOptional both read the destination through this projection rather than declaring one of their own.

Usage​

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

You bound on it when a signature must mention the destination while holding a partial value, as Partial::Target in the target_name function of the example.

The impls come from #[derive(BuildField)] for a record and #[derive(ExtractField)] for an enum. Both partial families implement it, which is worth knowing because it is the one trait the builder and extractor sides share directly.

Examples​

A generic function naming the destination of a partial value, at two configurations:

use cgp::core::field::traits::{BuildField, HasBuilder, PartialData};
use cgp::prelude::*;

#[derive(Debug, PartialEq, BuildField)]
pub struct Person {
pub first_name: String,
pub last_name: String,
}

pub fn target_name<Partial>(_partial: &Partial) -> &'static str
where
Partial: PartialData,
{
core::any::type_name::<Partial::Target>()
}

pub fn demo() {
let empty = Person::builder();
assert!(target_name(&empty).ends_with("Person"));

let half = empty.build_field(PhantomData::<Symbol!("first_name")>, "Alice".to_owned());
assert!(target_name(&half).ends_with("Person"));
}

Partial::Target is Person for the empty builder and the half-built one alike, since the impl covers every configuration.

When to use it​

Bound on it when generic code needs the destination type mid-build, and reach for the more specific traits otherwise.

  • FinalizeBuild when the value is complete and should become the struct. It supertraits this, so bounding on both is redundant.
  • HasBuilder when you have the concrete type and want a builder. That is the opposite direction: Person::Builder from Person, rather than Target from a partial.
  • PartialData when the code holds a partial value of unknown completeness and must name what it belongs to: a signature, a where clause, an error message.
  • TransformMapFields requires it, which is the other place it shows up in a bound rather than as a projection.

Under the hood​

The derive emits one impl covering every configuration at once, by leaving the markers generic. cargo cgp expand on a two-field Person shows:

impl<__F0__: MapType, __F1__: MapType> PartialData for __PartialPerson<__F0__, __F1__> {
type Target = Person;
}

Nothing about the markers is constrained, so the destination stays available at every step of a build. Contrast FinalizeBuild, whose impl fixes every marker to IsPresent. Splitting the two lets generic builder code name a destination while still being unable to finalize early. The enum side implements it the same way on its extraction companions, with Target naming the original enum.

Common Mistakes​

It says nothing about completeness. A PartialData bound is satisfied by an empty builder as readily as by a full one. Requiring completeness is FinalizeBuild.

Both families implement it. A PartialData bound admits an extraction remainder as well as a record builder, which is occasionally what you want and occasionally too permissive.

FinalizeBuild supertraits it, so naming both in a bound is redundant.

Target is the original type, not the partial one. Reading the projection the other way round is the usual confusion when meeting it in an error.

It lacks a method. Getting a value of Target is a finalize; this only names the type.

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.