Module serde_with::guide
source · Expand description
serde_with
User Guide
This crate provides helper functions to extend and change how serde
serializes different data types.
For example, you can serialize a map as a sequence of tuples, serialize using the Display
and FromStr
traits, or serialize an empty String
like None
.
serde_with
covers types from the Rust Standard Library and some common crates like chrono
.
A list of all supported transformations is available on this page.
The crate offers four types of functionality.
1. A more flexible and composable replacement for the with annotation, called serde_as
This is an alternative to serde’s with-annotation, which adds flexibility and composability to the scheme. The main downside is that it work with fewer types than with-annotations. However, all types from the Rust Standard Library should be supported in all combinations and any missing entry is a bug.
The serde_as
scheme is based on two new traits: SerializeAs
and DeserializeAs
.
Check out the detailed page about serde_as
and the available features.
Example
#[serde_as]
#[derive(Deserialize, Serialize)]
struct Data {
// Type does not implement Serialize or Deserialize
#[serde_as(as = "DisplayFromStr")]
address: Ipv4Addr,
// Treat the Vec like a map with duplicates
// Convert u32 into a String and keep the String the same type
#[serde_as(as = "Map<DisplayFromStr, _>")]
vec_as_map: Vec<(u32, String)>,
}
let data = Data {
address: Ipv4Addr::new(192, 168, 0, 1),
vec_as_map: vec![
(123, "Hello".into()),
(456, "World".into()),
(123, "Hello".into()),
],
};
let json = r#"{
"address": "192.168.0.1",
"vec_as_map": {
"123": "Hello",
"456": "World",
"123": "Hello"
}
}"#;
// Test Serialization
assert_eq!(json, serde_json::to_string_pretty(&data).unwrap());
// Test Deserialization
assert_eq!(data, serde_json::from_str(json).unwrap());
2. proc-macros to make it easier to use both above parts
The proc-macros are an optional addition and improve the user experience for common tasks.
We have already seen how the serde_as
attribute is used to define the serialization instructions.
The proc-macro attributes are defined in the serde_with_macros
crate and re-exported from the root of this crate.
The proc-macros are optional, but enabled by default.
For further details, please refer to the documentation of each proc-macro.
3. Derive macros to implement Deserialize
and Serialize
The derive macros work similar to the serde provided ones, but they do implement other de/serialization schemes.
For example, the derives DeserializeFromStr
and SerializeDisplay
require that the type also implement FromStr
and Display
and de/serializes from/to a string instead of the usual way of iterating over all fields.
Modules
- Available Feature Flags
serde_as
Annotation- De/Serialize Transformations Available