DeserializeRecordFields
Read a struct from a map, reading each field through the context and building the struct field by field.
Overview
In cgp-serde, a serialization library built with
Context-Generic Programming (CGP), DeserializeRecordFields is the reading half of
SerializeRecordFields. It reads a map, asks the context, the
type whose wiring holds the application's choices, to read each field's value, and collects the
values in CGP's builder for the struct until every field is present. The struct derives only CGP's
field traits, through #[derive(CgpData)] or the
narrower HasFields and
BuildField derives.
Definition
pub struct DeserializeRecordFields;
#[cgp_impl(DeserializeRecordFields)]
impl<'de, Record, Builder> ValueDeserializer<'de, Record>
where
Record: HasOptionalBuilder<Builder = Builder> + HasFields,
Record::Fields: HandleMapEntry<'de, Self, Builder>,
Builder: FinalizeOptional<Target = Record>,
{ ... }
HasOptionalBuilder gives a builder that
holds each field as an Option, so fields can arrive in any order, and
FinalizeOptional turns it into the struct
once every field is set. HandleMapEntry is a private trait that matches a key against the field
list, and it requires, for each field, that the context can read the field's type.
Usage
Import it from cgp_serde::providers, and wire it beside an entry for each field's type. From the
basic example:
@ValueDeserializerComponent.[
u64,
String,
]:
UseSerde,
@ValueDeserializerComponent.Payload:
DeserializeRecordFields,
@ValueDeserializerComponent.Vec<u8>: SerializeHex,
Behavior
The provider asks the format for a map and reads it entry by entry. It compares each key with the field names, and on a match reads the value through the context and stores it in the builder. A key that matches no field is skipped, with its value. When the map ends, the builder is finished, which succeeds only if every field was set. The order of the keys does not matter.
The provider reports three failures, each through Serde's Error::custom, so the format adds its
position to the message:
- A field is missing, after the whole map is read. With JSON,
{"a":1}read as a struct with fieldsaandbfails withmissing field: b at line 1 column 7. A field whose type is anOptionis no exception: it may benull, but it must be present. - A field appears twice, at the second occurrence:
{"a":1,"a":2,"b":3}fails withduplicate field: a at line 1 column 12. - The input is not a map, as the format's type error; with JSON, an array fails with
invalid type: sequence, expected map.
Only structs with named fields work, since a field's name is its key. A struct with a lifetime works
the same way: the arena example's Payload<'a> is read with this provider, its Vec<&'a Coord>
field through DeserializeExtend.
Context dependencies
CanDeserializeValue<'de, F> for the type F of every field.
Pairing
SerializeRecordFields writes the map it reads.
When to use it
Reach for DeserializeRecordFields to read a struct whose fields should follow the context's
choices. Every field is required: a field wired to
DeserializeDefault still has to appear in the input, since that
provider replaces a null value, not a missing one.
Related constructs
DeserializeExtendis the matching provider for a collection.
The ideas behind it
- Derive-free records: reading a struct through CGP's field traits.
- Extensible records: the builder the provider fills in.
Source
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.