Skip to main content

SerializeVariantFields

Write an enum as {"Variant": payload}, asking the context to write the payload.

Overview​

In cgp-serde, a serialization library built with Context-Generic Programming (CGP), SerializeVariantFields serializes an enum that derives nothing from Serde. It reads the enum's variants through CGP's field traits, which #[derive(CgpVariant)] provides, and asks the context, the type whose wiring holds the application's choices, to write the active variant's payload. So one generic provider serves every such enum, and each payload is encoded however the context encodes its type.

Every variant must hold one unnamed payload, as Circle(Circle) does, or no fields, as Empty does, which is also what CgpVariant requires. A variant with no fields has the payload Nil, so the context decides how it is written through its entry for Nil.

Definition​

pub struct SerializeVariantFields;

#[cgp_impl(SerializeVariantFields)]
impl<Value> ValueSerializer<Value>
where
Value: ToFieldsRef,
for<'a> Value::FieldsRef<'a>: VariantsSerializer<Self>,
{ ... }

ToFieldsRef borrows the enum as a list of its variants, each paired with its name. VariantsSerializer is a private trait that finds the active variant in that list, and it requires, for each variant, that the context can write the payload's type, Nil for a variant with no fields.

Usage​

Import it from cgp_serde::providers, and wire it beside an entry for each variant's payload type:

#[derive(CgpVariant)]
pub enum Shape {
Circle(Circle),
Label(String),
Empty,
}

delegate_components! {
App {
open ValueSerializerComponent;

@ValueSerializerComponent.[u64, String]: UseSerde,
@ValueSerializerComponent.Nil: SerializeUnit,
@ValueSerializerComponent.Circle: SerializeRecordFields,
@ValueSerializerComponent.Shape: SerializeVariantFields,
}
}

Here Circle is a struct with one radius: u64 field, so its own entry needs u64, and SerializeUnit writes the Nil of Empty.

Behavior​

The provider writes the active variant as a Serde newtype variant, with the variant's name and its position in the declaration. With JSON, Shape::Circle(Circle { radius: 3 }) is written as {"Circle":{"radius":3}} and Shape::Label("hi".into()) as {"Label":"hi"}, exactly what Serde's derive writes for those variants. Shape::Empty is written as {"Empty":null}, because Nil is wired to SerializeUnit. Every empty form is written that way, while Serde's derive writes each form its own way:

VariantThis providerSerde's derive
Empty{"Empty":null}"Empty"
Empty(){"Empty":null}{"Empty":[]}
Empty {}{"Empty":null}{"Empty":{}}

Serde's derive reads {"Empty":null} back only for the first form. In postcard the two agree, since every form is written as the variant's position alone.

Other formats see the same Serde calls. RON writes Label("x"), and postcard writes the variant's position followed by its payload. Both match Serde's derive, except where the payload is a struct: structs are written as maps without a declared length, which RON shows in map syntax and postcard rejects.

Context dependencies​

CanSerializeValue<P> for the payload type P of every variant, which is Nil for a variant with no fields.

Pairing​

DeserializeVariantFields reads what it writes.

When to use it​

Reach for SerializeVariantFields to write an enum whose payloads should follow the context's choices. Its limits are worth knowing first:

  • The enum must not borrow. An enum with a lifetime, such as Token<'a> holding a &'a str, fails to compile with "the type Token<'a> does not fulfill the required lifetime", because of a current limitation in how Rust proves lifetime bounds. Token<'static> works, and reading a borrowing enum with DeserializeVariantFields works too.
  • Only Serde's default enum form is written. There is no internally tagged, adjacently tagged, or untagged form, and a variant with no fields is written as {"Empty":null}, which does not match Serde's derive in JSON or RON.
  • An enum that contains itself, such as an expression tree, fails to compile, as a struct that contains itself does.

An enum outside these limits keeps its own Serde impl and is wired to UseSerde.

The ideas behind it​

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.