Struct AnyDictionary

pub struct AnyDictionary { /* private fields */ }

Expand description

Covariant Dictionary that can be typed or untyped.

Unlike Dictionary<K, V>, which carries compile-time type information, AnyDictionary is a type-erased version of dictionaries. It can point to any Dictionary<K, V>, for both typed and untyped dictionaries.

§Covariance

In GDScript, the subtyping relationship is modeled incorrectly for typed dictionaries:

var typed: Dictionary[String, int] = {"one": 1, "two": 2}
var untyped: Dictionary = typed   # Implicit "upcast" to Dictionary[Variant, Variant].

untyped["hello"] = "world"        # Not detected by GDScript parser (may fail at runtime).

godot-rust on the other hand introduces a new type AnyDictionary, which can store any dictionary, typed or untyped. AnyDictionary provides operations that are valid regardless of the type, e.g. len(), is_empty() or clear(). Methods which would return specific types on Dictionary<K, V> exist on AnyDictionary but return Variant.

AnyDictionary does not provide any operations where data flows into to the dictionary, such as set() or insert(). Note that this does not mean that AnyDictionary is an immutable view; mutating methods that are agnostic to element types (or where data only flows out), are still available. Examples are clear() and remove().

§Conversions

Use try_cast_dictionary::<K, V>() to convert to a typed Dictionary<K, V>.
Use try_cast_var_dictionary() to convert to an untyped VarDictionary.

Implementations§

§

impl AnyDictionary

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

⚠️ Returns the value for the given key, or panics.

To check for presence, use get().

§Panics

If there is no value for the given key. Note that this is distinct from a NIL value, which is returned as Variant::nil().

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.

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 len(&self) -> usize

Returns the number of entries in the dictionary.

Godot equivalent: size

pub fn is_empty(&self) -> bool

Returns true if the dictionary is empty.

pub fn hash_u32(&self) -> u32

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

Dictionaries with equal content will always produce identical hash values. However, the reverse is not true: Different dictionaries can have identical hash values due to hash collisions.

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(key) if found.

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.

Godot equivalent: find_key

pub fn clear(&mut self)

Removes all key-value pairs from the dictionary.

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

Removes a key from the dictionary, and returns the value associated with the key if it was present.

This is a covariant-safe operation that removes data without adding typed data.

Godot equivalent: erase

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

Alias for remove().

Godot equivalent: erase

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 duplicate_shallow(&self) -> AnyDictionary

Returns a shallow copy, sharing reference types (Array, Dictionary, Object…) with the original dictionary.

This operation retains the dynamic key/value types: copying Dictionary<K, V> will yield another Dictionary<K, V>.

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

pub fn duplicate_deep(&self) -> AnyDictionary

Returns a deep copy, duplicating nested Array/Dictionary elements but keeping Object elements shared.

This operation retains the dynamic key/value types: copying Dictionary<K, V> will yield another Dictionary<K, V>.

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

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 in the Dictionary.

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

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 into_read_only(self) -> AnyDictionary

Turns the dictionary into a shallow-immutable dictionary.

Makes the dictionary read-only and returns the original dictionary. Disables modification of the dictionary’s contents. Does not apply to nested content, e.g. elements of nested dictionaries.

In GDScript, dictionaries are automatically read-only if declared with the const keyword.

Godot equivalent: make_read_only

pub fn is_read_only(&self) -> bool

Returns true if the dictionary is read-only.

See into_read_only().

pub fn key_element_type(&self) -> ElementType

Returns the runtime element type information for keys in this dictionary.

The result is generally cached, so feel free to call this method repeatedly.

pub fn value_element_type(&self) -> ElementType

Returns the runtime element type information for values in this dictionary.

The result is generally cached, so feel free to call this method repeatedly.

pub fn try_cast_dictionary<K, V>( self, ) -> Result<Dictionary<K, V>, AnyDictionary>
where K: ArrayElement, V: ArrayElement,

Converts to Dictionary<K, V> if the runtime types match.

If K=Variant and V=Variant, this will attempt to “downcast” to an untyped dictionary, identical to try_cast_var_dictionary().

Returns Err(self) if the dictionary’s dynamic types differ from K and V. Check key_element_type() and value_element_type() before calling to determine what types the dictionary actually holds.

Consumes self, to avoid incrementing reference-count and to be only callable on AnyDictionary, not Dictionary. Use clone() if you need to keep the original.