Yi Kong | e94f392 | 2020-08-31 01:24:17 +0800 | [diff] [blame^] | 1 | # Serde   [![Build Status]][actions] [![Latest Version]][crates.io] [![serde: rustc 1.13+]][Rust 1.13] [![serde_derive: rustc 1.31+]][Rust 1.31] |
| 2 | |
| 3 | [Build Status]: https://img.shields.io/github/workflow/status/serde-rs/serde/CI/master |
| 4 | [actions]: https://github.com/serde-rs/serde/actions?query=branch%3Amaster |
| 5 | [Latest Version]: https://img.shields.io/crates/v/serde.svg |
| 6 | [crates.io]: https://crates.io/crates/serde |
| 7 | [serde: rustc 1.13+]: https://img.shields.io/badge/serde-rustc_1.13+-lightgray.svg |
| 8 | [serde_derive: rustc 1.31+]: https://img.shields.io/badge/serde_derive-rustc_1.31+-lightgray.svg |
| 9 | [Rust 1.13]: https://blog.rust-lang.org/2016/11/10/Rust-1.13.html |
| 10 | [Rust 1.31]: https://blog.rust-lang.org/2018/12/06/Rust-1.31-and-rust-2018.html |
| 11 | |
| 12 | **Serde is a framework for *ser*ializing and *de*serializing Rust data structures efficiently and generically.** |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | You may be looking for: |
| 17 | |
| 18 | - [An overview of Serde](https://serde.rs/) |
| 19 | - [Data formats supported by Serde](https://serde.rs/#data-formats) |
| 20 | - [Setting up `#[derive(Serialize, Deserialize)]`](https://serde.rs/derive.html) |
| 21 | - [Examples](https://serde.rs/examples.html) |
| 22 | - [API documentation](https://docs.serde.rs/serde/) |
| 23 | - [Release notes](https://github.com/serde-rs/serde/releases) |
| 24 | |
| 25 | ## Serde in action |
| 26 | |
| 27 | <details> |
| 28 | <summary> |
| 29 | Click to show Cargo.toml. |
| 30 | <a href="https://play.rust-lang.org/?edition=2018&gist=72755f28f99afc95e01d63174b28c1f5" target="_blank">Run this code in the playground.</a> |
| 31 | </summary> |
| 32 | |
| 33 | ```toml |
| 34 | [dependencies] |
| 35 | |
| 36 | # The core APIs, including the Serialize and Deserialize traits. Always |
| 37 | # required when using Serde. The "derive" feature is only required when |
| 38 | # using #[derive(Serialize, Deserialize)] to make Serde work with structs |
| 39 | # and enums defined in your crate. |
| 40 | serde = { version = "1.0", features = ["derive"] } |
| 41 | |
| 42 | # Each data format lives in its own crate; the sample code below uses JSON |
| 43 | # but you may be using a different one. |
| 44 | serde_json = "1.0" |
| 45 | ``` |
| 46 | |
| 47 | </details> |
| 48 | <p></p> |
| 49 | |
| 50 | ```rust |
| 51 | use serde::{Serialize, Deserialize}; |
| 52 | |
| 53 | #[derive(Serialize, Deserialize, Debug)] |
| 54 | struct Point { |
| 55 | x: i32, |
| 56 | y: i32, |
| 57 | } |
| 58 | |
| 59 | fn main() { |
| 60 | let point = Point { x: 1, y: 2 }; |
| 61 | |
| 62 | // Convert the Point to a JSON string. |
| 63 | let serialized = serde_json::to_string(&point).unwrap(); |
| 64 | |
| 65 | // Prints serialized = {"x":1,"y":2} |
| 66 | println!("serialized = {}", serialized); |
| 67 | |
| 68 | // Convert the JSON string back to a Point. |
| 69 | let deserialized: Point = serde_json::from_str(&serialized).unwrap(); |
| 70 | |
| 71 | // Prints deserialized = Point { x: 1, y: 2 } |
| 72 | println!("deserialized = {:?}", deserialized); |
| 73 | } |
| 74 | ``` |
| 75 | |
| 76 | ## Getting help |
| 77 | |
| 78 | Serde is one of the most widely used Rust libraries so any place that Rustaceans |
| 79 | congregate will be able to help you out. For chat, consider trying the |
| 80 | [#general] or [#beginners] channels of the unofficial community Discord, the |
| 81 | [#rust-usage] channel of the official Rust Project Discord, or the |
| 82 | [#general][zulip] stream in Zulip. For asynchronous, consider the [\[rust\] tag |
| 83 | on StackOverflow][stackoverflow], the [/r/rust] subreddit which has a pinned |
| 84 | weekly easy questions post, or the Rust [Discourse forum][discourse]. It's |
| 85 | acceptable to file a support issue in this repo but they tend not to get as many |
| 86 | eyes as any of the above and may get closed without a response after some time. |
| 87 | |
| 88 | [#general]: https://discord.com/channels/273534239310479360/274215136414400513 |
| 89 | [#beginners]: https://discord.com/channels/273534239310479360/273541522815713281 |
| 90 | [#rust-usage]: https://discord.com/channels/442252698964721669/443150878111694848 |
| 91 | [zulip]: https://rust-lang.zulipchat.com/#narrow/stream/122651-general |
| 92 | [stackoverflow]: https://stackoverflow.com/questions/tagged/rust |
| 93 | [/r/rust]: https://www.reddit.com/r/rust |
| 94 | [discourse]: https://users.rust-lang.org |
| 95 | |
| 96 | <br> |
| 97 | |
| 98 | #### License |
| 99 | |
| 100 | <sup> |
| 101 | Licensed under either of <a href="LICENSE-APACHE">Apache License, Version |
| 102 | 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. |
| 103 | </sup> |
| 104 | |
| 105 | <br> |
| 106 | |
| 107 | <sub> |
| 108 | Unless you explicitly state otherwise, any contribution intentionally submitted |
| 109 | for inclusion in Serde by you, as defined in the Apache-2.0 license, shall be |
| 110 | dual licensed as above, without any additional terms or conditions. |
| 111 | </sub> |