1 | use super::Value; |
2 | use crate::map::Map; |
3 | use alloc::borrow::ToOwned; |
4 | use alloc::string::String; |
5 | use core::fmt::{self, Display}; |
6 | use 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 | /// ``` |
37 | pub 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 | |
54 | impl 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 | |
83 | impl Index for str { |
84 | fn index_into<'v>(&self, v: &'v Value) -> Option<&'v Value> { |
85 | match v { |
86 | Value::Object(map: &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: &mut 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: &mut Map) => map.entry(self.to_owned()).or_insert(default:Value::Null), |
102 | _ => panic!("cannot access key {:?} in JSON {}" , self, Type(v)), |
103 | } |
104 | } |
105 | } |
106 | |
107 | impl 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 | |
119 | impl<'a, T> Index for &'a T |
120 | where |
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. |
135 | mod 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. |
144 | struct Type<'a>(&'a Value); |
145 | |
146 | impl<'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(data:"null" ), |
150 | Value::Bool(_) => formatter.write_str(data:"boolean" ), |
151 | Value::Number(_) => formatter.write_str(data:"number" ), |
152 | Value::String(_) => formatter.write_str(data:"string" ), |
153 | Value::Array(_) => formatter.write_str(data:"array" ), |
154 | Value::Object(_) => formatter.write_str(data:"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. |
178 | impl<I> ops::Index<I> for Value |
179 | where |
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 | |
218 | impl<I> ops::IndexMut<I> for Value |
219 | where |
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 | |