cgp-serde reference
This reference documents the public items of cgp-serde, one page per item. cgp-serde
rebuilds Serde's Serialize and Deserialize as components of
Context-Generic Programming (CGP), so most of its items are providers: implementations
a context, the type whose wiring holds an application's choices, names in its wiring table to
say how a type is encoded. The tables below list every provider by what it handles and what it asks
the context for, which is what a context must also wire.
New to CGP?
A provider page assumes the wiring that basic walks through. For CGP
itself, the Hello World tutorial introduces contexts, providers, and
wiring, and the site's reference documents the CGP constructs these pages link
to.
Serialization providers
Every provider below implements the serializing component, the deserializing one, or both, and is
imported from its crate's providers module, such as cgp_serde::providers::SerializeRecordFields.
The last column is what the provider asks the context to encode in turn; see re-entrant
providers.
| Provider | Crate | Direction | Handles | Asks the context for |
|---|---|---|---|---|
UseSerde | cgp-serde | both | any type with Serde's traits | nothing |
SerializeString | cgp-serde | both | writes any AsRef<str>; reads String | nothing |
SerializeBytes | cgp-serde | both | writes any AsRef<[u8]>; reads any From<&[u8]> | nothing |
TryDeserializeBytes | cgp-serde | reads | any TryFrom<&[u8]> | nothing |
SerializeWithDisplay | cgp-serde | writes | any Display type | String |
DeserializeWithFromStr | cgp-serde | reads | any FromStr type | &str |
SerializeFrom | cgp-serde | both | a type converted with Into | the converted type |
TrySerializeFrom | cgp-serde | both | a type converted with TryInto | the converted type |
SerializeDeref | cgp-serde | writes | a reference or smart pointer | the value it points to |
SerializeIterator | cgp-serde | writes | a collection iterable by reference | each item it yields |
DeserializeExtend | cgp-serde | reads | a collection that can be extended | each item |
SerializeRecordFields | cgp-serde | writes | a struct with named fields | each field's type |
DeserializeRecordFields | cgp-serde | reads | a struct with named fields | each field's type |
SerializeVariantFields | cgp-serde | writes | an enum whose variants hold one value or none, without a lifetime | each variant's value type, Nil for a variant with no fields |
DeserializeVariantFields | cgp-serde | reads | an enum whose variants hold one value or none | each variant's value type, Nil for a variant with no fields |
SerializeUnit | cgp-serde | both | writes any type as a unit; reads any Default type from one | nothing |
DeserializeDefault | cgp-serde | reads | a Default type that may be null | nothing; wraps another provider |
SerializeHex | cgp-serde-extra | both | bytes, as hex | String |
SerializeBase64 | cgp-serde-extra | both | bytes, as base64 | String |
SerializeRfc3339Date | cgp-serde-extra | both | DateTime<Utc>, as an RFC 3339 string | String |
SerializeTimestamp | cgp-serde-extra | both | DateTime<Utc>, as a Unix timestamp | i64 |
DeserializeAndAllocate | cgp-serde-alloc | reads | a reference, allocated through the context | the owned value, and an allocator |
JSON and allocation providers
Four more providers implement other components. The JSON providers make writing and reading JSON an operation the context runs, and the arena provider implements allocation:
| Provider | Crate | What it does | Asks the context for |
|---|---|---|---|
SerializeToJsonString | cgp-serde-json | writes a value as a compact JSON string | the value's serializer, and an error type |
DeserializeFromJsonReader | cgp-serde-json | reads a value from any serde_json reader | the value's deserializer, and an error type |
DeserializeFromJsonString | cgp-serde-json | reads a value from a string | what its inner provider asks for |
AllocateWithArena | cgp-serde-typed-arena | allocates into an arena held by the context | the arena |
Types and components
SerializeWithContext— pairs a context with a value as a SerdeSerializevalue, the way into any Serde format.DeserializeWithContext— pairs a context with a target type as a SerdeDeserializeSeed.CanDeserializeJsonString— gives a context adeserialize_json_stringmethod.CanAlloc— the component a deserializer allocates through.
The pages for the two serialization components, CanSerializeValue<Value> and
CanDeserializeValue<'de, Value>, and for the arena getter HasArena, are still being written. The
component design page explains the two components, and
AllocateWithArena shows the arena getter in use.
Looking for a name you don't see?
Some names belong to a construct documented under another name:
| Name | Where it is documented |
|---|---|
ValueSerializer, ValueSerializerComponent | the provider trait and wiring key of CanSerializeValue; see component design |
ValueDeserializer, ValueDeserializerComponent | the provider trait and wiring key of CanDeserializeValue; see component design |
SerializeJson, DeserializeJson | the marker types that select the JSON operations; see SerializeToJsonString and DeserializeFromJsonReader |
Allocator, AllocatorComponent | the provider trait and wiring key of CanAlloc |
ArenaGetter, ArenaGetterComponent | the provider trait and wiring key of HasArena; see AllocateWithArena |
deserialize_json_string | the method of CanDeserializeJsonString |
Where to go next
- Wiring a context: choosing providers for a context's table.
- Writing a provider: adding a provider of your own.
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.