serde

To use Serde, add the serde crate to your Cargo.toml. To use the #[derive(Serialize, Deserialize)] macros on your structs and enums, you must enable the derive feature.

Note that Serde itself provides the core traits, but data formats (like JSON, YAML, etc.) live in separate crates. For example, to work with JSON, you must also include serde_json.

[dependencies]
# The core APIs, including the Serialize and Deserialize traits. Always
# required when using Serde. The "derive" feature is only required when
# using #[derive(Serialize, Deserialize)] to make Serde work with structs
# and enums defined in your crate.
serde = { version = "1.0", features = ["derive"] }

# Each data format lives in its own crate; the sample code below uses JSON
# but you may be using a different one.
serde_json = "1.0"

When deciding which crate to depend on, follow these guidelines based on your use case:

1. If you need to use #[derive(Serialize, Deserialize)]: You must depend on the serde crate. The serde_core crate does not support the derive() functionality.

2. If you are handwriting trait implementations or using trait bounds: You can depend on serde_core. However, since serde re-exports all traits from serde_core, it is generally recommended to use serde to avoid confusion.

3. If you want to optimize build times: Depending on serde_core instead of serde allows your crate to compile in parallel with serde_derive (even when serde's "derive" feature is enabled).

The IntoDeserializer trait allows you to convert basic Rust types directly into deserializers. This is useful for implementing FromStr or other conversion traits where you want to leverage Serde's existing Deserialize implementations for your types.

Example of implementing FromStr for a custom enum using IntoDeserializer:

use serde::de::{value, Deserialize, IntoDeserializer};
use serde_derive::Deserialize;
use std::str::FromStr;

#[derive(Deserialize)]
enum Setting {
    On,
    Off,
}

impl FromStr for Setting {
    type Err = value::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::deserialize(s.into_deserializer())
    }
}

When working with Serde, you must choose the correct crate based on your use case:

• Use serde if you want to use #[derive(Serialize, Deserialize)] on your structs and enums. This is the standard choice for most users.
• Use serde_core only if you are hand-writing custom implementations of Serde traits or using them strictly as trait bounds. serde_core contains the core trait definitions but does not support the #[derive] macros.

Note: If you attempt to use Serde's derive macros while depending only on serde_core, the compilation will fail with a compile error.

You can use Serde to convert Rust data structures to and from various data formats. By deriving Serialize and Deserialize, your types become compatible with any Serde-supported format.

In this example, we use serde_json to convert a Point struct to a JSON string and back again.

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point = Point { x: 1, y: 2 };

    // Convert the Point to a JSON string.
    let serialized = serde_json::to_string(&point).unwrap();

    // Prints serialized = {"x":1,"y":2}
    println!("serialized = {}", serialized);

    // Convert the JSON string back to a Point.
    let deserialized: Point = serde_json::from_str(&serialized).unwrap();

    // Prints deserialized = Point { x: 1, y: 2 }
    println!("deserialized = {:?}", deserialized);
}

Use the Serialize and Deserialize procedural macros to automatically implement Serde's serialization and deserialization traits for your structs and enums. These macros support custom configuration via #[serde] attributes.

To use them, you typically need to include serde_derive in your dependencies and use the #[derive(...)] syntax on your data types.

use serde_derive::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct S;

fn main() {}