[][src]Crate serde_with

docs.rs badge crates.io badge Build Status codecov


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:

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.1"
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 DeserializeAs implementations

formats

Specify the format and how lenient the deserialization is

guide

serde_with User Guide

hex
json

De/Serialization of JSON

rust

De/Serialization for Rust's builtin and std types

ser

Module for SerializeAs implementations

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
BytesOrString
CommaSeparator

Predefined separator using a single comma

DefaultOnError
DisplayFromStr
DurationSeconds
DurationSecondsWithFrac
NoneAsEmptyString
Same
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 Deserialize.

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 Serialize.

Attribute Macros

serde_as

Conveniece macro to use the serde_as system.

skip_serializing_none

Add skip_serializing_if annotations to Option fields.