[−][src]Crate serde_with
This crate provides custom de/serialization helpers to use in combination with serde's with-annotation and with the improved serde_as
-annotation.
Some common use cases are:
- De/Serializing a type using the
Display
andFromStr
traits, e.g., foru8
,url::Url
, ormime::Mime
. CheckDisplayFromStr
orserde_with::rust::display_fromstr
for details. - Skip serializing all empty
Option
types with#[skip_serializing_none]
. - Apply a prefix to each fieldname of a struct, without changing the de/serialize implementations of the struct using
with_prefix!
. - Deserialize a comma separated list like
#hash,#tags,#are,#great
into aVec<String>
. Check the documentation forserde_with::rust::StringWithSeparator::<CommaSeparator>
.
Check out the user guide to find out more tips and tricks about this crate.
Use serde_with
in your Project
Add this to your Cargo.toml
:
[dependencies.serde_with]
version = "1.5.0-alpha.2"
features = [ "..." ]
The crate contains different features for integration with other common crates. Check the feature flags section for information about all available features.
Examples
Annotate your struct or enum to enable the custom de/serializer.
DisplayFromStr
#[serde_as] #[derive(Deserialize, Serialize)] struct Foo { // Serialize with Display, deserialize with FromStr #[serde_as(as = "DisplayFromStr")] bar: u8, } // This will serialize Foo {bar: 12} // into this JSON {"bar": "12"}
skip_serializing_none
This situation often occurs with JSON, but other formats also support optional fields. If many fields are optional, putting the annotations on the structs can become tedious.
#[skip_serializing_none] #[derive(Deserialize, Serialize)] struct Foo { a: Option<usize>, b: Option<usize>, c: Option<usize>, d: Option<usize>, e: Option<usize>, f: Option<usize>, g: Option<usize>, } // This will serialize Foo {a: None, b: None, c: None, d: Some(4), e: None, f: None, g: Some(7)} // into this JSON {"d": 4, "g": 7}
Advanced serde_as
usage
This example is mainly supposed to highlight the flexibility of the serde_as
-annotation compared to serde's with-annotation.
More details about serde_as
can be found in the user guide.
#[serde_as] #[derive(Deserialize, Serialize)] struct Foo { // Serialize them into a list of number as seconds #[serde_as(as = "Vec<DurationSeconds>")] durations: Vec<Duration>, // We can treat a Vec like a map with duplicates. // JSON only allows string keys, so convert i32 to strings // The bytes will be hex encoded #[serde_as(as = "BTreeMap<DisplayFromStr, Hex>")] bytes: Vec<(i32, Vec<u8>)>, } // This will serialize Foo { durations: vec![Duration::new(5, 0), Duration::new(3600, 0), Duration::new(0, 0)], bytes: vec![ (1, vec![0, 1, 2]), (-100, vec![100, 200, 255]), (1, vec![0, 111, 222]), ], } // into this JSON { "durations": [5, 3600, 0], "bytes": { "1": "000102", "-100": "64c8ff", "1": "006fde" } }
Modules
chrono | De/Serialization of chrono types |
de | Module for |
formats | Specify the format and how lenient the deserialization is |
guide |
|
hex | De/Serialization of hexadecimal encoded bytes |
json | De/Serialization of JSON |
rust | De/Serialization for Rust's builtin and std types |
ser | Module for |
Macros
flattened_maybe | Support deserializing from flattened and non-flattened representation |
with_prefix | Serialize with an added prefix on every field name and deserialize by trimming away the prefix. |
Structs
As | Adapter to convert from |
BytesOrString | Deserialize from bytes or string |
CommaSeparator | Predefined separator using a single comma |
DefaultOnError | Deserialize value and return |
DisplayFromStr | |
DurationSeconds | De/Serialize Durations as seconds since the UNIX epoch |
DurationSecondsWithFrac | De/Serialize Durations as seconds since the UNIX epoch |
NoneAsEmptyString | De/Serialize a |
Same | Adapter to convert from |
SpaceSeparator | Predefined separator using a single space |
Traits
DeserializeAs | A data structure that can be deserialized from any data format supported by Serde, analoge to |
Separator | Separator for string-based collection de/serialization |
SerializeAs | A data structure that can be serialized into any data format supported by Serde, analoge to |
Attribute Macros
serde_as | Conveniece macro to use the |
skip_serializing_none | Add |
Derive Macros
DeserializeFromStr | Deserialize value by using it's |
SerializeDisplay | Serialize value by using it's |