Struct Map 

pub struct Map { /* private fields */ }

A map of values.

Maps retain the order in which the entries were inserted and every key is unique. Keys can be any value, not just strings. Additionally a map holds the Order of its entries and if it’s a multimap (see is_multimap) which are passed on to formats when the map is serialized. Neither is considered when maps are compared: maps are equal if they contain the same entries. The exception are entries with maps or sequences as keys, which are compared in order (this allows comparing maps without recursion).

use deser_value::{Map, Value};

let mut map = Map::new();
map.insert("name", "Jane");
map.insert(42, true);
assert_eq!(map.get("name"), Some(&Value::from("Jane")));
assert_eq!(map.get(&42), Some(&Value::from(true)));
assert_eq!(
    map.keys().collect::<Vec<_>>(),
    [&Value::from("name"), &Value::from(42)]
);

Keys can be looked up by anything that implements MapKey, which includes strings, integers and values.

Implementations

impl Map

pub fn new() -> Map

Creates an empty map.

pub fn with_capacity(capacity: usize) -> Map

Creates an empty map with a capacity.

pub fn order(&self) -> Order

Returns the order of the entries.

pub fn set_order(&mut self, order: Order)

Sets the order of the entries.

pub fn is_multimap(&self) -> bool

Returns true if the map is a multimap.

Maps that are deserialized from multimaps (like query strings, see ContainerShape::set_multimap) are multimaps. The values of a key that was given more than once are a Seq marked as repeated. When the map is deserialized into another type, it’s a multimap again and the values of repeated keys are passed on as the values of repeated keys. A key that was given once is a single value, so types that collect the values of keys (like Vec<T>) receive the same values as from the original input.

use deser_value::{Map, Seq, Value};

#[derive(deser::Deserialize, Debug, PartialEq)]
struct Query {
    tag: Vec<String>,
    page: Vec<u32>,
}

let mut map = Map::new();
map.set_multimap(true);
let mut tags = Seq::from(vec![Value::from("a"), Value::from("b")]);
tags.set_repeated(true);
map.insert("tag", tags);
map.insert("page", 1);
let query: Query = deser_value::from_value(&Value::from(map)).unwrap();
assert_eq!(
    query,
    Query { tag: vec!["a".into(), "b".into()], page: vec![1] }
);

pub fn set_multimap(&mut self, yes: bool)

Sets if the map is a multimap.

pub fn is_ambiguous_empty(&self) -> bool

Returns true if the map is empty and could also be an empty sequence.

This is the counterpart of Seq::is_ambiguous_empty: types that expect a sequence receive an empty sequence. The flag has no effect once the map has entries.

pub fn set_ambiguous_empty(&mut self, yes: bool)

Sets if the map could also be an empty sequence when it’s empty.

pub fn len(&self) -> usize

Returns the number of entries.

pub fn is_empty(&self) -> bool

Returns true if the map has no entries.

pub fn get<K: MapKey + ?Sized>(&self, key: &K) -> Option<&Value>

Returns the value of a key.

pub fn get_mut<K: MapKey + ?Sized>(&mut self, key: &K) -> Option<&mut Value>

Returns the value of a key mutably.

pub fn get_key_value<K: MapKey + ?Sized>( &self, key: &K, ) -> Option<(&Value, &Value)>

Returns the key and value of a key.

This is useful to get to the meta data of the key.

pub fn get_index_of<K: MapKey + ?Sized>(&self, key: &K) -> Option<usize>

Returns the index of a key.

pub fn get_index(&self, index: usize) -> Option<(&Value, &Value)>

Returns the key and value at an index.

pub fn get_index_mut(&mut self, index: usize) -> Option<(&Value, &mut Value)>

Returns the key and the mutable value at an index.

pub fn contains_key<K: MapKey + ?Sized>(&self, key: &K) -> bool

Returns true if the map contains a key.

pub fn insert<K: Into<Value>, V: Into<Value>>( &mut self, key: K, value: V, ) -> Option<Value>

