@@ -42,22 +42,21 @@ transmit data objects consisting of key-value pairs.
42
42
}
43
43
```
44
44
45
- There are three common ways that you might find yourself needing to work
46
- with JSON data in Rust.
47
-
48
- - ** As text data.** An unprocessed string of JSON data that you receive on
49
- an HTTP endpoint, read from a file, or prepare to send to a remote
50
- server.
51
- - ** As an untyped or loosely typed representation.** Maybe you want to
52
- check that some JSON data is valid before passing it on, but without
53
- knowing the structure of what it contains. Or you want to do very basic
54
- manipulations like insert a key in a particular spot.
55
- - ** As a strongly typed Rust data structure.** When you expect all or most
56
- of your data to conform to a particular structure and want to get real
57
- work done without JSON's loosey-goosey nature tripping you up.
58
-
59
- Serde JSON provides efficient, flexible, safe ways of converting data
60
- between each of these representations.
45
+ There are three common ways that you might find yourself needing to work with
46
+ JSON data in Rust.
47
+
48
+ - ** As text data.** An unprocessed string of JSON data that you receive on an
49
+ HTTP endpoint, read from a file, or prepare to send to a remote server.
50
+ - ** As an untyped or loosely typed representation.** Maybe you want to check
51
+ that some JSON data is valid before passing it on, but without knowing the
52
+ structure of what it contains. Or you want to do very basic manipulations
53
+ like insert a key in a particular spot.
54
+ - ** As a strongly typed Rust data structure.** When you expect all or most of
55
+ your data to conform to a particular structure and want to get real work done
56
+ without JSON's loosey-goosey nature tripping you up.
57
+
58
+ Serde JSON provides efficient, flexible, safe ways of converting data between
59
+ each of these representations.
61
60
62
61
## Operating on untyped JSON values
63
62
@@ -78,8 +77,8 @@ enum Value {
78
77
A string of JSON data can be parsed into a ` serde_json::Value ` by the
79
78
[ ` serde_json::from_str ` ] [ from_str ] function. There is also
80
79
[ ` from_slice ` ] [ from_slice ] for parsing from a byte slice &[ u8] and
81
- [ ` from_reader ` ] [ from_reader ] for parsing from any ` io::Read ` like a File or
82
- a TCP stream.
80
+ [ ` from_reader ` ] [ from_reader ] for parsing from any ` io::Read ` like a File or a
81
+ TCP stream.
83
82
84
83
<div align =" right " >
85
84
<a href =" https://play.rust-lang.org/?edition=2018&gist=d69d8e3156d4bb81c4461b60b772ab72 " target =" _blank " >
@@ -185,20 +184,20 @@ fn typed_example() -> Result<()> {
185
184
This is the same ` serde_json::from_str ` function as before, but this time we
186
185
assign the return value to a variable of type ` Person ` so Serde will
187
186
automatically interpret the input data as a ` Person ` and produce informative
188
- error messages if the layout does not conform to what a ` Person ` is expected
189
- to look like.
187
+ error messages if the layout does not conform to what a ` Person ` is expected to
188
+ look like.
190
189
191
- Any type that implements Serde's ` Deserialize ` trait can be deserialized
192
- this way. This includes built-in Rust standard library types like ` Vec<T> `
193
- and ` HashMap<K, V> ` , as well as any structs or enums annotated with
190
+ Any type that implements Serde's ` Deserialize ` trait can be deserialized this
191
+ way. This includes built-in Rust standard library types like ` Vec<T> ` and
192
+ ` HashMap<K, V> ` , as well as any structs or enums annotated with
194
193
` #[derive(Deserialize)] ` .
195
194
196
- Once we have ` p ` of type ` Person ` , our IDE and the Rust compiler can help us
197
- use it correctly like they do for any other Rust code. The IDE can
198
- autocomplete field names to prevent typos, which was impossible in the
199
- ` serde_json::Value ` representation. And the Rust compiler can check that
200
- when we write ` p.phones[0] ` , then ` p.phones ` is guaranteed to be a
201
- ` Vec<String> ` so indexing into it makes sense and produces a ` String ` .
195
+ Once we have ` p ` of type ` Person ` , our IDE and the Rust compiler can help us use
196
+ it correctly like they do for any other Rust code. The IDE can autocomplete
197
+ field names to prevent typos, which was impossible in the ` serde_json::Value `
198
+ representation. And the Rust compiler can check that when we write
199
+ ` p.phones[0] ` , then ` p.phones ` is guaranteed to be a ` Vec<String> ` so indexing
200
+ into it makes sense and produces a ` String ` .
202
201
203
202
The necessary setup for using Serde's derive macros is explained on the * [ Using
204
203
derive] * page of the Serde site.
@@ -237,13 +236,13 @@ fn main() {
237
236
}
238
237
```
239
238
240
- The ` Value::to_string() ` function converts a ` serde_json::Value ` into a
241
- ` String ` of JSON text.
239
+ The ` Value::to_string() ` function converts a ` serde_json::Value ` into a ` String `
240
+ of JSON text.
242
241
243
- One neat thing about the ` json! ` macro is that variables and expressions can
244
- be interpolated directly into the JSON value as you are building it. Serde
245
- will check at compile time that the value you are interpolating is able to
246
- be represented as JSON.
242
+ One neat thing about the ` json! ` macro is that variables and expressions can be
243
+ interpolated directly into the JSON value as you are building it. Serde will
244
+ check at compile time that the value you are interpolating is able to be
245
+ represented as JSON.
247
246
248
247
<div align =" right " >
249
248
<a href =" https://play.rust-lang.org/?edition=2018&gist=f9101a6e61dfc9e02c6a67f315ed24f2 " target =" _blank " >
@@ -266,9 +265,9 @@ let john = json!({
266
265
```
267
266
268
267
This is amazingly convenient, but we have the problem we had before with
269
- ` Value ` : the IDE and Rust compiler cannot help us if we get it
270
- wrong. Serde JSON provides a better way of serializing strongly-typed data
271
- structures into JSON text.
268
+ ` Value ` : the IDE and Rust compiler cannot help us if we get it wrong. Serde JSON
269
+ provides a better way of serializing strongly-typed data structures into JSON
270
+ text.
272
271
273
272
## Creating JSON by serializing data structures
274
273
@@ -311,10 +310,9 @@ fn print_an_address() -> Result<()> {
311
310
}
312
311
```
313
312
314
- Any type that implements Serde's ` Serialize ` trait can be serialized this
315
- way. This includes built-in Rust standard library types like ` Vec<T> ` and
316
- ` HashMap<K, V> ` , as well as any structs or enums annotated with
317
- ` #[derive(Serialize)] ` .
313
+ Any type that implements Serde's ` Serialize ` trait can be serialized this way.
314
+ This includes built-in Rust standard library types like ` Vec<T> ` and `HashMap<K,
315
+ V>` , as well as any structs or enums annotated with ` #[ derive(Serialize)] `.
318
316
319
317
## Performance
320
318
@@ -328,9 +326,9 @@ Benchmarks live in the [serde-rs/json-benchmark] repo.
328
326
329
327
## Getting help
330
328
331
- Serde is one of the most widely used Rust libraries, so any place that Rustaceans
332
- congregate will be able to help you out. For chat, consider trying the
333
- [ #rust-questions] or [ #rust-beginners] channels of the unofficial community
329
+ Serde is one of the most widely used Rust libraries, so any place that
330
+ Rustaceans congregate will be able to help you out. For chat, consider trying
331
+ the [ #rust-questions] or [ #rust-beginners] channels of the unofficial community
334
332
Discord (invite: < https://discord.gg/rust-lang-community > ), the [ #rust-usage] or
335
333
[ #beginners] channels of the official Rust Project Discord (invite:
336
334
< https://discord.gg/rust-lang > ), or the [ #general] [ zulip ] stream in Zulip. For
0 commit comments