| 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.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 |
|
| 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<T> Index for &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("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. |
| 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 |
} |