Inserts a value for a key.

If the key already exists, its value is replaced (the entry keeps its position and key) and the old value is returned. Otherwise the entry is added at the end.

pub fn get_or_insert_with<K: Into<Value>, F: FnOnce() -> Value>( &mut self, key: K, f: F, ) -> &mut Value

Returns the value of a key, inserting the result of f if the key does not exist.

pub fn remove<K: MapKey + ?Sized>(&mut self, key: &K) -> Option<Value>

Removes a key and returns its value.

The order of the remaining entries is retained.

pub fn remove_entry<K: MapKey + ?Sized>( &mut self, key: &K, ) -> Option<(Value, Value)>

Removes a key and returns it together with its value.

The order of the remaining entries is retained.

pub fn retain<F: FnMut(&Value, &mut Value) -> bool>(&mut self, f: F)

Retains the entries for which the predicate returns true.

pub fn sort_by<F>(&mut self, f: F)

where F: FnMut(&Value, &Value, &Value, &Value) -> Ordering,

Sorts the entries with a comparison function.

pub fn clear(&mut self)

Removes all entries.

pub fn iter(&self) -> Iter<'_>

Returns an iterator over the entries.

pub fn iter_mut(&mut self) -> IterMut<'_>

Returns an iterator over the entries with mutable values.

pub fn keys(&self) -> Keys<'_>

Returns an iterator over the keys.

pub fn values(&self) -> Values<'_>

Returns an iterator over the values.

pub fn values_mut(&mut self) -> ValuesMut<'_>

Returns an iterator over the mutable values.

Trait Implementations

impl Clone for Map

fn clone(&self) -> Map

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Map

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Map

fn default() -> Map

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Map

fn deserialize_update<'out>( value: &'out mut Self, state: &mut State, ) -> SinkHandle<'out, 'de>

Merges the data into the map, the values of keys that exist are replaced.

fn deserialize_into<'out>( out: &'out mut Option<Self>, state: &mut State, ) -> SinkHandle<'out, 'de>

Creates a sink that deserializes the value into the given slot.

fn expecting() -> Cow<'static, str>

Returns what the value expects, for error messages.

fn deserialize_atom( slot: &mut Slot<T, Self>, atom: Atom<'_>, state: &mut State, ) -> Result<(), Error>

Deserializes an atom into the slot.

fn deserialize_borrowed_atom( slot: &mut Slot<T, Self>, atom: Atom<'de>, state: &mut State, ) -> Result<(), Error>

Deserializes an atom that borrows from the data being deserialized into the slot.

fn describe_type(d: &mut dyn Describe)

Describes the Rust shape of the type.

fn initial_value() -> Option<T>

Provides the value of a missing struct field.

impl Drop for Map

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Eq for Map

impl<K: Into<Value>, V: Into<Value>> Extend<(K, V)> for Map

fn extend<I: IntoIterator<Item = (K, V)>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<Map> for Value

fn from(value: Map) -> Value

Converts to this type from the input type.

impl<K: Into<Value>, V: Into<Value>> FromIterator<(K, V)> for Map

fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Map

Creates a value from an iterator.

impl Hash for Map

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoIterator for Map

type Item = (Value, Value)

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a Map

type Item = (&'a Value, &'a Value)

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Map

type Item = (&'a Value, &'a mut Value)

The type of the elements being iterated over.

type IntoIter = IterMut<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IterMut<'a>

Creates an iterator from a value.

impl PartialEq for Map

fn eq(&self, other: &Map) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Map

fn serialize<'a>(this: &'a Self, state: &mut State) -> Result<Emit<'a>, Error>

Serializes the value.

fn container_shape(value: &Self) -> ContainerShape

Returns the shape of the value if it’s a map or sequence.

fn finish(value: &T, state: &mut State) -> Result<(), Error>

Invoked after the serialization finished.

fn is_optional(value: &T) -> bool

Checks if the value represents an optional value.

fn describe(value: &T, d: &mut dyn Describe)

Describes the Rust shape of the value.