#deserialize #serde-json #deserialize-json #serde #visitor #multiple-type

serde-this-or-that

Custom deserialization for fields that can be specified as multiple types

9 unstable releases

0.5.0 Jan 25, 2025
0.4.2 Feb 6, 2023
0.4.0 Apr 18, 2022
0.3.1 Apr 17, 2022
0.1.1 Apr 16, 2022

#122 in Encoding

Download history 3767/week @ 2024-11-17 3327/week @ 2024-11-24 3521/week @ 2024-12-01 3988/week @ 2024-12-08 4017/week @ 2024-12-15 2789/week @ 2024-12-22 1917/week @ 2024-12-29 4673/week @ 2025-01-05 4785/week @ 2025-01-12 4415/week @ 2025-01-19 4639/week @ 2025-01-26 6261/week @ 2025-02-02 5160/week @ 2025-02-09 4937/week @ 2025-02-16 5141/week @ 2025-02-23 2601/week @ 2025-03-02

18,156 downloads per month
Used in 17 crates (11 directly)

MIT license

59KB
1K SLoC

serde-this-or-that

github crates.io docs.rs build status

Custom deserialization for fields that can be specified as multiple types.


This crate works with Cargo with a Cargo.toml like:

[dependencies]
serde-this-or-that = "0.5.0"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Getting started

Add some usage to your application.

Here's an example of using serde-this-or-that in code:

use serde::Deserialize;
use serde_json::from_str;
use serde_this_or_that::{as_bool, as_f64, as_opt_i64, as_u64};

#[derive(Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
struct MyStruct {
    #[serde(deserialize_with = "as_bool")]
    is_active: bool,
    #[serde(deserialize_with = "as_u64")]
    num_attempts: u64,
    #[serde(deserialize_with = "as_f64")]
    grade: f64,
    // uses #[serde(default)] in case the field is missing in JSON
    #[serde(default, deserialize_with = "as_opt_i64")]
    confidence: Option<i64>,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let string = r#"
    {
        "isActive": "True",
        "numAttempts": "",
        "grade": "81",
        "confidence": "A+"
    }
    "#;

    let s: MyStruct = from_str(string)?;
    println!("{s:#?}");

    assert!(s.is_active);
    assert_eq!(s.num_attempts, 0);
    assert_eq!(s.grade, 81.0);
    assert_eq!(s.confidence, None);

    Ok(())
}

Exported Functions

Examples

You can check out sample usage of this crate in the examples/ folder in the project repo on GitHub.

Performance

The benchmarks suggest that implementing a custom Visitor as serde-this-or-that does, performs on average about 15x better than an approach with an untagged enum.

A separate benchmark compares performance against the serde_with crate: it indicates both crates perform about the same, assuming only DisplayFromStr is used. But when PickFirst is involved, serde-this-or-that appears to perform about 12x better in an average case.

The benchmarks live in the benches/ folder, and can be run with cargo bench.

Optionals

The extra helper functions that begin with as_opt, return an Option<T> of the respective data type T, rather than the type T itself (see #4).

On success, they return a value of T wrapped in Some.

On error, or when there is a null value, or one of an invalid data type, the as_opt helper functions return None instead.

Contributing

Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature or change.

Check out the Contributing section in the docs for more info.

License

This project is proudly licensed under the MIT license (LICENSE or http://opensource.org/licenses/MIT).

serde-this-or-that can be distributed according to the MIT license. Contributions will be accepted under the same license.

Authors

Dependencies

~99–320KB