Struct godot::prelude::Dictionary

pub struct Dictionary { /* private fields */ }

Expand description

Godot’s Dictionary type.

The keys and values of the dictionary are all Variants, so they can be of different types. Variants are designed to be generally cheap to clone.

§Thread safety

The same principles apply as for VariantArray. Consult its documentation for details.

Implementations§

§

impl Dictionary

pub fn clear(&mut self)

Removes all key-value pairs from the dictionary.

pub fn duplicate_deep(&self) -> Dictionary

Returns a deep copy of the dictionary. All nested arrays and dictionaries are duplicated and will not be shared with the original dictionary. Note that any Object-derived elements will still be shallow copied.

To create a shallow copy, use Self::duplicate_shallow() instead. To create a new reference to the same dictionary data, use clone().

Godot equivalent: dict.duplicate(true)

pub fn duplicate_shallow(&self) -> Dictionary

Returns a shallow copy of the dictionary. All dictionary keys and values are copied, but any reference types (such as Array, Dictionary and Object) will still refer to the same value.

To create a deep copy, use Self::duplicate_deep() instead. To create a new reference to the same dictionary data, use clone().

Godot equivalent: dict.duplicate(false)

pub fn remove<K>(&mut self, key: K) -> Option<Variant>
where K: ToGodot,

Removes a key from the map, and returns the value associated with the key if the key was in the dictionary.

Godot equivalent: erase

pub fn find_key_by_value<V>(&self, value: V) -> Option<Variant>
where V: ToGodot,

Reverse-search a key by its value.

Unlike Godot, this will return None if the key does not exist and Some(Variant::nil()) the key is NIL.

This operation is rarely needed and very inefficient. If you find yourself needing it a lot, consider using a HashMap or Dictionary with the inverse mapping (V -> K).

Godot equivalent: find_key

pub fn get<K>(&self, key: K) -> Option<Variant>
where K: ToGodot,

Returns the value for the given key, or None.

Note that NIL values are returned as Some(Variant::nil()), while absent values are returned as None. If you want to treat both as NIL, use Self::get_or_nil.

pub fn get_or_nil<K>(&self, key: K) -> Variant
where K: ToGodot,

Returns the value at the key in the dictionary, or NIL otherwise.

This method does not let you differentiate NIL values stored as values from absent keys. If you need that, use Self::get.

Godot equivalent: dict.get(key, null)

pub fn contains_key<K>(&self, key: K) -> bool
where K: ToGodot,

Returns true if the dictionary contains the given key.

Godot equivalent: has

pub fn contains_all_keys(&self, keys: Array<Variant>) -> bool

Returns true if the dictionary contains all the given keys.

Godot equivalent: has_all

pub fn hash(&self) -> u32

Returns a 32-bit integer hash value representing the dictionary and its contents.

pub fn keys_array(&self) -> Array<Variant>

Creates a new Array containing all the keys currently in the dictionary.

Godot equivalent: keys

pub fn values_array(&self) -> Array<Variant>

Creates a new Array containing all the values currently in the dictionary.

Godot equivalent: values

pub fn is_empty(&self) -> bool

Returns true if the dictionary is empty.

pub fn extend_dictionary(&mut self, other: Dictionary, overwrite: bool)

Copies all keys and values from other into self.

If overwrite is true, it will overwrite pre-existing keys.

Godot equivalent: merge

pub fn len(&self) -> usize

Returns the number of entries in the dictionary.

This is equivalent to size in Godot.

pub fn insert<K, V>(&mut self, key: K, value: V) -> Option<Variant>
where K: ToGodot, V: ToGodot,

Insert a value at the given key, returning the previous value for that key (if available).

If you don’t need the previous value, use Self::set instead.

pub fn set<K, V>(&mut self, key: K, value: V)
where K: ToGodot, V: ToGodot,

Set a key to a given value.

If you are interested in the previous value, use Self::insert instead.

Godot equivalent: dict[key] = value

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

Returns an iterator over the key-value pairs of the Dictionary. The pairs are each of type (Variant, Variant). Each pair references the original Dictionary, but instead of a &-reference to key-value pairs as you might expect, the iterator returns a (cheap, shallow) copy of each key-value pair.

Note that it’s possible to modify the Dictionary through another reference while iterating over it. This will not result in unsoundness or crashes, but will cause the iterator to behave in an unspecified way.

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

Returns an iterator over the keys Dictionary. The keys are each of type Variant. Each key references the original Dictionary, but instead of a &-reference to keys pairs as you might expect, the iterator returns a (cheap, shallow) copy of each key pair.

Note that it’s possible to modify the Dictionary through another reference while iterating over it. This will not result in unsoundness or crashes, but will cause the iterator to behave in an unspecified way.