serde_json/value/mod.rs
1//! The Value enum, a loosely typed way of representing any valid JSON value.
2//!
3//! # Constructing JSON
4//!
5//! Serde JSON provides a [`json!` macro][macro] to build `serde_json::Value`
6//! objects with very natural JSON syntax.
7//!
8//! ```edition2018
9//! use serde_json::json;
10//!
11//! fn main() {
12//! // The type of `john` is `serde_json::Value`
13//! let john = json!({
14//! "name": "John Doe",
15//! "age": 43,
16//! "phones": [
17//! "+44 1234567",
18//! "+44 2345678"
19//! ]
20//! });
21//!
22//! println!("first phone number: {}", john["phones"][0]);
23//!
24//! // Convert to a string of JSON and print it out
25//! println!("{}", john.to_string());
26//! }
27//! ```
28//!
29//! The `Value::to_string()` function converts a `serde_json::Value` into a
30//! `String` of JSON text.
31//!
32//! One neat thing about the `json!` macro is that variables and expressions can
33//! be interpolated directly into the JSON value as you are building it. Serde
34//! will check at compile time that the value you are interpolating is able to
35//! be represented as JSON.
36//!
37//! ```edition2018
38//! # use serde_json::json;
39//! #
40//! # fn random_phone() -> u16 { 0 }
41//! #
42//! let full_name = "John Doe";
43//! let age_last_year = 42;
44//!
45//! // The type of `john` is `serde_json::Value`
46//! let john = json!({
47//! "name": full_name,
48//! "age": age_last_year + 1,
49//! "phones": [
50//! format!("+44 {}", random_phone())
51//! ]
52//! });
53//! ```
54//!
55//! A string of JSON data can be parsed into a `serde_json::Value` by the
56//! [`serde_json::from_str`][from_str] function. There is also
57//! [`from_slice`][from_slice] for parsing from a byte slice `&[u8]` and
58//! [`from_reader`][from_reader] for parsing from any `io::Read` like a File or
59//! a TCP stream.
60//!
61//! ```edition2018
62//! use serde_json::{json, Value, Error};
63//!
64//! fn untyped_example() -> Result<(), Error> {
65//! // Some JSON input data as a &str. Maybe this comes from the user.
66//! let data = r#"
67//! {
68//! "name": "John Doe",
69//! "age": 43,
70//! "phones": [
71//! "+44 1234567",
72//! "+44 2345678"
73//! ]
74//! }"#;
75//!
76//! // Parse the string of data into serde_json::Value.
77//! let v: Value = serde_json::from_str(data)?;
78//!
79//! // Access parts of the data by indexing with square brackets.
80//! println!("Please call {} at the number {}", v["name"], v["phones"][0]);
81//!
82//! Ok(())
83//! }
84//! #
85//! # untyped_example().unwrap();
86//! ```
87//!
88//! [macro]: https://docs.serde.rs/serde_json/macro.json.html
89//! [from_str]: https://docs.serde.rs/serde_json/de/fn.from_str.html
90//! [from_slice]: https://docs.serde.rs/serde_json/de/fn.from_slice.html
91//! [from_reader]: https://docs.serde.rs/serde_json/de/fn.from_reader.html
92
93use std::fmt::{self, Debug};
94use std::io;
95use std::mem;
96use std::str;
97
98use serde::de::DeserializeOwned;
99use serde::ser::Serialize;
100
101use error::Error;
102pub use map::Map;
103pub use number::Number;
104
105#[cfg(feature = "raw_value")]
106pub use raw::RawValue;
107
108pub use self::index::Index;
109
110use self::ser::Serializer;
111
112/// Represents any valid JSON value.
113///
114/// See the `serde_json::value` module documentation for usage examples.
115#[derive(Clone, PartialEq)]
116pub enum Value {
117 /// Represents a JSON null value.
118 ///
119 /// ```edition2018
120 /// # use serde_json::json;
121 /// #
122 /// let v = json!(null);
123 /// ```
124 Null,
125
126 /// Represents a JSON boolean.
127 ///
128 /// ```edition2018
129 /// # use serde_json::json;
130 /// #
131 /// let v = json!(true);
132 /// ```
133 Bool(bool),
134
135 /// Represents a JSON number, whether integer or floating point.
136 ///
137 /// ```edition2018
138 /// # use serde_json::json;
139 /// #
140 /// let v = json!(12.5);
141 /// ```
142 Number(Number),
143
144 /// Represents a JSON string.
145 ///
146 /// ```edition2018
147 /// # use serde_json::json;
148 /// #
149 /// let v = json!("a string");
150 /// ```
151 String(String),
152
153 /// Represents a JSON array.
154 ///
155 /// ```edition2018
156 /// # use serde_json::json;
157 /// #
158 /// let v = json!(["an", "array"]);
159 /// ```
160 Array(Vec<Value>),
161
162 /// Represents a JSON object.
163 ///
164 /// By default the map is backed by a BTreeMap. Enable the `preserve_order`
165 /// feature of serde_json to use IndexMap instead, which preserves
166 /// entries in the order they are inserted into the map. In particular, this
167 /// allows JSON data to be deserialized into a Value and serialized to a
168 /// string while retaining the order of map keys in the input.
169 ///
170 /// ```edition2018
171 /// # use serde_json::json;
172 /// #
173 /// let v = json!({ "an": "object" });
174 /// ```
175 Object(Map<String, Value>),
176}
177
178impl Debug for Value {
179 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
180 match *self {
181 Value::Null => formatter.debug_tuple("Null").finish(),
182 Value::Bool(v) => formatter.debug_tuple("Bool").field(&v).finish(),
183 Value::Number(ref v) => Debug::fmt(v, formatter),
184 Value::String(ref v) => formatter.debug_tuple("String").field(v).finish(),
185 Value::Array(ref v) => formatter.debug_tuple("Array").field(v).finish(),
186 Value::Object(ref v) => formatter.debug_tuple("Object").field(v).finish(),
187 }
188 }
189}
190
191struct WriterFormatter<'a, 'b: 'a> {
192 inner: &'a mut fmt::Formatter<'b>,
193}
194
195impl<'a, 'b> io::Write for WriterFormatter<'a, 'b> {
196 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
197 fn io_error<E>(_: E) -> io::Error {
198 // Error value does not matter because fmt::Display impl below just
199 // maps it to fmt::Error
200 io::Error::new(io::ErrorKind::Other, "fmt error")
201 }
202 let s = try!(str::from_utf8(buf).map_err(io_error));
203 try!(self.inner.write_str(s).map_err(io_error));
204 Ok(buf.len())
205 }
206
207 fn flush(&mut self) -> io::Result<()> {
208 Ok(())
209 }
210}
211
212impl fmt::Display for Value {
213 /// Display a JSON value as a string.
214 ///
215 /// ```edition2018
216 /// # use serde_json::json;
217 /// #
218 /// let json = json!({ "city": "London", "street": "10 Downing Street" });
219 ///
220 /// // Compact format:
221 /// //
222 /// // {"city":"London","street":"10 Downing Street"}
223 /// let compact = format!("{}", json);
224 /// assert_eq!(compact,
225 /// "{\"city\":\"London\",\"street\":\"10 Downing Street\"}");
226 ///
227 /// // Pretty format:
228 /// //
229 /// // {
230 /// // "city": "London",
231 /// // "street": "10 Downing Street"
232 /// // }
233 /// let pretty = format!("{:#}", json);
234 /// assert_eq!(pretty,
235 /// "{\n \"city\": \"London\",\n \"street\": \"10 Downing Street\"\n}");
236 /// ```
237 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
238 let alternate = f.alternate();
239 let mut wr = WriterFormatter { inner: f };
240 if alternate {
241 // {:#}
242 super::ser::to_writer_pretty(&mut wr, self).map_err(|_| fmt::Error)
243 } else {
244 // {}
245 super::ser::to_writer(&mut wr, self).map_err(|_| fmt::Error)
246 }
247 }
248}
249
250fn parse_index(s: &str) -> Option<usize> {
251 if s.starts_with('+') || (s.starts_with('0') && s.len() != 1) {
252 return None;
253 }
254 s.parse().ok()
255}
256
257impl Value {
258 /// Index into a JSON array or map. A string index can be used to access a
259 /// value in a map, and a usize index can be used to access an element of an
260 /// array.
261 ///
262 /// Returns `None` if the type of `self` does not match the type of the
263 /// index, for example if the index is a string and `self` is an array or a
264 /// number. Also returns `None` if the given key does not exist in the map
265 /// or the given index is not within the bounds of the array.
266 ///
267 /// ```edition2018
268 /// # use serde_json::json;
269 /// #
270 /// let object = json!({ "A": 65, "B": 66, "C": 67 });
271 /// assert_eq!(*object.get("A").unwrap(), json!(65));
272 ///
273 /// let array = json!([ "A", "B", "C" ]);
274 /// assert_eq!(*array.get(2).unwrap(), json!("C"));
275 ///
276 /// assert_eq!(array.get("A"), None);
277 /// ```
278 ///
279 /// Square brackets can also be used to index into a value in a more concise
280 /// way. This returns `Value::Null` in cases where `get` would have returned
281 /// `None`.
282 ///
283 /// ```edition2018
284 /// # use serde_json::json;
285 /// #
286 /// let object = json!({
287 /// "A": ["a", "á", "à"],
288 /// "B": ["b", "b́"],
289 /// "C": ["c", "ć", "ć̣", "ḉ"],
290 /// });
291 /// assert_eq!(object["B"][0], json!("b"));
292 ///
293 /// assert_eq!(object["D"], json!(null));
294 /// assert_eq!(object[0]["x"]["y"]["z"], json!(null));
295 /// ```
296 pub fn get<I: Index>(&self, index: I) -> Option<&Value> {
297 index.index_into(self)
298 }
299
300 /// Mutably index into a JSON array or map. A string index can be used to
301 /// access a value in a map, and a usize index can be used to access an
302 /// element of an array.
303 ///
304 /// Returns `None` if the type of `self` does not match the type of the
305 /// index, for example if the index is a string and `self` is an array or a
306 /// number. Also returns `None` if the given key does not exist in the map
307 /// or the given index is not within the bounds of the array.
308 ///
309 /// ```edition2018
310 /// # use serde_json::json;
311 /// #
312 /// let mut object = json!({ "A": 65, "B": 66, "C": 67 });
313 /// *object.get_mut("A").unwrap() = json!(69);
314 ///
315 /// let mut array = json!([ "A", "B", "C" ]);
316 /// *array.get_mut(2).unwrap() = json!("D");
317 /// ```
318 pub fn get_mut<I: Index>(&mut self, index: I) -> Option<&mut Value> {
319 index.index_into_mut(self)
320 }
321
322 /// Returns true if the `Value` is an Object. Returns false otherwise.
323 ///
324 /// For any Value on which `is_object` returns true, `as_object` and
325 /// `as_object_mut` are guaranteed to return the map representation of the
326 /// object.
327 ///
328 /// ```edition2018
329 /// # use serde_json::json;
330 /// #
331 /// let obj = json!({ "a": { "nested": true }, "b": ["an", "array"] });
332 ///
333 /// assert!(obj.is_object());
334 /// assert!(obj["a"].is_object());
335 ///
336 /// // array, not an object
337 /// assert!(!obj["b"].is_object());
338 /// ```
339 pub fn is_object(&self) -> bool {
340 self.as_object().is_some()
341 }
342
343 /// If the `Value` is an Object, returns the associated Map. Returns None
344 /// otherwise.
345 ///
346 /// ```edition2018
347 /// # use serde_json::json;
348 /// #
349 /// let v = json!({ "a": { "nested": true }, "b": ["an", "array"] });
350 ///
351 /// // The length of `{"nested": true}` is 1 entry.
352 /// assert_eq!(v["a"].as_object().unwrap().len(), 1);
353 ///
354 /// // The array `["an", "array"]` is not an object.
355 /// assert_eq!(v["b"].as_object(), None);
356 /// ```
357 pub fn as_object(&self) -> Option<&Map<String, Value>> {
358 match *self {
359 Value::Object(ref map) => Some(map),
360 _ => None,
361 }
362 }
363
364 /// If the `Value` is an Object, returns the associated mutable Map.
365 /// Returns None otherwise.
366 ///
367 /// ```edition2018
368 /// # use serde_json::json;
369 /// #
370 /// let mut v = json!({ "a": { "nested": true } });
371 ///
372 /// v["a"].as_object_mut().unwrap().clear();
373 /// assert_eq!(v, json!({ "a": {} }));
374 /// ```
375 pub fn as_object_mut(&mut self) -> Option<&mut Map<String, Value>> {
376 match *self {
377 Value::Object(ref mut map) => Some(map),
378 _ => None,
379 }
380 }
381
382 /// Returns true if the `Value` is an Array. Returns false otherwise.
383 ///
384 /// For any Value on which `is_array` returns true, `as_array` and
385 /// `as_array_mut` are guaranteed to return the vector representing the
386 /// array.
387 ///
388 /// ```edition2018
389 /// # use serde_json::json;
390 /// #
391 /// let obj = json!({ "a": ["an", "array"], "b": { "an": "object" } });
392 ///
393 /// assert!(obj["a"].is_array());
394 ///
395 /// // an object, not an array
396 /// assert!(!obj["b"].is_array());
397 /// ```
398 pub fn is_array(&self) -> bool {
399 self.as_array().is_some()
400 }
401
402 /// If the `Value` is an Array, returns the associated vector. Returns None
403 /// otherwise.
404 ///
405 /// ```edition2018
406 /// # use serde_json::json;
407 /// #
408 /// let v = json!({ "a": ["an", "array"], "b": { "an": "object" } });
409 ///
410 /// // The length of `["an", "array"]` is 2 elements.
411 /// assert_eq!(v["a"].as_array().unwrap().len(), 2);
412 ///
413 /// // The object `{"an": "object"}` is not an array.
414 /// assert_eq!(v["b"].as_array(), None);
415 /// ```
416 pub fn as_array(&self) -> Option<&Vec<Value>> {
417 match *self {
418 Value::Array(ref array) => Some(&*array),
419 _ => None,
420 }
421 }
422
423 /// If the `Value` is an Array, returns the associated mutable vector.
424 /// Returns None otherwise.
425 ///
426 /// ```edition2018
427 /// # use serde_json::json;
428 /// #
429 /// let mut v = json!({ "a": ["an", "array"] });
430 ///
431 /// v["a"].as_array_mut().unwrap().clear();
432 /// assert_eq!(v, json!({ "a": [] }));
433 /// ```
434 pub fn as_array_mut(&mut self) -> Option<&mut Vec<Value>> {
435 match *self {
436 Value::Array(ref mut list) => Some(list),
437 _ => None,
438 }
439 }
440
441 /// Returns true if the `Value` is a String. Returns false otherwise.
442 ///
443 /// For any Value on which `is_string` returns true, `as_str` is guaranteed
444 /// to return the string slice.
445 ///
446 /// ```edition2018
447 /// # use serde_json::json;
448 /// #
449 /// let v = json!({ "a": "some string", "b": false });
450 ///
451 /// assert!(v["a"].is_string());
452 ///
453 /// // The boolean `false` is not a string.
454 /// assert!(!v["b"].is_string());
455 /// ```
456 pub fn is_string(&self) -> bool {
457 self.as_str().is_some()
458 }
459
460 /// If the `Value` is a String, returns the associated str. Returns None
461 /// otherwise.
462 ///
463 /// ```edition2018
464 /// # use serde_json::json;
465 /// #
466 /// let v = json!({ "a": "some string", "b": false });
467 ///
468 /// assert_eq!(v["a"].as_str(), Some("some string"));
469 ///
470 /// // The boolean `false` is not a string.
471 /// assert_eq!(v["b"].as_str(), None);
472 ///
473 /// // JSON values are printed in JSON representation, so strings are in quotes.
474 /// //
475 /// // The value is: "some string"
476 /// println!("The value is: {}", v["a"]);
477 ///
478 /// // Rust strings are printed without quotes.
479 /// //
480 /// // The value is: some string
481 /// println!("The value is: {}", v["a"].as_str().unwrap());
482 /// ```
483 pub fn as_str(&self) -> Option<&str> {
484 match *self {
485 Value::String(ref s) => Some(s),
486 _ => None,
487 }
488 }
489
490 /// Returns true if the `Value` is a Number. Returns false otherwise.
491 ///
492 /// ```edition2018
493 /// # use serde_json::json;
494 /// #
495 /// let v = json!({ "a": 1, "b": "2" });
496 ///
497 /// assert!(v["a"].is_number());
498 ///
499 /// // The string `"2"` is a string, not a number.
500 /// assert!(!v["b"].is_number());
501 /// ```
502 pub fn is_number(&self) -> bool {
503 match *self {
504 Value::Number(_) => true,
505 _ => false,
506 }
507 }
508
509 /// Returns true if the `Value` is an integer between `i64::MIN` and
510 /// `i64::MAX`.
511 ///
512 /// For any Value on which `is_i64` returns true, `as_i64` is guaranteed to
513 /// return the integer value.
514 ///
515 /// ```edition2018
516 /// # use serde_json::json;
517 /// #
518 /// let big = i64::max_value() as u64 + 10;
519 /// let v = json!({ "a": 64, "b": big, "c": 256.0 });
520 ///
521 /// assert!(v["a"].is_i64());
522 ///
523 /// // Greater than i64::MAX.
524 /// assert!(!v["b"].is_i64());
525 ///
526 /// // Numbers with a decimal point are not considered integers.
527 /// assert!(!v["c"].is_i64());
528 /// ```
529 pub fn is_i64(&self) -> bool {
530 match *self {
531 Value::Number(ref n) => n.is_i64(),
532 _ => false,
533 }
534 }
535
536 /// Returns true if the `Value` is an integer between zero and `u64::MAX`.
537 ///
538 /// For any Value on which `is_u64` returns true, `as_u64` is guaranteed to
539 /// return the integer value.
540 ///
541 /// ```edition2018
542 /// # use serde_json::json;
543 /// #
544 /// let v = json!({ "a": 64, "b": -64, "c": 256.0 });
545 ///
546 /// assert!(v["a"].is_u64());
547 ///
548 /// // Negative integer.
549 /// assert!(!v["b"].is_u64());
550 ///
551 /// // Numbers with a decimal point are not considered integers.
552 /// assert!(!v["c"].is_u64());
553 /// ```
554 pub fn is_u64(&self) -> bool {
555 match *self {
556 Value::Number(ref n) => n.is_u64(),
557 _ => false,
558 }
559 }
560
561 /// Returns true if the `Value` is a number that can be represented by f64.
562 ///
563 /// For any Value on which `is_f64` returns true, `as_f64` is guaranteed to
564 /// return the floating point value.
565 ///
566 /// Currently this function returns true if and only if both `is_i64` and
567 /// `is_u64` return false but this is not a guarantee in the future.
568 ///
569 /// ```edition2018
570 /// # use serde_json::json;
571 /// #
572 /// let v = json!({ "a": 256.0, "b": 64, "c": -64 });
573 ///
574 /// assert!(v["a"].is_f64());
575 ///
576 /// // Integers.
577 /// assert!(!v["b"].is_f64());
578 /// assert!(!v["c"].is_f64());
579 /// ```
580 pub fn is_f64(&self) -> bool {
581 match *self {
582 Value::Number(ref n) => n.is_f64(),
583 _ => false,
584 }
585 }
586
587 /// If the `Value` is an integer, represent it as i64 if possible. Returns
588 /// None otherwise.
589 ///
590 /// ```edition2018
591 /// # use serde_json::json;
592 /// #
593 /// let big = i64::max_value() as u64 + 10;
594 /// let v = json!({ "a": 64, "b": big, "c": 256.0 });
595 ///
596 /// assert_eq!(v["a"].as_i64(), Some(64));
597 /// assert_eq!(v["b"].as_i64(), None);
598 /// assert_eq!(v["c"].as_i64(), None);
599 /// ```
600 pub fn as_i64(&self) -> Option<i64> {
601 match *self {
602 Value::Number(ref n) => n.as_i64(),
603 _ => None,
604 }
605 }
606
607 /// If the `Value` is an integer, represent it as u64 if possible. Returns
608 /// None otherwise.
609 ///
610 /// ```edition2018
611 /// # use serde_json::json;
612 /// #
613 /// let v = json!({ "a": 64, "b": -64, "c": 256.0 });
614 ///
615 /// assert_eq!(v["a"].as_u64(), Some(64));
616 /// assert_eq!(v["b"].as_u64(), None);
617 /// assert_eq!(v["c"].as_u64(), None);
618 /// ```
619 pub fn as_u64(&self) -> Option<u64> {
620 match *self {
621 Value::Number(ref n) => n.as_u64(),
622 _ => None,
623 }
624 }
625
626 /// If the `Value` is a number, represent it as f64 if possible. Returns
627 /// None otherwise.
628 ///
629 /// ```edition2018
630 /// # use serde_json::json;
631 /// #
632 /// let v = json!({ "a": 256.0, "b": 64, "c": -64 });
633 ///
634 /// assert_eq!(v["a"].as_f64(), Some(256.0));
635 /// assert_eq!(v["b"].as_f64(), Some(64.0));
636 /// assert_eq!(v["c"].as_f64(), Some(-64.0));
637 /// ```
638 pub fn as_f64(&self) -> Option<f64> {
639 match *self {
640 Value::Number(ref n) => n.as_f64(),
641 _ => None,
642 }
643 }
644
645 /// Returns true if the `Value` is a Boolean. Returns false otherwise.
646 ///
647 /// For any Value on which `is_boolean` returns true, `as_bool` is
648 /// guaranteed to return the boolean value.
649 ///
650 /// ```edition2018
651 /// # use serde_json::json;
652 /// #
653 /// let v = json!({ "a": false, "b": "false" });
654 ///
655 /// assert!(v["a"].is_boolean());
656 ///
657 /// // The string `"false"` is a string, not a boolean.
658 /// assert!(!v["b"].is_boolean());
659 /// ```
660 pub fn is_boolean(&self) -> bool {
661 self.as_bool().is_some()
662 }
663
664 /// If the `Value` is a Boolean, returns the associated bool. Returns None
665 /// otherwise.
666 ///
667 /// ```edition2018
668 /// # use serde_json::json;
669 /// #
670 /// let v = json!({ "a": false, "b": "false" });
671 ///
672 /// assert_eq!(v["a"].as_bool(), Some(false));
673 ///
674 /// // The string `"false"` is a string, not a boolean.
675 /// assert_eq!(v["b"].as_bool(), None);
676 /// ```
677 pub fn as_bool(&self) -> Option<bool> {
678 match *self {
679 Value::Bool(b) => Some(b),
680 _ => None,
681 }
682 }
683
684 /// Returns true if the `Value` is a Null. Returns false otherwise.
685 ///
686 /// For any Value on which `is_null` returns true, `as_null` is guaranteed
687 /// to return `Some(())`.
688 ///
689 /// ```edition2018
690 /// # use serde_json::json;
691 /// #
692 /// let v = json!({ "a": null, "b": false });
693 ///
694 /// assert!(v["a"].is_null());
695 ///
696 /// // The boolean `false` is not null.
697 /// assert!(!v["b"].is_null());
698 /// ```
699 pub fn is_null(&self) -> bool {
700 self.as_null().is_some()
701 }
702
703 /// If the `Value` is a Null, returns (). Returns None otherwise.
704 ///
705 /// ```edition2018
706 /// # use serde_json::json;
707 /// #
708 /// let v = json!({ "a": null, "b": false });
709 ///
710 /// assert_eq!(v["a"].as_null(), Some(()));
711 ///
712 /// // The boolean `false` is not null.
713 /// assert_eq!(v["b"].as_null(), None);
714 /// ```
715 pub fn as_null(&self) -> Option<()> {
716 match *self {
717 Value::Null => Some(()),
718 _ => None,
719 }
720 }
721
722 /// Looks up a value by a JSON Pointer.
723 ///
724 /// JSON Pointer defines a string syntax for identifying a specific value
725 /// within a JavaScript Object Notation (JSON) document.
726 ///
727 /// A Pointer is a Unicode string with the reference tokens separated by `/`.
728 /// Inside tokens `/` is replaced by `~1` and `~` is replaced by `~0`. The
729 /// addressed value is returned and if there is no such value `None` is
730 /// returned.
731 ///
732 /// For more information read [RFC6901](https://tools.ietf.org/html/rfc6901).
733 ///
734 /// # Examples
735 ///
736 /// ```edition2018
737 /// # use serde_json::json;
738 /// #
739 /// let data = json!({
740 /// "x": {
741 /// "y": ["z", "zz"]
742 /// }
743 /// });
744 ///
745 /// assert_eq!(data.pointer("/x/y/1").unwrap(), &json!("zz"));
746 /// assert_eq!(data.pointer("/a/b/c"), None);
747 /// ```
748 pub fn pointer<'a>(&'a self, pointer: &str) -> Option<&'a Value> {
749 if pointer == "" {
750 return Some(self);
751 }
752 if !pointer.starts_with('/') {
753 return None;
754 }
755 let tokens = pointer
756 .split('/')
757 .skip(1)
758 .map(|x| x.replace("~1", "/").replace("~0", "~"));
759 let mut target = self;
760
761 for token in tokens {
762 let target_opt = match *target {
763 Value::Object(ref map) => map.get(&token),
764 Value::Array(ref list) => parse_index(&token).and_then(|x| list.get(x)),
765 _ => return None,
766 };
767 if let Some(t) = target_opt {
768 target = t;
769 } else {
770 return None;
771 }
772 }
773 Some(target)
774 }
775
776 /// Looks up a value by a JSON Pointer and returns a mutable reference to
777 /// that value.
778 ///
779 /// JSON Pointer defines a string syntax for identifying a specific value
780 /// within a JavaScript Object Notation (JSON) document.
781 ///
782 /// A Pointer is a Unicode string with the reference tokens separated by `/`.
783 /// Inside tokens `/` is replaced by `~1` and `~` is replaced by `~0`. The
784 /// addressed value is returned and if there is no such value `None` is
785 /// returned.
786 ///
787 /// For more information read [RFC6901](https://tools.ietf.org/html/rfc6901).
788 ///
789 /// # Example of Use
790 ///
791 /// ```edition2018
792 /// use serde_json::Value;
793 ///
794 /// fn main() {
795 /// let s = r#"{"x": 1.0, "y": 2.0}"#;
796 /// let mut value: Value = serde_json::from_str(s).unwrap();
797 ///
798 /// // Check value using read-only pointer
799 /// assert_eq!(value.pointer("/x"), Some(&1.0.into()));
800 /// // Change value with direct assignment
801 /// *value.pointer_mut("/x").unwrap() = 1.5.into();
802 /// // Check that new value was written
803 /// assert_eq!(value.pointer("/x"), Some(&1.5.into()));
804 ///
805 /// // "Steal" ownership of a value. Can replace with any valid Value.
806 /// let old_x = value.pointer_mut("/x").map(Value::take).unwrap();
807 /// assert_eq!(old_x, 1.5);
808 /// assert_eq!(value.pointer("/x").unwrap(), &Value::Null);
809 /// }
810 /// ```
811 pub fn pointer_mut<'a>(&'a mut self, pointer: &str) -> Option<&'a mut Value> {
812 if pointer == "" {
813 return Some(self);
814 }
815 if !pointer.starts_with('/') {
816 return None;
817 }
818 let tokens = pointer
819 .split('/')
820 .skip(1)
821 .map(|x| x.replace("~1", "/").replace("~0", "~"));
822 let mut target = self;
823
824 for token in tokens {
825 // borrow checker gets confused about `target` being mutably borrowed too many times because of the loop
826 // this once-per-loop binding makes the scope clearer and circumvents the error
827 let target_once = target;
828 let target_opt = match *target_once {
829 Value::Object(ref mut map) => map.get_mut(&token),
830 Value::Array(ref mut list) => {
831 parse_index(&token).and_then(move |x| list.get_mut(x))
832 }
833 _ => return None,
834 };
835 if let Some(t) = target_opt {
836 target = t;
837 } else {
838 return None;
839 }
840 }
841 Some(target)
842 }
843
844 /// Takes the value out of the `Value`, leaving a `Null` in its place.
845 ///
846 /// ```edition2018
847 /// # use serde_json::json;
848 /// #
849 /// let mut v = json!({ "x": "y" });
850 /// assert_eq!(v["x"].take(), json!("y"));
851 /// assert_eq!(v, json!({ "x": null }));
852 /// ```
853 pub fn take(&mut self) -> Value {
854 mem::replace(self, Value::Null)
855 }
856}
857
858/// The default value is `Value::Null`.
859///
860/// This is useful for handling omitted `Value` fields when deserializing.
861///
862/// # Examples
863///
864/// ```edition2018
865/// # use serde::Deserialize;
866/// use serde_json::Value;
867///
868/// #[derive(Deserialize)]
869/// struct Settings {
870/// level: i32,
871/// #[serde(default)]
872/// extras: Value,
873/// }
874///
875/// # fn try_main() -> Result<(), serde_json::Error> {
876/// let data = r#" { "level": 42 } "#;
877/// let s: Settings = serde_json::from_str(data)?;
878///
879/// assert_eq!(s.level, 42);
880/// assert_eq!(s.extras, Value::Null);
881/// #
882/// # Ok(())
883/// # }
884/// #
885/// # try_main().unwrap()
886/// ```
887impl Default for Value {
888 fn default() -> Value {
889 Value::Null
890 }
891}
892
893mod de;
894mod from;
895mod index;
896mod partial_eq;
897mod ser;
898
899/// Convert a `T` into `serde_json::Value` which is an enum that can represent
900/// any valid JSON data.
901///
902/// # Example
903///
904/// ```edition2018
905/// use serde::Serialize;
906/// use serde_json::json;
907///
908/// use std::error::Error;
909///
910/// #[derive(Serialize)]
911/// struct User {
912/// fingerprint: String,
913/// location: String,
914/// }
915///
916/// fn compare_json_values() -> Result<(), Box<Error>> {
917/// let u = User {
918/// fingerprint: "0xF9BA143B95FF6D82".to_owned(),
919/// location: "Menlo Park, CA".to_owned(),
920/// };
921///
922/// // The type of `expected` is `serde_json::Value`
923/// let expected = json!({
924/// "fingerprint": "0xF9BA143B95FF6D82",
925/// "location": "Menlo Park, CA",
926/// });
927///
928/// let v = serde_json::to_value(u).unwrap();
929/// assert_eq!(v, expected);
930///
931/// Ok(())
932/// }
933/// #
934/// # compare_json_values().unwrap();
935/// ```
936///
937/// # Errors
938///
939/// This conversion can fail if `T`'s implementation of `Serialize` decides to
940/// fail, or if `T` contains a map with non-string keys.
941///
942/// ```edition2018
943/// use std::collections::BTreeMap;
944///
945/// fn main() {
946/// // The keys in this map are vectors, not strings.
947/// let mut map = BTreeMap::new();
948/// map.insert(vec![32, 64], "x86");
949///
950/// println!("{}", serde_json::to_value(map).unwrap_err());
951/// }
952/// ```
953// Taking by value is more friendly to iterator adapters, option and result
954// consumers, etc. See https://github.com/serde-rs/json/pull/149.
955pub fn to_value<T>(value: T) -> Result<Value, Error>
956where
957 T: Serialize,
958{
959 value.serialize(Serializer)
960}
961
962/// Interpret a `serde_json::Value` as an instance of type `T`.
963///
964/// # Example
965///
966/// ```edition2018
967/// use serde::Deserialize;
968/// use serde_json::json;
969///
970/// #[derive(Deserialize, Debug)]
971/// struct User {
972/// fingerprint: String,
973/// location: String,
974/// }
975///
976/// fn main() {
977/// // The type of `j` is `serde_json::Value`
978/// let j = json!({
979/// "fingerprint": "0xF9BA143B95FF6D82",
980/// "location": "Menlo Park, CA"
981/// });
982///
983/// let u: User = serde_json::from_value(j).unwrap();
984/// println!("{:#?}", u);
985/// }
986/// ```
987///
988/// # Errors
989///
990/// This conversion can fail if the structure of the Value does not match the
991/// structure expected by `T`, for example if `T` is a struct type but the Value
992/// contains something other than a JSON map. It can also fail if the structure
993/// is correct but `T`'s implementation of `Deserialize` decides that something
994/// is wrong with the data, for example required struct fields are missing from
995/// the JSON map or some number is too big to fit in the expected primitive
996/// type.
997pub fn from_value<T>(value: Value) -> Result<T, Error>
998where
999 T: DeserializeOwned,
1000{
1001 T::deserialize(value)
1002}