Debian Codegraph @

.cargo/vendor/serde_json/src/lib.rs

raw
1 //! # Serde JSON
2 //!
3 //! JSON is a ubiquitous open-standard format that uses human-readable text to
4 //! transmit data objects consisting of key-value pairs.
5 //!
6 //! ```json
7 //! {
8 //! "name": "John Doe",
9 //! "age": 43,
10 //! "address": {
11 //! "street": "10 Downing Street",
12 //! "city": "London"
13 //! },
14 //! "phones": [
15 //! "+44 1234567",
16 //! "+44 2345678"
17 //! ]
18 //! }
19 //! ```
20 //!
21 //! There are three common ways that you might find yourself needing to work
22 //! with JSON data in Rust.
23 //!
24 //! - **As text data.** An unprocessed string of JSON data that you receive on
25 //! an HTTP endpoint, read from a file, or prepare to send to a remote
26 //! server.
27 //! - **As an untyped or loosely typed representation.** Maybe you want to
28 //! check that some JSON data is valid before passing it on, but without
29 //! knowing the structure of what it contains. Or you want to do very basic
30 //! manipulations like insert a key in a particular spot.
31 //! - **As a strongly typed Rust data structure.** When you expect all or most
32 //! of your data to conform to a particular structure and want to get real
33 //! work done without JSON's loosey-goosey nature tripping you up.
34 //!
35 //! Serde JSON provides efficient, flexible, safe ways of converting data
36 //! between each of these representations.
37 //!
38 //! # Operating on untyped JSON values
39 //!
40 //! Any valid JSON data can be manipulated in the following recursive enum
41 //! representation. This data structure is [`serde_json::Value`][value].
42 //!
43 //! ```
44 //! # use serde_json::{Number, Map};
45 //! #
46 //! # #[allow(dead_code)]
47 //! enum Value {
48 //! Null,
49 //! Bool(bool),
50 //! Number(Number),
51 //! String(String),
52 //! Array(Vec<Value>),
53 //! Object(Map<String, Value>),
54 //! }
55 //! ```
56 //!
57 //! A string of JSON data can be parsed into a `serde_json::Value` by the
58 //! [`serde_json::from_str`][from_str] function. There is also [`from_slice`]
59 //! for parsing from a byte slice `&[u8]` and [`from_reader`] for parsing from
60 //! any `io::Read` like a File or a TCP stream.
61 //!
62 //! ```
63 //! use serde_json::{Result, Value};
64 //!
65 //! fn untyped_example() -> Result<()> {
66 //! // Some JSON input data as a &str. Maybe this comes from the user.
67 //! let data = r#"
68 //! {
69 //! "name": "John Doe",
70 //! "age": 43,
71 //! "phones": [
72 //! "+44 1234567",
73 //! "+44 2345678"
74 //! ]
75 //! }"#;
76 //!
77 //! // Parse the string of data into serde_json::Value.
78 //! let v: Value = serde_json::from_str(data)?;
79 //!
80 //! // Access parts of the data by indexing with square brackets.
81 //! println!("Please call {} at the number {}", v["name"], v["phones"][0]);
82 //!
83 //! Ok(())
84 //! }
85 //! #
86 //! # fn main() {
87 //! # untyped_example().unwrap();
88 //! # }
89 //! ```
90 //!
91 //! The result of square bracket indexing like `v["name"]` is a borrow of the
92 //! data at that index, so the type is `&Value`. A JSON map can be indexed with
93 //! string keys, while a JSON array can be indexed with integer keys. If the
94 //! type of the data is not right for the type with which it is being indexed,
95 //! or if a map does not contain the key being indexed, or if the index into a
96 //! vector is out of bounds, the returned element is `Value::Null`.
97 //!
98 //! When a `Value` is printed, it is printed as a JSON string. So in the code
99 //! above, the output looks like `Please call "John Doe" at the number "+44
100 //! 1234567"`. The quotation marks appear because `v["name"]` is a `&Value`
101 //! containing a JSON string and its JSON representation is `"John Doe"`.
102 //! Printing as a plain string without quotation marks involves converting from
103 //! a JSON string to a Rust string with [`as_str()`] or avoiding the use of
104 //! `Value` as described in the following section.
105 //!
106 //! [`as_str()`]: crate::Value::as_str
107 //!
108 //! The `Value` representation is sufficient for very basic tasks but can be
109 //! tedious to work with for anything more significant. Error handling is
110 //! verbose to implement correctly, for example imagine trying to detect the
111 //! presence of unrecognized fields in the input data. The compiler is powerless
112 //! to help you when you make a mistake, for example imagine typoing `v["name"]`
113 //! as `v["nmae"]` in one of the dozens of places it is used in your code.
114 //!
115 //! # Parsing JSON as strongly typed data structures
116 //!
117 //! Serde provides a powerful way of mapping JSON data into Rust data structures
118 //! largely automatically.
119 //!
120 //! ```
121 //! use serde::{Deserialize, Serialize};
122 //! use serde_json::Result;
123 //!
124 //! #[derive(Serialize, Deserialize)]
125 //! struct Person {
126 //! name: String,
127 //! age: u8,
128 //! phones: Vec<String>,
129 //! }
130 //!
131 //! fn typed_example() -> Result<()> {
132 //! // Some JSON input data as a &str. Maybe this comes from the user.
133 //! let data = r#"
134 //! {
135 //! "name": "John Doe",
136 //! "age": 43,
137 //! "phones": [
138 //! "+44 1234567",
139 //! "+44 2345678"
140 //! ]
141 //! }"#;
142 //!
143 //! // Parse the string of data into a Person object. This is exactly the
144 //! // same function as the one that produced serde_json::Value above, but
145 //! // now we are asking it for a Person as output.
146 //! let p: Person = serde_json::from_str(data)?;
147 //!
148 //! // Do things just like with any other Rust data structure.
149 //! println!("Please call {} at the number {}", p.name, p.phones[0]);
150 //!
151 //! Ok(())
152 //! }
153 //! #
154 //! # fn main() {
155 //! # typed_example().unwrap();
156 //! # }
157 //! ```
158 //!
159 //! This is the same `serde_json::from_str` function as before, but this time we
160 //! assign the return value to a variable of type `Person` so Serde will
161 //! automatically interpret the input data as a `Person` and produce informative
162 //! error messages if the layout does not conform to what a `Person` is expected
163 //! to look like.
164 //!
165 //! Any type that implements Serde's `Deserialize` trait can be deserialized
166 //! this way. This includes built-in Rust standard library types like `Vec<T>`
167 //! and `HashMap<K, V>`, as well as any structs or enums annotated with
168 //! `#[derive(Deserialize)]`.
169 //!
170 //! Once we have `p` of type `Person`, our IDE and the Rust compiler can help us
171 //! use it correctly like they do for any other Rust code. The IDE can
172 //! autocomplete field names to prevent typos, which was impossible in the
173 //! `serde_json::Value` representation. And the Rust compiler can check that
174 //! when we write `p.phones[0]`, then `p.phones` is guaranteed to be a
175 //! `Vec<String>` so indexing into it makes sense and produces a `String`.
176 //!
177 //! # Constructing JSON values
178 //!
179 //! Serde JSON provides a [`json!` macro][macro] to build `serde_json::Value`
180 //! objects with very natural JSON syntax.
181 //!
182 //! ```
183 //! use serde_json::json;
184 //!
185 //! fn main() {
186 //! // The type of `john` is `serde_json::Value`
187 //! let john = json!({
188 //! "name": "John Doe",
189 //! "age": 43,
190 //! "phones": [
191 //! "+44 1234567",
192 //! "+44 2345678"
193 //! ]
194 //! });
195 //!
196 //! println!("first phone number: {}", john["phones"][0]);
197 //!
198 //! // Convert to a string of JSON and print it out
199 //! println!("{}", john.to_string());
200 //! }
201 //! ```
202 //!
203 //! The `Value::to_string()` function converts a `serde_json::Value` into a
204 //! `String` of JSON text.
205 //!
206 //! One neat thing about the `json!` macro is that variables and expressions can
207 //! be interpolated directly into the JSON value as you are building it. Serde
208 //! will check at compile time that the value you are interpolating is able to
209 //! be represented as JSON.
210 //!
211 //! ```
212 //! # use serde_json::json;
213 //! #
214 //! # fn random_phone() -> u16 { 0 }
215 //! #
216 //! let full_name = "John Doe";
217 //! let age_last_year = 42;
218 //!
219 //! // The type of `john` is `serde_json::Value`
220 //! let john = json!({
221 //! "name": full_name,
222 //! "age": age_last_year + 1,
223 //! "phones": [
224 //! format!("+44 {}", random_phone())
225 //! ]
226 //! });
227 //! ```
228 //!
229 //! This is amazingly convenient, but we have the problem we had before with
230 //! `Value`: the IDE and Rust compiler cannot help us if we get it wrong. Serde
231 //! JSON provides a better way of serializing strongly-typed data structures
232 //! into JSON text.
233 //!
234 //! # Creating JSON by serializing data structures
235 //!
236 //! A data structure can be converted to a JSON string by
237 //! [`serde_json::to_string`][to_string]. There is also
238 //! [`serde_json::to_vec`][to_vec] which serializes to a `Vec<u8>` and
239 //! [`serde_json::to_writer`][to_writer] which serializes to any `io::Write`
240 //! such as a File or a TCP stream.
241 //!
242 //! ```
243 //! use serde::{Deserialize, Serialize};
244 //! use serde_json::Result;
245 //!
246 //! #[derive(Serialize, Deserialize)]
247 //! struct Address {
248 //! street: String,
249 //! city: String,
250 //! }
251 //!
252 //! fn print_an_address() -> Result<()> {
253 //! // Some data structure.
254 //! let address = Address {
255 //! street: "10 Downing Street".to_owned(),
256 //! city: "London".to_owned(),
257 //! };
258 //!
259 //! // Serialize it to a JSON string.
260 //! let j = serde_json::to_string(&address)?;
261 //!
262 //! // Print, write to a file, or send to an HTTP server.
263 //! println!("{}", j);
264 //!
265 //! Ok(())
266 //! }
267 //! #
268 //! # fn main() {
269 //! # print_an_address().unwrap();
270 //! # }
271 //! ```
272 //!
273 //! Any type that implements Serde's `Serialize` trait can be serialized this
274 //! way. This includes built-in Rust standard library types like `Vec<T>` and
275 //! `HashMap<K, V>`, as well as any structs or enums annotated with
276 //! `#[derive(Serialize)]`.
277 //!
278 //! # No-std support
279 //!
280 //! As long as there is a memory allocator, it is possible to use serde_json
281 //! without the rest of the Rust standard library. Disable the default "std"
282 //! feature and enable the "alloc" feature:
283 //!
284 //! ```toml
285 //! [dependencies]
286 //! serde_json = { version = "1.0", default-features = false, features = ["alloc"] }
287 //! ```
288 //!
289 //! For JSON support in Serde without a memory allocator, please see the
290 //! [`serde-json-core`] crate.
291 //!
292 //! [value]: crate::value::Value
293 //! [from_str]: crate::de::from_str
294 //! [from_slice]: crate::de::from_slice
295 //! [from_reader]: crate::de::from_reader
296 //! [to_string]: crate::ser::to_string
297 //! [to_vec]: crate::ser::to_vec
298 //! [to_writer]: crate::ser::to_writer
299 //! [macro]: crate::json
300 //! [`serde-json-core`]: https://github.com/rust-embedded-community/serde-json-core
301
302 #![doc(html_root_url = "https://docs.rs/serde_json/1.0.116")]
303 // Ignored clippy lints
304 #![allow(
305 clippy::collapsible_else_if,
306 clippy::comparison_chain,
307 clippy::deprecated_cfg_attr,
308 clippy::doc_markdown,
309 clippy::excessive_precision,
310 clippy::explicit_auto_deref,
311 clippy::float_cmp,
312 clippy::manual_range_contains,
313 clippy::match_like_matches_macro,
314 clippy::match_single_binding,
315 clippy::needless_doctest_main,
316 clippy::needless_late_init,
317 clippy::return_self_not_must_use,
318 clippy::transmute_ptr_to_ptr,
319 clippy::unconditional_recursion, // https://github.com/rust-lang/rust-clippy/issues/12133
320 clippy::unnecessary_wraps
321 )]
322 // Ignored clippy_pedantic lints
323 #![allow(
324 // Deserializer::from_str, into_iter
325 clippy::should_implement_trait,
326 // integer and float ser/de requires these sorts of casts
327 clippy::cast_possible_truncation,
328 clippy::cast_possible_wrap,
329 clippy::cast_precision_loss,
330 clippy::cast_sign_loss,
331 // correctly used
332 clippy::enum_glob_use,
333 clippy::if_not_else,
334 clippy::integer_division,
335 clippy::let_underscore_untyped,
336 clippy::map_err_ignore,
337 clippy::match_same_arms,
338 clippy::similar_names,
339 clippy::unused_self,
340 clippy::wildcard_imports,
341 // things are often more readable this way
342 clippy::cast_lossless,
343 clippy::module_name_repetitions,
344 clippy::redundant_else,
345 clippy::shadow_unrelated,
346 clippy::single_match_else,
347 clippy::too_many_lines,
348 clippy::unreadable_literal,
349 clippy::unseparated_literal_suffix,
350 clippy::use_self,
351 clippy::zero_prefixed_literal,
352 // we support older compilers
353 clippy::checked_conversions,
354 clippy::mem_replace_with_default,
355 // noisy
356 clippy::missing_errors_doc,
357 clippy::must_use_candidate,
358 )]
359 // Restrictions
360 #![deny(clippy::question_mark_used)]
361 #![allow(non_upper_case_globals)]
362 #![deny(missing_docs)]
363 #![no_std]
364 #![cfg_attr(docsrs, feature(doc_cfg))]
365
366 #[cfg(not(any(feature = "std", feature = "alloc")))]
367 compile_error! {
368 "serde_json requires that either `std` (default) or `alloc` feature is enabled"
369 }
370
371 extern crate alloc;
372
373 #[cfg(feature = "std")]
374 extern crate std;
375
376 #[cfg(feature = "std")]
377 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
378 #[doc(inline)]
379 pub use crate::de::from_reader;
380 #[doc(inline)]
381 pub use crate::de::{from_slice, from_str, Deserializer, StreamDeserializer};
382 #[doc(inline)]
383 pub use crate::error::{Error, Result};
384 #[doc(inline)]
385 pub use crate::ser::{to_string, to_string_pretty, to_vec, to_vec_pretty};
386 #[cfg(feature = "std")]
387 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
388 #[doc(inline)]
389 pub use crate::ser::{to_writer, to_writer_pretty, Serializer};
390 #[doc(inline)]
391 pub use crate::value::{from_value, to_value, Map, Number, Value};
392
393 // We only use our own error type; no need for From conversions provided by the
394 // standard library's try! macro. This reduces lines of LLVM IR by 4%.
395 macro_rules! tri {
396 ($e:expr $(,)?) => {
397 match $e {
398 core::result::Result::Ok(val) => val,
399 core::result::Result::Err(err) => return core::result::Result::Err(err),
400 }
401 };
402 }
403
404 #[macro_use]
405 mod macros;
406
407 pub mod de;
408 pub mod error;
409 pub mod map;
410 #[cfg(feature = "std")]
411 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
412 pub mod ser;
413 #[cfg(not(feature = "std"))]
414 mod ser;
415 pub mod value;
416
417 mod io;
418 #[cfg(feature = "std")]
419 mod iter;
420 #[cfg(feature = "float_roundtrip")]
421 mod lexical;
422 mod number;
423 mod read;
424
425 #[cfg(feature = "raw_value")]
426 mod raw;