1//! A map of String to serde_json::Value.
2//!
3//! By default the map is backed by a [`BTreeMap`]. Enable the `preserve_order`
4//! feature of serde_json to use [`IndexMap`] instead.
5//!
6//! [`BTreeMap`]: std::collections::BTreeMap
7//! [`IndexMap`]: indexmap::IndexMap
8
9use crate::error::Error;
10use crate::value::Value;
11use alloc::string::String;
12#[cfg(feature = "preserve_order")]
13use alloc::vec::Vec;
14use core::borrow::Borrow;
15use core::fmt::{self, Debug};
16use core::hash::{Hash, Hasher};
17use core::iter::FusedIterator;
18#[cfg(feature = "preserve_order")]
19use core::mem;
20use core::ops;
21use serde::de;
22
23#[cfg(not(feature = "preserve_order"))]
24use alloc::collections::{btree_map, BTreeMap};
25#[cfg(feature = "preserve_order")]
26use indexmap::IndexMap;
27
28/// Represents a JSON key/value type.
29pub struct Map<K, V> {
30 map: MapImpl<K, V>,
31}
32
33#[cfg(not(feature = "preserve_order"))]
34type MapImpl<K, V> = BTreeMap<K, V>;
35#[cfg(feature = "preserve_order")]
36type MapImpl<K, V> = IndexMap<K, V>;
37
38impl Map<String, Value> {
39 /// Makes a new empty Map.
40 #[inline]
41 pub fn new() -> Self {
42 Map {
43 map: MapImpl::new(),
44 }
45 }
46
47 /// Makes a new empty Map with the given initial capacity.
48 #[inline]
49 pub fn with_capacity(capacity: usize) -> Self {
50 Map {
51 #[cfg(not(feature = "preserve_order"))]
52 map: {
53 // does not support with_capacity
54 let _ = capacity;
55 BTreeMap::new()
56 },
57 #[cfg(feature = "preserve_order")]
58 map: IndexMap::with_capacity(capacity),
59 }
60 }
61
62 /// Clears the map, removing all values.
63 #[inline]
64 pub fn clear(&mut self) {
65 self.map.clear();
66 }
67
68 /// Returns a reference to the value corresponding to the key.
69 ///
70 /// The key may be any borrowed form of the map's key type, but the ordering
71 /// on the borrowed form *must* match the ordering on the key type.
72 #[inline]
73 pub fn get<Q>(&self, key: &Q) -> Option<&Value>
74 where
75 String: Borrow<Q>,
76 Q: ?Sized + Ord + Eq + Hash,
77 {
78 self.map.get(key)
79 }
80
81 /// Returns true if the map contains a value for the specified key.
82 ///
83 /// The key may be any borrowed form of the map's key type, but the ordering
84 /// on the borrowed form *must* match the ordering on the key type.
85 #[inline]
86 pub fn contains_key<Q>(&self, key: &Q) -> bool
87 where
88 String: Borrow<Q>,
89 Q: ?Sized + Ord + Eq + Hash,
90 {
91 self.map.contains_key(key)
92 }
93
94 /// Returns a mutable reference to the value corresponding to the key.
95 ///
96 /// The key may be any borrowed form of the map's key type, but the ordering
97 /// on the borrowed form *must* match the ordering on the key type.
98 #[inline]
99 pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut Value>
100 where
101 String: Borrow<Q>,
102 Q: ?Sized + Ord + Eq + Hash,
103 {
104 self.map.get_mut(key)
105 }
106
107 /// Returns the key-value pair matching the given key.
108 ///
109 /// The key may be any borrowed form of the map's key type, but the ordering
110 /// on the borrowed form *must* match the ordering on the key type.
111 #[inline]
112 pub fn get_key_value<Q>(&self, key: &Q) -> Option<(&String, &Value)>
113 where
114 String: Borrow<Q>,
115 Q: ?Sized + Ord + Eq + Hash,
116 {
117 self.map.get_key_value(key)
118 }
119
120 /// Inserts a key-value pair into the map.
121 ///
122 /// If the map did not have this key present, `None` is returned.
123 ///
124 /// If the map did have this key present, the value is updated, and the old
125 /// value is returned.
126 #[inline]
127 pub fn insert(&mut self, k: String, v: Value) -> Option<Value> {
128 self.map.insert(k, v)
129 }
130
131 /// Insert a key-value pair in the map at the given index.
132 ///
133 /// If the map did not have this key present, `None` is returned.
134 ///
135 /// If the map did have this key present, the key is moved to the new
136 /// position, the value is updated, and the old value is returned.
137 #[cfg(feature = "preserve_order")]
138 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
139 #[inline]
140 pub fn shift_insert(&mut self, index: usize, k: String, v: Value) -> Option<Value> {
141 self.map.shift_insert(index, k, v)
142 }
143
144 /// Removes a key from the map, returning the value at the key if the key
145 /// was previously in the map.
146 ///
147 /// The key may be any borrowed form of the map's key type, but the ordering
148 /// on the borrowed form *must* match the ordering on the key type.
149 ///
150 /// If serde_json's "preserve_order" is enabled, `.remove(key)` is
151 /// equivalent to [`.swap_remove(key)`][Self::swap_remove], replacing this
152 /// entry's position with the last element. If you need to preserve the
153 /// relative order of the keys in the map, use
154 /// [`.shift_remove(key)`][Self::shift_remove] instead.
155 #[inline]
156 pub fn remove<Q>(&mut self, key: &Q) -> Option<Value>
157 where
158 String: Borrow<Q>,
159 Q: ?Sized + Ord + Eq + Hash,
160 {
161 #[cfg(feature = "preserve_order")]
162 return self.swap_remove(key);
163 #[cfg(not(feature = "preserve_order"))]
164 return self.map.remove(key);
165 }
166
167 /// Removes a key from the map, returning the stored key and value if the
168 /// key was previously in the map.
169 ///
170 /// The key may be any borrowed form of the map's key type, but the ordering
171 /// on the borrowed form *must* match the ordering on the key type.
172 ///
173 /// If serde_json's "preserve_order" is enabled, `.remove_entry(key)` is
174 /// equivalent to [`.swap_remove_entry(key)`][Self::swap_remove_entry],
175 /// replacing this entry's position with the last element. If you need to
176 /// preserve the relative order of the keys in the map, use
177 /// [`.shift_remove_entry(key)`][Self::shift_remove_entry] instead.
178 #[inline]
179 pub fn remove_entry<Q>(&mut self, key: &Q) -> Option<(String, Value)>
180 where
181 String: Borrow<Q>,
182 Q: ?Sized + Ord + Eq + Hash,
183 {
184 #[cfg(feature = "preserve_order")]
185 return self.swap_remove_entry(key);
186 #[cfg(not(feature = "preserve_order"))]
187 return self.map.remove_entry(key);
188 }
189
190 /// Removes and returns the value corresponding to the key from the map.
191 ///
192 /// Like [`Vec::swap_remove`], the entry is removed by swapping it with the
193 /// last element of the map and popping it off. This perturbs the position
194 /// of what used to be the last element!
195 ///
196 /// [`Vec::swap_remove`]: std::vec::Vec::swap_remove
197 #[cfg(feature = "preserve_order")]
198 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
199 #[inline]
200 pub fn swap_remove<Q>(&mut self, key: &Q) -> Option<Value>
201 where
202 String: Borrow<Q>,
203 Q: ?Sized + Ord + Eq + Hash,
204 {
205 self.map.swap_remove(key)
206 }
207
208 /// Remove and return the key-value pair.
209 ///
210 /// Like [`Vec::swap_remove`], the entry is removed by swapping it with the
211 /// last element of the map and popping it off. This perturbs the position
212 /// of what used to be the last element!
213 ///
214 /// [`Vec::swap_remove`]: std::vec::Vec::swap_remove
215 #[cfg(feature = "preserve_order")]
216 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
217 #[inline]
218 pub fn swap_remove_entry<Q>(&mut self, key: &Q) -> Option<(String, Value)>
219 where
220 String: Borrow<Q>,
221 Q: ?Sized + Ord + Eq + Hash,
222 {
223 self.map.swap_remove_entry(key)
224 }
225
226 /// Removes and returns the value corresponding to the key from the map.
227 ///
228 /// Like [`Vec::remove`], the entry is removed by shifting all of the
229 /// elements that follow it, preserving their relative order. This perturbs
230 /// the index of all of those elements!
231 ///
232 /// [`Vec::remove`]: std::vec::Vec::remove
233 #[cfg(feature = "preserve_order")]
234 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
235 #[inline]
236 pub fn shift_remove<Q>(&mut self, key: &Q) -> Option<Value>
237 where
238 String: Borrow<Q>,
239 Q: ?Sized + Ord + Eq + Hash,
240 {
241 self.map.shift_remove(key)
242 }
243
244 /// Remove and return the key-value pair.
245 ///
246 /// Like [`Vec::remove`], the entry is removed by shifting all of the
247 /// elements that follow it, preserving their relative order. This perturbs
248 /// the index of all of those elements!
249 ///
250 /// [`Vec::remove`]: std::vec::Vec::remove
251 #[cfg(feature = "preserve_order")]
252 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
253 #[inline]
254 pub fn shift_remove_entry<Q>(&mut self, key: &Q) -> Option<(String, Value)>
255 where
256 String: Borrow<Q>,
257 Q: ?Sized + Ord + Eq + Hash,
258 {
259 self.map.shift_remove_entry(key)
260 }
261
262 /// Moves all elements from other into self, leaving other empty.
263 #[inline]
264 pub fn append(&mut self, other: &mut Self) {
265 #[cfg(feature = "preserve_order")]
266 self.map
267 .extend(mem::replace(&mut other.map, MapImpl::default()));
268 #[cfg(not(feature = "preserve_order"))]
269 self.map.append(&mut other.map);
270 }
271
272 /// Gets the given key's corresponding entry in the map for in-place
273 /// manipulation.
274 pub fn entry<S>(&mut self, key: S) -> Entry
275 where
276 S: Into<String>,
277 {
278 #[cfg(not(feature = "preserve_order"))]
279 use alloc::collections::btree_map::Entry as EntryImpl;
280 #[cfg(feature = "preserve_order")]
281 use indexmap::map::Entry as EntryImpl;
282
283 match self.map.entry(key.into()) {
284 EntryImpl::Vacant(vacant) => Entry::Vacant(VacantEntry { vacant }),
285 EntryImpl::Occupied(occupied) => Entry::Occupied(OccupiedEntry { occupied }),
286 }
287 }
288
289 /// Returns the number of elements in the map.
290 #[inline]
291 pub fn len(&self) -> usize {
292 self.map.len()
293 }
294
295 /// Returns true if the map contains no elements.
296 #[inline]
297 pub fn is_empty(&self) -> bool {
298 self.map.is_empty()
299 }
300
301 /// Gets an iterator over the entries of the map.
302 #[inline]
303 pub fn iter(&self) -> Iter {
304 Iter {
305 iter: self.map.iter(),
306 }
307 }
308
309 /// Gets a mutable iterator over the entries of the map.
310 #[inline]
311 pub fn iter_mut(&mut self) -> IterMut {
312 IterMut {
313 iter: self.map.iter_mut(),
314 }
315 }
316
317 /// Gets an iterator over the keys of the map.
318 #[inline]
319 pub fn keys(&self) -> Keys {
320 Keys {
321 iter: self.map.keys(),
322 }
323 }
324
325 /// Gets an iterator over the values of the map.
326 #[inline]
327 pub fn values(&self) -> Values {
328 Values {
329 iter: self.map.values(),
330 }
331 }
332
333 /// Gets an iterator over mutable values of the map.
334 #[inline]
335 pub fn values_mut(&mut self) -> ValuesMut {
336 ValuesMut {
337 iter: self.map.values_mut(),
338 }
339 }
340
341 /// Gets an iterator over the values of the map.
342 #[inline]
343 pub fn into_values(self) -> IntoValues {
344 IntoValues {
345 iter: self.map.into_values(),
346 }
347 }
348
349 /// Retains only the elements specified by the predicate.
350 ///
351 /// In other words, remove all pairs `(k, v)` such that `f(&k, &mut v)`
352 /// returns `false`.
353 #[inline]
354 pub fn retain<F>(&mut self, f: F)
355 where
356 F: FnMut(&String, &mut Value) -> bool,
357 {
358 self.map.retain(f);
359 }
360
361 /// Sorts this map's entries in-place using `str`'s usual ordering.
362 ///
363 /// If serde_json's "preserve_order" feature is not enabled, this method
364 /// does no work because all JSON maps are always kept in a sorted state.
365 ///
366 /// If serde_json's "preserve_order" feature is enabled, this method
367 /// destroys the original source order or insertion order of this map in
368 /// favor of an alphanumerical order that matches how a BTreeMap with the
369 /// same contents would be ordered. This takes **O(n log n + c)** time where
370 /// _n_ is the length of the map and _c_ is the capacity.
371 ///
372 /// Other maps nested within the values of this map are not sorted. If you
373 /// need the entire data structure to be sorted at all levels, you must also
374 /// call
375 /// <code>map.[values_mut]\().for_each([Value::sort_all_objects])</code>.
376 ///
377 /// [values_mut]: Map::values_mut
378 #[inline]
379 pub fn sort_keys(&mut self) {
380 #[cfg(feature = "preserve_order")]
381 self.map.sort_unstable_keys();
382 }
383}
384
385#[allow(clippy::derivable_impls)] // clippy bug: https://github.com/rust-lang/rust-clippy/issues/7655
386impl Default for Map<String, Value> {
387 #[inline]
388 fn default() -> Self {
389 Map {
390 map: MapImpl::new(),
391 }
392 }
393}
394
395impl Clone for Map<String, Value> {
396 #[inline]
397 fn clone(&self) -> Self {
398 Map {
399 map: self.map.clone(),
400 }
401 }
402
403 #[inline]
404 fn clone_from(&mut self, source: &Self) {
405 self.map.clone_from(&source.map);
406 }
407}
408
409impl PartialEq for Map<String, Value> {
410 #[inline]
411 fn eq(&self, other: &Self) -> bool {
412 self.map.eq(&other.map)
413 }
414}
415
416impl Eq for Map<String, Value> {}
417
418impl Hash for Map<String, Value> {
419 fn hash<H: Hasher>(&self, state: &mut H) {
420 #[cfg(not(feature = "preserve_order"))]
421 {
422 self.map.hash(state);
423 }
424
425 #[cfg(feature = "preserve_order")]
426 {
427 let mut kv = Vec::from_iter(&self.map);
428 kv.sort_unstable_by(|a, b| a.0.cmp(b.0));
429 kv.hash(state);
430 }
431 }
432}
433
434/// Access an element of this map. Panics if the given key is not present in the
435/// map.
436///
437/// ```
438/// # use serde_json::Value;
439/// #
440/// # let val = &Value::String("".to_owned());
441/// # let _ =
442/// match val {
443/// Value::String(s) => Some(s.as_str()),
444/// Value::Array(arr) => arr[0].as_str(),
445/// Value::Object(map) => map["type"].as_str(),
446/// _ => None,
447/// }
448/// # ;
449/// ```
450impl<Q> ops::Index<&Q> for Map<String, Value>
451where
452 String: Borrow<Q>,
453 Q: ?Sized + Ord + Eq + Hash,
454{
455 type Output = Value;
456
457 fn index(&self, index: &Q) -> &Value {
458 self.map.index(index)
459 }
460}
461
462/// Mutably access an element of this map. Panics if the given key is not
463/// present in the map.
464///
465/// ```
466/// # use serde_json::json;
467/// #
468/// # let mut map = serde_json::Map::new();
469/// # map.insert("key".to_owned(), serde_json::Value::Null);
470/// #
471/// map["key"] = json!("value");
472/// ```
473impl<Q> ops::IndexMut<&Q> for Map<String, Value>
474where
475 String: Borrow<Q>,
476 Q: ?Sized + Ord + Eq + Hash,
477{
478 fn index_mut(&mut self, index: &Q) -> &mut Value {
479 self.map.get_mut(index).expect(msg:"no entry found for key")
480 }
481}
482
483impl Debug for Map<String, Value> {
484 #[inline]
485 fn fmt(&self, formatter: &mut fmt::Formatter) -> Result<(), fmt::Error> {
486 self.map.fmt(formatter)
487 }
488}
489
490#[cfg(any(feature = "std", feature = "alloc"))]
491impl serde::ser::Serialize for Map<String, Value> {
492 #[inline]
493 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
494 where
495 S: serde::ser::Serializer,
496 {
497 use serde::ser::SerializeMap;
498 let mut map: ::SerializeMap = tri!(serializer.serialize_map(Some(self.len())));
499 for (k: &String, v: &Value) in self {
500 tri!(map.serialize_entry(k, v));
501 }
502 map.end()
503 }
504}
505
506impl<'de> de::Deserialize<'de> for Map<String, Value> {
507 #[inline]
508 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
509 where
510 D: de::Deserializer<'de>,
511 {
512 struct Visitor;
513
514 impl<'de> de::Visitor<'de> for Visitor {
515 type Value = Map<String, Value>;
516
517 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
518 formatter.write_str("a map")
519 }
520
521 #[inline]
522 fn visit_unit<E>(self) -> Result<Self::Value, E>
523 where
524 E: de::Error,
525 {
526 Ok(Map::new())
527 }
528
529 #[cfg(any(feature = "std", feature = "alloc"))]
530 #[inline]
531 fn visit_map<V>(self, mut visitor: V) -> Result<Self::Value, V::Error>
532 where
533 V: de::MapAccess<'de>,
534 {
535 let mut values = Map::new();
536
537 while let Some((key, value)) = tri!(visitor.next_entry()) {
538 values.insert(key, value);
539 }
540
541 Ok(values)
542 }
543 }
544
545 deserializer.deserialize_map(Visitor)
546 }
547}
548
549impl FromIterator<(String, Value)> for Map<String, Value> {
550 fn from_iter<T>(iter: T) -> Self
551 where
552 T: IntoIterator<Item = (String, Value)>,
553 {
554 Map {
555 map: FromIterator::from_iter(iter),
556 }
557 }
558}
559
560impl Extend<(String, Value)> for Map<String, Value> {
561 fn extend<T>(&mut self, iter: T)
562 where
563 T: IntoIterator<Item = (String, Value)>,
564 {
565 self.map.extend(iter);
566 }
567}
568
569macro_rules! delegate_iterator {
570 (($name:ident $($generics:tt)*) => $item:ty) => {
571 impl $($generics)* Iterator for $name $($generics)* {
572 type Item = $item;
573 #[inline]
574 fn next(&mut self) -> Option<Self::Item> {
575 self.iter.next()
576 }
577 #[inline]
578 fn size_hint(&self) -> (usize, Option<usize>) {
579 self.iter.size_hint()
580 }
581 }
582
583 impl $($generics)* DoubleEndedIterator for $name $($generics)* {
584 #[inline]
585 fn next_back(&mut self) -> Option<Self::Item> {
586 self.iter.next_back()
587 }
588 }
589
590 impl $($generics)* ExactSizeIterator for $name $($generics)* {
591 #[inline]
592 fn len(&self) -> usize {
593 self.iter.len()
594 }
595 }
596
597 impl $($generics)* FusedIterator for $name $($generics)* {}
598 }
599}
600
601impl<'de> de::IntoDeserializer<'de, Error> for Map<String, Value> {
602 type Deserializer = Self;
603
604 fn into_deserializer(self) -> Self::Deserializer {
605 self
606 }
607}
608
609impl<'de> de::IntoDeserializer<'de, Error> for &'de Map<String, Value> {
610 type Deserializer = Self;
611
612 fn into_deserializer(self) -> Self::Deserializer {
613 self
614 }
615}
616
617//////////////////////////////////////////////////////////////////////////////
618
619/// A view into a single entry in a map, which may either be vacant or occupied.
620/// This enum is constructed from the [`entry`] method on [`Map`].
621///
622/// [`entry`]: Map::entry
623pub enum Entry<'a> {
624 /// A vacant Entry.
625 Vacant(VacantEntry<'a>),
626 /// An occupied Entry.
627 Occupied(OccupiedEntry<'a>),
628}
629
630/// A vacant Entry. It is part of the [`Entry`] enum.
631pub struct VacantEntry<'a> {
632 vacant: VacantEntryImpl<'a>,
633}
634
635/// An occupied Entry. It is part of the [`Entry`] enum.
636pub struct OccupiedEntry<'a> {
637 occupied: OccupiedEntryImpl<'a>,
638}
639
640#[cfg(not(feature = "preserve_order"))]
641type VacantEntryImpl<'a> = btree_map::VacantEntry<'a, String, Value>;
642#[cfg(feature = "preserve_order")]
643type VacantEntryImpl<'a> = indexmap::map::VacantEntry<'a, String, Value>;
644
645#[cfg(not(feature = "preserve_order"))]
646type OccupiedEntryImpl<'a> = btree_map::OccupiedEntry<'a, String, Value>;
647#[cfg(feature = "preserve_order")]
648type OccupiedEntryImpl<'a> = indexmap::map::OccupiedEntry<'a, String, Value>;
649
650impl<'a> Entry<'a> {
651 /// Returns a reference to this entry's key.
652 ///
653 /// # Examples
654 ///
655 /// ```
656 /// let mut map = serde_json::Map::new();
657 /// assert_eq!(map.entry("serde").key(), &"serde");
658 /// ```
659 pub fn key(&self) -> &String {
660 match self {
661 Entry::Vacant(e) => e.key(),
662 Entry::Occupied(e) => e.key(),
663 }
664 }
665
666 /// Ensures a value is in the entry by inserting the default if empty, and
667 /// returns a mutable reference to the value in the entry.
668 ///
669 /// # Examples
670 ///
671 /// ```
672 /// # use serde_json::json;
673 /// #
674 /// let mut map = serde_json::Map::new();
675 /// map.entry("serde").or_insert(json!(12));
676 ///
677 /// assert_eq!(map["serde"], 12);
678 /// ```
679 pub fn or_insert(self, default: Value) -> &'a mut Value {
680 match self {
681 Entry::Vacant(entry) => entry.insert(default),
682 Entry::Occupied(entry) => entry.into_mut(),
683 }
684 }
685
686 /// Ensures a value is in the entry by inserting the result of the default
687 /// function if empty, and returns a mutable reference to the value in the
688 /// entry.
689 ///
690 /// # Examples
691 ///
692 /// ```
693 /// # use serde_json::json;
694 /// #
695 /// let mut map = serde_json::Map::new();
696 /// map.entry("serde").or_insert_with(|| json!("hoho"));
697 ///
698 /// assert_eq!(map["serde"], "hoho".to_owned());
699 /// ```
700 pub fn or_insert_with<F>(self, default: F) -> &'a mut Value
701 where
702 F: FnOnce() -> Value,
703 {
704 match self {
705 Entry::Vacant(entry) => entry.insert(default()),
706 Entry::Occupied(entry) => entry.into_mut(),
707 }
708 }
709
710 /// Provides in-place mutable access to an occupied entry before any
711 /// potential inserts into the map.
712 ///
713 /// # Examples
714 ///
715 /// ```
716 /// # use serde_json::json;
717 /// #
718 /// let mut map = serde_json::Map::new();
719 /// map.entry("serde")
720 /// .and_modify(|e| *e = json!("rust"))
721 /// .or_insert(json!("cpp"));
722 ///
723 /// assert_eq!(map["serde"], "cpp");
724 ///
725 /// map.entry("serde")
726 /// .and_modify(|e| *e = json!("rust"))
727 /// .or_insert(json!("cpp"));
728 ///
729 /// assert_eq!(map["serde"], "rust");
730 /// ```
731 pub fn and_modify<F>(self, f: F) -> Self
732 where
733 F: FnOnce(&mut Value),
734 {
735 match self {
736 Entry::Occupied(mut entry) => {
737 f(entry.get_mut());
738 Entry::Occupied(entry)
739 }
740 Entry::Vacant(entry) => Entry::Vacant(entry),
741 }
742 }
743}
744
745impl<'a> VacantEntry<'a> {
746 /// Gets a reference to the key that would be used when inserting a value
747 /// through the VacantEntry.
748 ///
749 /// # Examples
750 ///
751 /// ```
752 /// use serde_json::map::Entry;
753 ///
754 /// let mut map = serde_json::Map::new();
755 ///
756 /// match map.entry("serde") {
757 /// Entry::Vacant(vacant) => {
758 /// assert_eq!(vacant.key(), &"serde");
759 /// }
760 /// Entry::Occupied(_) => unimplemented!(),
761 /// }
762 /// ```
763 #[inline]
764 pub fn key(&self) -> &String {
765 self.vacant.key()
766 }
767
768 /// Sets the value of the entry with the VacantEntry's key, and returns a
769 /// mutable reference to it.
770 ///
771 /// # Examples
772 ///
773 /// ```
774 /// # use serde_json::json;
775 /// #
776 /// use serde_json::map::Entry;
777 ///
778 /// let mut map = serde_json::Map::new();
779 ///
780 /// match map.entry("serde") {
781 /// Entry::Vacant(vacant) => {
782 /// vacant.insert(json!("hoho"));
783 /// }
784 /// Entry::Occupied(_) => unimplemented!(),
785 /// }
786 /// ```
787 #[inline]
788 pub fn insert(self, value: Value) -> &'a mut Value {
789 self.vacant.insert(value)
790 }
791}
792
793impl<'a> OccupiedEntry<'a> {
794 /// Gets a reference to the key in the entry.
795 ///
796 /// # Examples
797 ///
798 /// ```
799 /// # use serde_json::json;
800 /// #
801 /// use serde_json::map::Entry;
802 ///
803 /// let mut map = serde_json::Map::new();
804 /// map.insert("serde".to_owned(), json!(12));
805 ///
806 /// match map.entry("serde") {
807 /// Entry::Occupied(occupied) => {
808 /// assert_eq!(occupied.key(), &"serde");
809 /// }
810 /// Entry::Vacant(_) => unimplemented!(),
811 /// }
812 /// ```
813 #[inline]
814 pub fn key(&self) -> &String {
815 self.occupied.key()
816 }
817
818 /// Gets a reference to the value in the entry.
819 ///
820 /// # Examples
821 ///
822 /// ```
823 /// # use serde_json::json;
824 /// #
825 /// use serde_json::map::Entry;
826 ///
827 /// let mut map = serde_json::Map::new();
828 /// map.insert("serde".to_owned(), json!(12));
829 ///
830 /// match map.entry("serde") {
831 /// Entry::Occupied(occupied) => {
832 /// assert_eq!(occupied.get(), 12);
833 /// }
834 /// Entry::Vacant(_) => unimplemented!(),
835 /// }
836 /// ```
837 #[inline]
838 pub fn get(&self) -> &Value {
839 self.occupied.get()
840 }
841
842 /// Gets a mutable reference to the value in the entry.
843 ///
844 /// # Examples
845 ///
846 /// ```
847 /// # use serde_json::json;
848 /// #
849 /// use serde_json::map::Entry;
850 ///
851 /// let mut map = serde_json::Map::new();
852 /// map.insert("serde".to_owned(), json!([1, 2, 3]));
853 ///
854 /// match map.entry("serde") {
855 /// Entry::Occupied(mut occupied) => {
856 /// occupied.get_mut().as_array_mut().unwrap().push(json!(4));
857 /// }
858 /// Entry::Vacant(_) => unimplemented!(),
859 /// }
860 ///
861 /// assert_eq!(map["serde"].as_array().unwrap().len(), 4);
862 /// ```
863 #[inline]
864 pub fn get_mut(&mut self) -> &mut Value {
865 self.occupied.get_mut()
866 }
867
868 /// Converts the entry into a mutable reference to its value.
869 ///
870 /// # Examples
871 ///
872 /// ```
873 /// # use serde_json::json;
874 /// #
875 /// use serde_json::map::Entry;
876 ///
877 /// let mut map = serde_json::Map::new();
878 /// map.insert("serde".to_owned(), json!([1, 2, 3]));
879 ///
880 /// match map.entry("serde") {
881 /// Entry::Occupied(mut occupied) => {
882 /// occupied.into_mut().as_array_mut().unwrap().push(json!(4));
883 /// }
884 /// Entry::Vacant(_) => unimplemented!(),
885 /// }
886 ///
887 /// assert_eq!(map["serde"].as_array().unwrap().len(), 4);
888 /// ```
889 #[inline]
890 pub fn into_mut(self) -> &'a mut Value {
891 self.occupied.into_mut()
892 }
893
894 /// Sets the value of the entry with the `OccupiedEntry`'s key, and returns
895 /// the entry's old value.
896 ///
897 /// # Examples
898 ///
899 /// ```
900 /// # use serde_json::json;
901 /// #
902 /// use serde_json::map::Entry;
903 ///
904 /// let mut map = serde_json::Map::new();
905 /// map.insert("serde".to_owned(), json!(12));
906 ///
907 /// match map.entry("serde") {
908 /// Entry::Occupied(mut occupied) => {
909 /// assert_eq!(occupied.insert(json!(13)), 12);
910 /// assert_eq!(occupied.get(), 13);
911 /// }
912 /// Entry::Vacant(_) => unimplemented!(),
913 /// }
914 /// ```
915 #[inline]
916 pub fn insert(&mut self, value: Value) -> Value {
917 self.occupied.insert(value)
918 }
919
920 /// Takes the value of the entry out of the map, and returns it.
921 ///
922 /// If serde_json's "preserve_order" is enabled, `.remove()` is
923 /// equivalent to [`.swap_remove()`][Self::swap_remove], replacing this
924 /// entry's position with the last element. If you need to preserve the
925 /// relative order of the keys in the map, use
926 /// [`.shift_remove()`][Self::shift_remove] instead.
927 ///
928 /// # Examples
929 ///
930 /// ```
931 /// # use serde_json::json;
932 /// #
933 /// use serde_json::map::Entry;
934 ///
935 /// let mut map = serde_json::Map::new();
936 /// map.insert("serde".to_owned(), json!(12));
937 ///
938 /// match map.entry("serde") {
939 /// Entry::Occupied(occupied) => {
940 /// assert_eq!(occupied.remove(), 12);
941 /// }
942 /// Entry::Vacant(_) => unimplemented!(),
943 /// }
944 /// ```
945 #[inline]
946 pub fn remove(self) -> Value {
947 #[cfg(feature = "preserve_order")]
948 return self.swap_remove();
949 #[cfg(not(feature = "preserve_order"))]
950 return self.occupied.remove();
951 }
952
953 /// Takes the value of the entry out of the map, and returns it.
954 ///
955 /// Like [`Vec::swap_remove`], the entry is removed by swapping it with the
956 /// last element of the map and popping it off. This perturbs the position
957 /// of what used to be the last element!
958 ///
959 /// [`Vec::swap_remove`]: std::vec::Vec::swap_remove
960 #[cfg(feature = "preserve_order")]
961 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
962 #[inline]
963 pub fn swap_remove(self) -> Value {
964 self.occupied.swap_remove()
965 }
966
967 /// Takes the value of the entry out of the map, and returns it.
968 ///
969 /// Like [`Vec::remove`], the entry is removed by shifting all of the
970 /// elements that follow it, preserving their relative order. This perturbs
971 /// the index of all of those elements!
972 ///
973 /// [`Vec::remove`]: std::vec::Vec::remove
974 #[cfg(feature = "preserve_order")]
975 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
976 #[inline]
977 pub fn shift_remove(self) -> Value {
978 self.occupied.shift_remove()
979 }
980
981 /// Removes the entry from the map, returning the stored key and value.
982 ///
983 /// If serde_json's "preserve_order" is enabled, `.remove_entry()` is
984 /// equivalent to [`.swap_remove_entry()`][Self::swap_remove_entry],
985 /// replacing this entry's position with the last element. If you need to
986 /// preserve the relative order of the keys in the map, use
987 /// [`.shift_remove_entry()`][Self::shift_remove_entry] instead.
988 ///
989 /// # Examples
990 ///
991 /// ```
992 /// # use serde_json::json;
993 /// #
994 /// use serde_json::map::Entry;
995 ///
996 /// let mut map = serde_json::Map::new();
997 /// map.insert("serde".to_owned(), json!(12));
998 ///
999 /// match map.entry("serde") {
1000 /// Entry::Occupied(occupied) => {
1001 /// let (key, value) = occupied.remove_entry();
1002 /// assert_eq!(key, "serde");
1003 /// assert_eq!(value, 12);
1004 /// }
1005 /// Entry::Vacant(_) => unimplemented!(),
1006 /// }
1007 /// ```
1008 #[inline]
1009 pub fn remove_entry(self) -> (String, Value) {
1010 #[cfg(feature = "preserve_order")]
1011 return self.swap_remove_entry();
1012 #[cfg(not(feature = "preserve_order"))]
1013 return self.occupied.remove_entry();
1014 }
1015
1016 /// Removes the entry from the map, returning the stored key and value.
1017 ///
1018 /// Like [`Vec::swap_remove`], the entry is removed by swapping it with the
1019 /// last element of the map and popping it off. This perturbs the position
1020 /// of what used to be the last element!
1021 ///
1022 /// [`Vec::swap_remove`]: std::vec::Vec::swap_remove
1023 #[cfg(feature = "preserve_order")]
1024 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
1025 #[inline]
1026 pub fn swap_remove_entry(self) -> (String, Value) {
1027 self.occupied.swap_remove_entry()
1028 }
1029
1030 /// Removes the entry from the map, returning the stored key and value.
1031 ///
1032 /// Like [`Vec::remove`], the entry is removed by shifting all of the
1033 /// elements that follow it, preserving their relative order. This perturbs
1034 /// the index of all of those elements!
1035 ///
1036 /// [`Vec::remove`]: std::vec::Vec::remove
1037 #[cfg(feature = "preserve_order")]
1038 #[cfg_attr(docsrs, doc(cfg(feature = "preserve_order")))]
1039 #[inline]
1040 pub fn shift_remove_entry(self) -> (String, Value) {
1041 self.occupied.shift_remove_entry()
1042 }
1043}
1044
1045//////////////////////////////////////////////////////////////////////////////
1046
1047impl<'a> IntoIterator for &'a Map<String, Value> {
1048 type Item = (&'a String, &'a Value);
1049 type IntoIter = Iter<'a>;
1050 #[inline]
1051 fn into_iter(self) -> Self::IntoIter {
1052 Iter {
1053 iter: self.map.iter(),
1054 }
1055 }
1056}
1057
1058/// An iterator over a serde_json::Map's entries.
1059pub struct Iter<'a> {
1060 iter: IterImpl<'a>,
1061}
1062
1063#[cfg(not(feature = "preserve_order"))]
1064type IterImpl<'a> = btree_map::Iter<'a, String, Value>;
1065#[cfg(feature = "preserve_order")]
1066type IterImpl<'a> = indexmap::map::Iter<'a, String, Value>;
1067
1068delegate_iterator!((Iter<'a>) => (&'a String, &'a Value));
1069
1070//////////////////////////////////////////////////////////////////////////////
1071
1072impl<'a> IntoIterator for &'a mut Map<String, Value> {
1073 type Item = (&'a String, &'a mut Value);
1074 type IntoIter = IterMut<'a>;
1075 #[inline]
1076 fn into_iter(self) -> Self::IntoIter {
1077 IterMut {
1078 iter: self.map.iter_mut(),
1079 }
1080 }
1081}
1082
1083/// A mutable iterator over a serde_json::Map's entries.
1084pub struct IterMut<'a> {
1085 iter: IterMutImpl<'a>,
1086}
1087
1088#[cfg(not(feature = "preserve_order"))]
1089type IterMutImpl<'a> = btree_map::IterMut<'a, String, Value>;
1090#[cfg(feature = "preserve_order")]
1091type IterMutImpl<'a> = indexmap::map::IterMut<'a, String, Value>;
1092
1093delegate_iterator!((IterMut<'a>) => (&'a String, &'a mut Value));
1094
1095//////////////////////////////////////////////////////////////////////////////
1096
1097impl IntoIterator for Map<String, Value> {
1098 type Item = (String, Value);
1099 type IntoIter = IntoIter;
1100 #[inline]
1101 fn into_iter(self) -> Self::IntoIter {
1102 IntoIter {
1103 iter: self.map.into_iter(),
1104 }
1105 }
1106}
1107
1108/// An owning iterator over a serde_json::Map's entries.
1109pub struct IntoIter {
1110 iter: IntoIterImpl,
1111}
1112
1113#[cfg(not(feature = "preserve_order"))]
1114type IntoIterImpl = btree_map::IntoIter<String, Value>;
1115#[cfg(feature = "preserve_order")]
1116type IntoIterImpl = indexmap::map::IntoIter<String, Value>;
1117
1118delegate_iterator!((IntoIter) => (String, Value));
1119
1120//////////////////////////////////////////////////////////////////////////////
1121
1122/// An iterator over a serde_json::Map's keys.
1123pub struct Keys<'a> {
1124 iter: KeysImpl<'a>,
1125}
1126
1127#[cfg(not(feature = "preserve_order"))]
1128type KeysImpl<'a> = btree_map::Keys<'a, String, Value>;
1129#[cfg(feature = "preserve_order")]
1130type KeysImpl<'a> = indexmap::map::Keys<'a, String, Value>;
1131
1132delegate_iterator!((Keys<'a>) => &'a String);
1133
1134//////////////////////////////////////////////////////////////////////////////
1135
1136/// An iterator over a serde_json::Map's values.
1137pub struct Values<'a> {
1138 iter: ValuesImpl<'a>,
1139}
1140
1141#[cfg(not(feature = "preserve_order"))]
1142type ValuesImpl<'a> = btree_map::Values<'a, String, Value>;
1143#[cfg(feature = "preserve_order")]
1144type ValuesImpl<'a> = indexmap::map::Values<'a, String, Value>;
1145
1146delegate_iterator!((Values<'a>) => &'a Value);
1147
1148//////////////////////////////////////////////////////////////////////////////
1149
1150/// A mutable iterator over a serde_json::Map's values.
1151pub struct ValuesMut<'a> {
1152 iter: ValuesMutImpl<'a>,
1153}
1154
1155#[cfg(not(feature = "preserve_order"))]
1156type ValuesMutImpl<'a> = btree_map::ValuesMut<'a, String, Value>;
1157#[cfg(feature = "preserve_order")]
1158type ValuesMutImpl<'a> = indexmap::map::ValuesMut<'a, String, Value>;
1159
1160delegate_iterator!((ValuesMut<'a>) => &'a mut Value);
1161
1162//////////////////////////////////////////////////////////////////////////////
1163
1164/// An owning iterator over a serde_json::Map's values.
1165pub struct IntoValues {
1166 iter: IntoValuesImpl,
1167}
1168
1169#[cfg(not(feature = "preserve_order"))]
1170type IntoValuesImpl = btree_map::IntoValues<String, Value>;
1171#[cfg(feature = "preserve_order")]
1172type IntoValuesImpl = indexmap::map::IntoValues<String, Value>;
1173
1174delegate_iterator!((IntoValues) => Value);
1175