Struct Map

Source

pub struct Map<'ctx>(/* private fields */);

Expand description

Represents a JSON key/value type.

For performance reasons we use a Vec instead of a Hashmap. This comes with a tradeoff of slower key accesses as we need to iterate and compare.

The ObjectAsVec struct is a wrapper around a Vec of (&str, Value) pairs. It provides methods to make it easy to migrate from serde_json::Value::Object or serde_json::Map.

Implementations§

Source §

impl<'ctx> ObjectAsVec<'ctx>

Source

pub fn as_vec(&self) -> &Vec<(KeyStrType<'_>, Value<'ctx>)>

Access to the underlying Vec.

§Note

Since KeyStrType can be changed via a feature flag avoid using as_vec and use other methods instead. This could be a problem with feature unification, when one crate uses it as &str and another uses it as Cow<str>, both will get Cow<str>

Source

pub fn into_vec(self) -> Vec<(Cow<'ctx, str>, Value<'ctx>)>

Access to the underlying Vec. Keys are normalized to Cow.

Source

pub fn get(&self, key: &str) -> Option<&Value<'ctx>>

Returns a reference to the value corresponding to the key.

§Performance

As this is backed by a Vec, this searches linearly through the Vec as may be much more expensive than a Hashmap for larger Objects.

Source

pub fn get_mut(&mut self, key: &str) -> Option<&mut Value<'ctx>>

Returns a mutable reference to the value corresponding to the key, if it exists.

§Performance

As this is backed by a Vec, this searches linearly through the Vec as may be much more expensive than a Hashmap for larger Objects.

Source

pub fn get_key_value(&self, key: &str) -> Option<(&str, &Value<'ctx>)>

Returns the key-value pair corresponding to the supplied key.

§Performance

As this is backed by a Vec, this searches linearly through the Vec as may be much more expensive than a Hashmap for larger Objects.

Source

pub fn get_entry(&self, key: &str) -> Option<ObjectEntry<'_, 'ctx>>

Finds an ObjectEntry in the Map by key.

This method allows you to obtain both the value and its position in the underlying Vec.

Similar to ObjectAsVec::get_key_value, but returns an ObjectEntry instead of a tuple.

§Performance

As this is backed by a Vec, this searches linearly through the Vec as may be much more expensive than a Hashmap for larger Objects.

The returned index can be used with ObjectAsVec::get_key_value_at for future O(1) access.

§Example

let entry = obj.get_entry("name").unwrap();
println!("Found '{}={}' at index {}", entry.key, entry.value, entry.index);

Source

pub fn get_key_value_at(&self, index: usize) -> Option<(&str, &Value<'ctx>)>

Retrieves an entry directly by its index in the underlying Vec.

This method provides O(1) access to entries when the index is known, avoiding the linear search required by ObjectAsVec::get_key_value if you have already looked up the entry using ObjectAsVec::get_entry or otherwise have found its index.

§Examples

let entry = obj.get_entry("name").unwrap();
if let Some((key, value)) = obj.get_key_value_at(entry.index) {
    println!("Found entry: {} = {:?}", key, value);
}

Source

pub fn iter(&self) -> impl Iterator<Item = (&str, &Value<'ctx>)>

An iterator visiting all key-value pairs

Source

pub fn len(&self) -> usize

Returns the number of elements in the object

Source

pub fn is_empty(&self) -> bool

Returns true if the object contains no elements

Source

pub fn keys(&self) -> impl Iterator<Item = &str>

An iterator visiting all keys

Source

pub fn values(&self) -> impl Iterator<Item = &Value<'ctx>>

An iterator visiting all values

Source

pub fn contains_key(&self, key: &str) -> bool

Returns true if the object contains a value for the specified key.

§Performance

As this is backed by a Vec, this searches linearly through the Vec as may be much more expensive than a Hashmap for larger Objects.

Source

pub fn insert( &mut self, key: &'ctx str, value: Value<'ctx>, ) -> Option<Value<'ctx>>

Inserts a key-value pair into the object. If the object did not have this key present, None is returned. If the object did have this key present, the value is updated, and the old value is returned.

§Performance

This operation is linear in the size of the Vec because it potentially requires iterating through all elements to find a matching key.

Source

pub fn insert_or_get_mut( &mut self, key: &'ctx str, value: Value<'ctx>, ) -> &mut Value<'ctx>

Inserts a key-value pair into the object if the key does not yet exist, otherwise returns a mutable reference to the existing value.

§Performance

This operation might be linear in the size of the Vec because it requires iterating through all elements to find a matching key, and might add to the end if not found.

Source

pub fn insert_unchecked_and_get_mut( &mut self, key: &'ctx str, value: Value<'ctx>, ) -> &mut Value<'ctx>

Inserts a key-value pair into the object and returns the mutable reference of the inserted value.

§Note

The key must not exist in the object. If the key already exists, the object will contain multiple keys afterwards.

§Performance

This operation is amortized constant time, worst case linear time in the size of the Vec because it potentially requires a reallocation to grow the Vec.