Skip to main content

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.

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.