serde_json/value/
index.rs

1use super::Value;
2use crate::map::Map;
3use alloc::borrow::ToOwned;
4use alloc::string::String;
5use core::fmt::{self, Display};
6use core::ops;
7
8/// A type that can be used to index into a `serde_json::Value`.
9///
10/// The [`get`] and [`get_mut`] methods of `Value` accept any type that
11/// implements `Index`, as does the [square-bracket indexing operator]. This
12/// trait is implemented for strings which are used as the index into a JSON
13/// map, and for `usize` which is used as the index into a JSON array.
14///
15/// [`get`]: ../enum.Value.html#method.get
16/// [`get_mut`]: ../enum.Value.html#method.get_mut
17/// [square-bracket indexing operator]: ../enum.Value.html#impl-Index%3CI%3E-for-Value
18///
19/// This trait is sealed and cannot be implemented for types outside of
20/// `serde_json`.
21///
22/// # Examples
23///
24/// ```
25/// # use serde_json::json;
26/// #
27/// let data = json!({ "inner": [1, 2, 3] });
28///
29/// // Data is a JSON map so it can be indexed with a string.
30/// let inner = &data["inner"];
31///
32/// // Inner is a JSON array so it can be indexed with an integer.
33/// let first = &inner[0];
34///
35/// assert_eq!(first, 1);
36/// ```
37pub trait Index: private::Sealed {
38    /// Return None if the key is not already in the array or object.
39    #[doc(hidden)]
40    fn index_into<'v>(&self, v: &'v Value) -> Option<&'v Value>;
41
42    /// Return None if the key is not already in the array or object.
43    #[doc(hidden)]
44    fn index_into_mut<'v>(&self, v: &'v mut Value) -> Option<&'v mut Value>;
45
46    /// Panic if array index out of bounds. If key is not already in the object,
47    /// insert it with a value of null. Panic if Value is a type that cannot be
48    /// indexed into, except if Value is null then it can be treated as an empty
49    /// object.
50    #[doc(hidden)]
51    fn index_or_insert<'v>(&self, v: &'v mut Value) -> &'v mut Value;
52}
53
54impl Index for usize {
55    fn index_into<'v>(&self, v: &'v Value) -> Option<&'v Value> {
56        match v {
57            Value::Array(vec) => vec.get(*self),
58            _ => None,
59        }
60    }
61    fn index_into_mut<'v>(&self, v: &'v mut Value) -> Option<&'v mut Value> {
62        match v {
63            Value::Array(vec) => vec.get_mut(*self),
64            _ => None,
65        }
66    }
67    fn index_or_insert<'v>(&self, v: &'v mut Value) -> &'v mut Value {
68        match v {
69            Value::Array(vec) => {
70                let len = vec.len();
71                vec.get_mut(*self).unwrap_or_else(|| {
72                    panic!(
73                        "cannot access index {} of JSON array of length {}",
74                        self, len
75                    )
76                })
77            }
78            _ => panic!("cannot access index {} of JSON {}", self, Type(v)),
79        }
80    }
81}
82
83impl Index for str {
84    fn index_into<'v>(&self, v: &'v Value) -> Option<&'v Value> {
85        match v {
86            Value::Object(map) => map.get(self),
87            _ => None,
88        }
89    }
90    fn index_into_mut<'v>(&self, v: &'v mut Value) -> Option<&'v mut Value> {
91        match v {
92            Value::Object(map) => map.get_mut(self),
93            _ => None,
94        }
95    }
96    fn index_or_insert<'v>(&self, v: &'v mut Value) -> &'v mut Value {
97        if let Value::Null = v {
98            *v = Value::Object(Map::new());
99        }
100        match v {
101            Value::Object(map) => map.entry(self.to_owned()).or_insert(Value::Null),
102            _ => panic!("cannot access key {:?} in JSON {}", self, Type(v)),
103        }
104    }
105}
106
107impl Index for String {
108    fn index_into<'v>(&self, v: &'v Value) -> Option<&'v Value> {
109        self[..].index_into(v)
110    }
111    fn index_into_mut<'v>(&self, v: &'v mut Value) -> Option<&'v mut Value> {
112        self[..].index_into_mut(v)
113    }
114    fn index_or_insert<'v>(&self, v: &'v mut Value) -> &'v mut Value {
115        self[..].index_or_insert(v)
116    }
117}
118
119impl<T> Index for &T
120where
121    T: ?Sized + Index,
122{
123    fn index_into<'v>(&self, v: &'v Value) -> Option<&'v Value> {
124        (**self).index_into(v)
125    }
126    fn index_into_mut<'v>(&self, v: &'v mut Value) -> Option<&'v mut Value> {
127        (**self).index_into_mut(v)
128    }
129    fn index_or_insert<'v>(&self, v: &'v mut Value) -> &'v mut Value {
130        (**self).index_or_insert(v)
131    }
132}
133
134// Prevent users from implementing the Index trait.
135mod private {
136    pub trait Sealed {}
137    impl Sealed for usize {}
138    impl Sealed for str {}
139    impl Sealed for alloc::string::String {}
140    impl<T> Sealed for &T where T: ?Sized + Sealed {}
141}
142
143/// Used in panic messages.
144struct Type<'a>(&'a Value);
145
146impl<'a> Display for Type<'a> {
147    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
148        match *self.0 {
149            Value::Null => formatter.write_str("null"),
150            Value::Bool(_) => formatter.write_str("boolean"),
151            Value::Number(_) => formatter.write_str("number"),
152            Value::String(_) => formatter.write_str("string"),
153            Value::Array(_) => formatter.write_str("array"),
154            Value::Object(_) => formatter.write_str("object"),
155        }
156    }
157}
158
159// The usual semantics of Index is to panic on invalid indexing.
160//
161// That said, the usual semantics are for things like Vec and BTreeMap which
162// have different use cases than Value. If you are working with a Vec, you know
163// that you are working with a Vec and you can get the len of the Vec and make
164// sure your indices are within bounds. The Value use cases are more
165// loosey-goosey. You got some JSON from an endpoint and you want to pull values
166// out of it. Outside of this Index impl, you already have the option of using
167// value.as_array() and working with the Vec directly, or matching on
168// Value::Array and getting the Vec directly. The Index impl means you can skip
169// that and index directly into the thing using a concise syntax. You don't have
170// to check the type, you don't have to check the len, it is all about what you
171// expect the Value to look like.
172//
173// Basically the use cases that would be well served by panicking here are
174// better served by using one of the other approaches: get and get_mut,
175// as_array, or match. The value of this impl is that it adds a way of working
176// with Value that is not well served by the existing approaches: concise and
177// careless and sometimes that is exactly what you want.
178impl<I> ops::Index<I> for Value
179where
180    I: Index,
181{
182    type Output = Value;
183
184    /// Index into a `serde_json::Value` using the syntax `value[0]` or
185    /// `value["k"]`.
186    ///
187    /// Returns `Value::Null` if the type of `self` does not match the type of
188    /// the index, for example if the index is a string and `self` is an array
189    /// or a number. Also returns `Value::Null` if the given key does not exist
190    /// in the map or the given index is not within the bounds of the array.
191    ///
192    /// For retrieving deeply nested values, you should have a look at the
193    /// `Value::pointer` method.
194    ///
195    /// # Examples
196    ///
197    /// ```
198    /// # use serde_json::json;
199    /// #
200    /// let data = json!({
201    ///     "x": {
202    ///         "y": ["z", "zz"]
203    ///     }
204    /// });
205    ///
206    /// assert_eq!(data["x"]["y"], json!(["z", "zz"]));
207    /// assert_eq!(data["x"]["y"][0], json!("z"));
208    ///
209    /// assert_eq!(data["a"], json!(null)); // returns null for undefined values
210    /// assert_eq!(data["a"]["b"], json!(null)); // does not panic
211    /// ```
212    fn index(&self, index: I) -> &Value {
213        static NULL: Value = Value::Null;
214        index.index_into(self).unwrap_or(&NULL)
215    }
216}
217
218impl<I> ops::IndexMut<I> for Value
219where
220    I: Index,
221{
222    /// Write into a `serde_json::Value` using the syntax `value[0] = ...` or
223    /// `value["k"] = ...`.
224    ///
225    /// If the index is a number, the value must be an array of length bigger
226    /// than the index. Indexing into a value that is not an array or an array
227    /// that is too small will panic.
228    ///
229    /// If the index is a string, the value must be an object or null which is
230    /// treated like an empty object. If the key is not already present in the
231    /// object, it will be inserted with a value of null. Indexing into a value
232    /// that is neither an object nor null will panic.
233    ///
234    /// # Examples
235    ///
236    /// ```
237    /// # use serde_json::json;
238    /// #
239    /// let mut data = json!({ "x": 0 });
240    ///
241    /// // replace an existing key
242    /// data["x"] = json!(1);
243    ///
244    /// // insert a new key
245    /// data["y"] = json!([false, false, false]);
246    ///
247    /// // replace an array value
248    /// data["y"][0] = json!(true);
249    ///
250    /// // inserted a deeply nested key
251    /// data["a"]["b"]["c"]["d"] = json!(true);
252    ///
253    /// println!("{}", data);
254    /// ```
255    fn index_mut(&mut self, index: I) -> &mut Value {
256        index.index_or_insert(self)
257    }
258}
serde_json/value/index.rs

serde_json/value/
index.rs
