SerializeIterator
Write any collection that can be iterated by reference as a sequence of its items.
Overview
In cgp-serde, a serialization library built with
Context-Generic Programming (CGP), SerializeIterator writes a Vec, a slice, a set, or
any other collection as a Serde sequence, and asks the context, the type whose wiring holds the
application's choices, to write each item. So the items follow the context's choices: a
Vec<Vec<u8>> in a context that wires Vec<u8> to hex is a list of hex strings.
Definition
#[cgp_impl(new SerializeIterator)]
impl<Value> ValueSerializer<Value>
where
for<'a> &'a Value: IntoIterator,
Self: for<'a> CanSerializeValue<<&'a Value as IntoIterator>::Item>,
{ ... }
Both bounds hold for every lifetime of the borrow, because the item type depends on it. That is why
the requirement on the context is written in the where clause rather than with
#[uses].
Usage
Import it from cgp_serde::providers, and wire each collection type the context writes, beside the
generic reference entry for its items. From the messages example:
@ValueSerializerComponent.<'a, T> &'a T:
SerializeDeref,
@ValueSerializerComponent.[
Vec<EncryptedMessage>,
Vec<MessagesByTopic>,
]:
SerializeIterator,
Behavior
The provider starts a sequence, then writes each item that iterating &Value yields, wrapped with
the context in SerializeWithContext. With JSON, a Vec<u64>
or a BTreeSet<u64> becomes an array, and a nested vector whose inner type is also wired to
SerializeIterator becomes a nested array. The sequence is started without a declared length.
The items are what iterating by reference yields, which for a Vec<T>, a slice, or a set is &T.
That is why the context needs an entry for the reference, which the generic &'a T entry to
SerializeDeref provides. A map yields pairs of references, so a map is
written as a sequence of pairs, each pair written by the context's entry for the tuple type.
Context dependencies
CanSerializeValue<I> for each item type I the collection yields by reference, for every lifetime
of the borrow: usually the reference entry, and through it an entry for the item type.
Pairing
DeserializeExtend reads a sequence back into a collection.
When to use it
Reach for SerializeIterator for any collection whose items should follow the context's
choices. For a collection of types the application does not customize, such as a Vec<u64>,
UseSerde writes the same array without an entry per item type.
Related constructs
SerializeRecordFieldsis the matching provider for a struct.
The ideas behind it
- Re-entrant providers: handing each item to Serde with the context attached.
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.