vendor/erased-serde-0.4.5/README.md

Erased Serde
============

[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/erased--serde-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/erased-serde)
[<img alt="crates.io" src="https://img.shields.io/crates/v/erased-serde.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/erased-serde)
[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-erased--serde-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/erased-serde)
[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/erased-serde/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/erased-serde/actions?query=branch%3Amaster)

This crate provides type-erased versions of Serde's `Serialize`, `Serializer`
and `Deserializer` traits that can be used as [trait objects].

[trait objects]: https://doc.rust-lang.org/book/first-edition/trait-objects.html

- [`erased_serde::Serialize`](https://docs.rs/erased-serde/0.4/erased_serde/trait.Serialize.html)
- [`erased_serde::Serializer`](https://docs.rs/erased-serde/0.4/erased_serde/trait.Serializer.html)
- [`erased_serde::Deserializer`](https://docs.rs/erased-serde/0.4/erased_serde/trait.Deserializer.html)

The usual Serde `Serialize`, `Serializer` and `Deserializer` traits cannot be
used as trait objects like `&dyn Serialize` or boxed trait objects like
`Box<dyn Serialize>` because of Rust's ["object safety" rules]. In particular,
all three traits contain generic methods which cannot be made into a trait
object.

["object safety" rules]: http://huonw.github.io/blog/2015/01/object-safety/

This library should be considered a low-level building block for interacting
with Serde APIs in an object-safe way. Most use cases will require higher level
functionality such as provided by [`typetag`] which uses this crate internally.

[`typetag`]: https://github.com/dtolnay/typetag

**The traits in this crate work seamlessly with any existing Serde `Serialize`
and `Deserialize` type and any existing Serde `Serializer` and `Deserializer`
format.**

```toml
[dependencies]
serde = "1.0"
erased-serde = "0.4"
```

## Serialization

```rust
use erased_serde::{Serialize, Serializer};
use std::collections::BTreeMap as Map;
use std::io;

fn main() {
    // Construct some serializers.
    let json = &mut serde_json::Serializer::new(io::stdout());
    let cbor = &mut serde_cbor::Serializer::new(serde_cbor::ser::IoWrite::new(io::stdout()));

    // The values in this map are boxed trait objects. Ordinarily this would not
    // be possible with serde::Serializer because of object safety, but type
    // erasure makes it possible with erased_serde::Serializer.
    let mut formats: Map<&str, Box<dyn Serializer>> = Map::new();
    formats.insert("json", Box::new(<dyn Serializer>::erase(json)));
    formats.insert("cbor", Box::new(<dyn Serializer>::erase(cbor)));

    // These are boxed trait objects as well. Same thing here - type erasure
    // makes this possible.
    let mut values: Map<&str, Box<dyn Serialize>> = Map::new();
    values.insert("vec", Box::new(vec!["a", "b"]));
    values.insert("int", Box::new(65536));

    // Pick a Serializer out of the formats map.
    let format = formats.get_mut("json").unwrap();

    // Pick a Serialize out of the values map.
    let value = values.get("vec").unwrap();

    // This line prints `["a","b"]` to stdout.
    value.erased_serialize(format).unwrap();
}
```

## Deserialization

```rust
use erased_serde::Deserializer;
use std::collections::BTreeMap as Map;

fn main() {
    static JSON: &[u8] = br#"{"A": 65, "B": 66}"#;
    static CBOR: &[u8] = &[162, 97, 65, 24, 65, 97, 66, 24, 66];

    // Construct some deserializers.
    let json = &mut serde_json::Deserializer::from_slice(JSON);
    let cbor = &mut serde_cbor::Deserializer::from_slice(CBOR);

    // The values in this map are boxed trait objects, which is not possible
    // with the normal serde::Deserializer because of object safety.
    let mut formats: Map<&str, Box<dyn Deserializer>> = Map::new();
    formats.insert("json", Box::new(<dyn Deserializer>::erase(json)));
    formats.insert("cbor", Box::new(<dyn Deserializer>::erase(cbor)));

    // Pick a Deserializer out of the formats map.
    let format = formats.get_mut("json").unwrap();

    let data: Map<String, usize> = erased_serde::deserialize(format).unwrap();

    println!("{}", data["A"] + data["B"]);
}
```

## How it works

This crate is based on a general technique for building trait objects of traits
that have generic methods (like all of Serde's traits). [This example code]
demonstrates the technique applied to a simplified case of a single generic
method. [Try it in the playground.]

[This example code]: https://github.com/dtolnay/erased-serde/blob/master/explanation/main.rs
[Try it in the playground.]: https://play.rust-lang.org/?gist=c1111875e7462ba3d0190aacb2fc2211

In erased-serde things are a bit more complicated than in the example for three
reasons but the idea is the same.

- We need to deal with trait methods that take `self` by value -- effectively by
  implementing the object-safe trait for `Option<T>` where `T` implements the
  real trait.
- We need to deal with traits that have associated types like `Serializer::Ok`
  and `Visitor::Value` -- by carefully short-term stashing things behind a
  pointer.
- We need to support trait methods that have a generic type in the return type
  but none of the argument types, like `SeqAccess::next_element` -- this can be
  flipped around into a callback style where the return value is instead passed
  on to a generic argument.

In the future maybe the Rust compiler will be able to apply this technique
automatically to any trait that is not already object safe by the current rules.

<br>

#### License

<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>

<br>

<sub>
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.
</sub>