diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
tree | f435a8308119effd964b339f76abb83a57c29483 /third_party/rust/serde_with_macros/README.md | |
parent | Initial commit. (diff) | |
download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'third_party/rust/serde_with_macros/README.md')
-rw-r--r-- | third_party/rust/serde_with_macros/README.md | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/third_party/rust/serde_with_macros/README.md b/third_party/rust/serde_with_macros/README.md new file mode 100644 index 0000000000..fd5c446f37 --- /dev/null +++ b/third_party/rust/serde_with_macros/README.md @@ -0,0 +1,212 @@ +# Custom de/serialization functions for Rust's [serde](https://serde.rs) + +[![crates.io badge](https://img.shields.io/crates/v/serde_with.svg)](https://crates.io/crates/serde_with/) +[![Build Status](https://github.com/jonasbb/serde_with/workflows/Rust%20CI/badge.svg)](https://github.com/jonasbb/serde_with) +[![codecov](https://codecov.io/gh/jonasbb/serde_with/branch/master/graph/badge.svg)](https://codecov.io/gh/jonasbb/serde_with) +[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4322/badge)](https://bestpractices.coreinfrastructure.org/projects/4322) +[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust&logoColor=orange)](https://www.rustexplorer.com/b/py7ida) + +--- + +This crate provides custom de/serialization helpers to use in combination with [serde's with-annotation][with-annotation] and with the improved [`serde_as`][as-annotation]-annotation. +Some common use cases are: + +* De/Serializing a type using the `Display` and `FromStr` traits, e.g., for `u8`, `url::Url`, or `mime::Mime`. + Check [`DisplayFromStr`] for details. +* Support for arrays larger than 32 elements or using const generics. + With `serde_as` large arrays are supported, even if they are nested in other types. + `[bool; 64]`, `Option<[u8; M]>`, and `Box<[[u8; 64]; N]>` are all supported, as [this examples shows](#large-and-const-generic-arrays). +* Skip serializing all empty `Option` types with [`#[skip_serializing_none]`][skip_serializing_none]. +* Apply a prefix to each field name 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 a `Vec<String>`. + Check the documentation for [`serde_with::StringWithSeparator::<CommaSeparator, T>`][StringWithSeparator]. + +### Getting Help + +**Check out the [user guide][user guide] to find out more tips and tricks about this crate.** + +For further help using this crate you can [open a new discussion](https://github.com/jonasbb/serde_with/discussions/new) or ask on [users.rust-lang.org](https://users.rust-lang.org/). +For bugs, please open a [new issue](https://github.com/jonasbb/serde_with/issues/new) on GitHub. + +## Use `serde_with` in your Project + +```bash +# Add the current version to your Cargo.toml +cargo add serde_with +``` + +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. +The `#[serde_as]` attribute must be placed *before* the `#[derive]`. + +The `as` is analogous to the `with` attribute of serde. +You mirror the type structure of the field you want to de/serialize. +You can specify converters for the inner types of a field, e.g., `Vec<DisplayFromStr>`. +The default de/serialization behavior can be restored by using `_` as a placeholder, e.g., `BTreeMap<_, DisplayFromStr>`. + +### `DisplayFromStr` + +[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust&logoColor=orange)](https://www.rustexplorer.com/b/py7ida) +```rust +#[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"} +``` + +### Large and const-generic arrays + +serde does not support arrays with more than 32 elements or using const-generics. +The `serde_as` attribute allows circumventing this restriction, even for nested types and nested arrays. + +On top of it, `[u8; N]` (aka, bytes) can use the specialized `"Bytes"` for efficiency much like the `serde_bytes` crate. + +[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust&logoColor=orange)](https://www.rustexplorer.com/b/um0xyi) +```rust +#[serde_as] +#[derive(Deserialize, Serialize)] +struct Arrays<const N: usize, const M: usize> { + #[serde_as(as = "[_; N]")] + constgeneric: [bool; N], + + #[serde_as(as = "Box<[[_; 64]; N]>")] + nested: Box<[[u8; 64]; N]>, + + #[serde_as(as = "Option<[_; M]>")] + optional: Option<[u8; M]>, + + #[serde_as(as = "Bytes")] + bytes: [u8; M], +} + +// This allows us to serialize a struct like this +let arrays: Arrays<100, 128> = Arrays { + constgeneric: [true; 100], + nested: Box::new([[111; 64]; 100]), + optional: Some([222; 128]), + bytes: [0x42; 128], +}; +assert!(serde_json::to_string(&arrays).is_ok()); +``` + +### `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. +The `#[skip_serializing_none]` attribute must be placed *before* the `#[derive]`. + +[![Rustexplorer](https://img.shields.io/badge/Try%20on-rustexplorer-lightgrey?logo=rust&logoColor=orange)](https://www.rustexplorer.com/b/xr1tm0) +```rust +#[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][with-annotation]. +More details about `serde_as` can be found in the [user guide]. + +```rust +use std::time::Duration; + +#[serde_as] +#[derive(Deserialize, Serialize)] +enum Foo { + Durations( + // Serialize them into a list of number as seconds + #[serde_as(as = "Vec<DurationSeconds>")] + Vec<Duration>, + ), + Bytes { + // 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 = "Map<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)] +) +// into this JSON +{ + "Durations": [5, 3600, 0] +} + +// and serializes +Foo::Bytes { + bytes: vec![ + (1, vec![0, 1, 2]), + (-100, vec![100, 200, 255]), + (1, vec![0, 111, 222]), + ], +} +// into this JSON +{ + "Bytes": { + "bytes": { + "1": "000102", + "-100": "64c8ff", + "1": "006fde" + } + } +} +``` + +[`DisplayFromStr`]: https://docs.rs/serde_with/3.0.0/serde_with/struct.DisplayFromStr.html +[`with_prefix!`]: https://docs.rs/serde_with/3.0.0/serde_with/macro.with_prefix.html +[feature flags]: https://docs.rs/serde_with/3.0.0/serde_with/guide/feature_flags/index.html +[skip_serializing_none]: https://docs.rs/serde_with/3.0.0/serde_with/attr.skip_serializing_none.html +[StringWithSeparator]: https://docs.rs/serde_with/3.0.0/serde_with/struct.StringWithSeparator.html +[user guide]: https://docs.rs/serde_with/3.0.0/serde_with/guide/index.html +[with-annotation]: https://serde.rs/field-attrs.html#with +[as-annotation]: https://docs.rs/serde_with/3.0.0/serde_with/guide/serde_as/index.html + +## License + +Licensed under either of + +* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) +* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +## Contribution + +For detailed contribution instructions please read [`CONTRIBUTING.md`]. + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall +be dual licensed as above, without any additional terms or conditions. + +[`CONTRIBUTING.md`]: https://github.com/jonasbb/serde_with/blob/master/CONTRIBUTING.md |