https://github.com/rnag/serde-this-or-that
Custom deserialization for fields that can be specified as multiple types.
https://github.com/rnag/serde-this-or-that
crates deserialization json multiple-type rust serde this-or-that untagged visitor-pattern
Last synced: 6 months ago
JSON representation
Custom deserialization for fields that can be specified as multiple types.
- Host: GitHub
- URL: https://github.com/rnag/serde-this-or-that
- Owner: rnag
- License: mit
- Created: 2022-04-16T15:06:01.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-25T05:32:14.000Z (8 months ago)
- Last Synced: 2025-04-10T01:12:49.948Z (6 months ago)
- Topics: crates, deserialization, json, multiple-type, rust, serde, this-or-that, untagged, visitor-pattern
- Language: Rust
- Homepage: https://docs.rs/serde-this-or-that
- Size: 115 KB
- Stars: 19
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# serde-this-or-that
[
](https://github.com/rnag/serde-this-or-that)
[
](https://crates.io/crates/serde-this-or-that)
[
](https://docs.rs/serde-this-or-that)
[
](https://github.com/rnag/serde-this-or-that/actions?query=branch%3Amain)
Custom deserialization for fields that can be specified as multiple types.
---
This crate works with Cargo with a `Cargo.toml` like:
```toml
[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:
```rust
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,
}
fn main() -> Result<(), Box> {
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
- [`as_bool`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_bool.html) / [
`as_opt_bool`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_opt_bool.html)
- [`as_f64`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_f64.html) / [
`as_opt_f64`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_opt_f64.html)
- [`as_i64`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_i64.html) / [
`as_opt_i64`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_opt_i64.html)
- [`as_string`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_string.html) / [
`as_opt_string`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_opt_string.html)
- [`as_u64`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_u64.html) / [
`as_opt_u64`](https://docs.rs/serde-this-or-that/latest/serde_this_or_that/fn.as_opt_u64.html)
## Examples
You can check out sample usage of this crate in
the [examples/](https://github.com/rnag/serde-this-or-that/tree/main/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/](https://github.com/rnag/serde-this-or-that/tree/main/benches)
folder, and can be run with `cargo bench`.
[`Visitor`]: https://docs.serde.rs/serde/de/trait.Visitor.html
[untagged enum]: https://stackoverflow.com/a/66961340/10237506
[serde_with]: https://docs.rs/serde_with
[`DisplayFromStr`]: https://docs.rs/serde_with/latest/serde_with/struct.DisplayFromStr.html
[`PickFirst`]: https://docs.rs/serde_with/latest/serde_with/struct.PickFirst.html
## Optionals
The extra helper functions that begin with `as_opt`, return an `Option` of the respective data type `T`,
rather than the type `T` itself (see [#4](https://github.com/rnag/serde-this-or-that/issues/4)).
On success, they return a value of `T` wrapped in [
`Some`](https://doc.rust-lang.org/std/option/enum.Option.html#variant.Some).
On error, or when there is a `null` value, or one of an *invalid* data type, the
`as_opt` helper functions return [`None`](https://doc.rust-lang.org/std/option/enum.Option.html#variant.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.
[Contributing]: CONTRIBUTING.md
[open an issue]: https://github.com/rnag/serde-this-or-that/issues
## License
This project is proudly licensed under the MIT license ([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
* [Ritvik Nag](https://github.com/rnag)