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
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<'a, T> Sealed for &'a 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}
259