Struct Dictionary
pub struct Dictionary { /* private fields */ }
Expand description
Godot’s Dictionary
type.
The keys and values of the dictionary are all Variant
s, so they can be of different types.
Variants are designed to be generally cheap to clone.
§Dictionary example
// Create empty dictionary and add key-values pairs.
let mut dict = Dictionary::new();
dict.set("str", "Hello");
dict.set("num", 23);
// Keys don't need to be strings.
let coord = Vector2i::new(0, 1);
dict.set(coord, "Tile77");
// Or create the same dictionary in a single expression.
let dict = dict! {
"str": "Hello",
"num": 23,
coord: "Tile77",
};
// Access elements.
let value: Variant = dict.at("str");
let value: GString = dict.at("str").to(); // Variant::to() extracts GString.
let maybe: Option<Variant> = dict.get("absent_key");
// Iterate over key-value pairs as (Variant, Variant).
for (key, value) in dict.iter_shared() {
println!("{key} => {value}");
}
// Use typed::<K, V>() to get typed iterators.
for (key, value) in dict.iter_shared().typed::<GString, Variant>() {
println!("{key} => {value}");
}
// Clone dictionary (shares the reference), and overwrite elements through clone.
let mut cloned = dict.clone();
cloned.remove("num");
// Overwrite with set(); use insert() to get the previous value.
let prev = cloned.insert("str", "Goodbye"); // prev == Some("Hello")
// Changes will be reflected in the original dictionary.
assert_eq!(dict.at("str"), "Goodbye".to_variant());
assert_eq!(dict.get("num"), None);
§Thread safety
The same principles apply as for VariantArray
. Consult its documentation for details.
§Godot docs
Implementations§
§impl Dictionary
impl Dictionary
pub fn new() -> Dictionary
pub fn new() -> Dictionary
Constructs an empty Dictionary
.
pub fn at<K>(&self, key: K) -> Variantwhere
K: ToGodot,
pub fn at<K>(&self, key: K) -> Variantwhere
K: ToGodot,
⚠️ Returns the value for the given key, or panics.
If you want to check for presence, use get()
or get_or_nil()
.
§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,
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 get_or_nil()
.
When you are certain that a key is present, use at()
instead.
This can be combined with Rust’s Option
methods, e.g. dict.get(key).unwrap_or(default)
.
pub fn get_or_nil<K>(&self, key: K) -> Variantwhere
K: ToGodot,
pub fn get_or_nil<K>(&self, key: K) -> Variantwhere
K: ToGodot,
pub fn contains_key<K>(&self, key: K) -> boolwhere
K: ToGodot,
pub fn contains_key<K>(&self, key: K) -> boolwhere
K: ToGodot,
Returns true
if the dictionary contains the given key.
Godot equivalent: has
pub fn contains_all_keys(&self, keys: &Array<Variant>) -> bool
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 find_key_by_value<V>(&self, value: V) -> Option<Variant>where
V: ToGodot,
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 clear(&mut self)
pub fn clear(&mut self)
Removes all key-value pairs from the dictionary.
pub fn set<K, V>(&mut self, key: K, value: V)
pub fn set<K, V>(&mut self, key: K, value: V)
Set a key to a given value.
If you are interested in the previous value, use insert()
instead.
Godot equivalent: dict[key] = value
pub fn insert<K, V>(&mut self, key: K, value: V) -> Option<Variant>
pub fn insert<K, V>(&mut self, key: K, value: V) -> Option<Variant>
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 set()
instead.
pub fn remove<K>(&mut self, key: K) -> Option<Variant>where
K: ToGodot,
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 hash(&self) -> u32
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>
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>
pub fn values_array(&self) -> Array<Variant>
Creates a new Array
containing all the values currently in the dictionary.
Godot equivalent: values
pub fn extend_dictionary(&mut self, other: &Dictionary, overwrite: bool)
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 duplicate_deep(&self) -> Dictionary
pub fn duplicate_deep(&self) -> Dictionary
Deep copy, duplicating nested collections.
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
pub fn duplicate_shallow(&self) -> Dictionary
Shallow copy, copying elements but sharing nested collections.
All dictionary keys and values are copied, but any reference types (such as Array
, Dictionary
and Gd<T>
objects)
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)
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.
Use dict.iter_shared().typed::<K, V>()
to iterate over (K, V)
pairs instead.
Returns an iterator over the keys in a 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.
Use dict.keys_shared().typed::<K>()
to iterate over K
keys instead.
Trait Implementations§
§impl ArrayElement for Dictionary
impl ArrayElement for Dictionary
fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError>
§impl Clone for Dictionary
impl Clone for Dictionary
Creates a new reference to the data in this dictionary. Changes to the original dictionary will be reflected in the copy and vice versa.
To create a (mostly) independent copy instead, see Dictionary::duplicate_shallow()
and
Dictionary::duplicate_deep()
.
§fn clone(&self) -> Dictionary
fn clone(&self) -> Dictionary
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more§impl Debug for Dictionary
impl Debug for Dictionary
§impl Default for Dictionary
impl Default for Dictionary
§fn default() -> Dictionary
fn default() -> Dictionary
§impl Display for Dictionary
impl Display for Dictionary
§impl Export for Dictionary
impl Export for Dictionary
§fn export_hint() -> PropertyHintInfo
fn export_hint() -> PropertyHintInfo
§fn as_node_class() -> Option<ClassName>
fn as_node_class() -> Option<ClassName>
§impl<K, V> Extend<(K, V)> for Dictionary
impl<K, V> Extend<(K, V)> for Dictionary
Insert iterator range into dictionary.
Inserts all key-value pairs from the iterator into the dictionary. Previous values for keys appearing
in iter
will be overwritten.
§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = (K, V)>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = (K, V)>,
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)§impl<'a, 'b, K, V, I> From<I> for Dictionary
impl<'a, 'b, K, V, I> From<I> for Dictionary
Creates a dictionary from the given iterator I
over a (&K, &V)
key-value pair.
Each key and value are converted to a Variant
.
§fn from(iterable: I) -> Dictionary
fn from(iterable: I) -> Dictionary
§impl FromGodot for Dictionary
impl FromGodot for Dictionary
§fn try_from_godot(
via: <Dictionary as GodotConvert>::Via,
) -> Result<Dictionary, ConvertError>
fn try_from_godot( via: <Dictionary as GodotConvert>::Via, ) -> Result<Dictionary, ConvertError>
Err
on failure.§fn from_godot(via: Self::Via) -> Self
fn from_godot(via: Self::Via) -> Self
§fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>
fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>
Variant
, returning Err
on failure.§fn from_variant(variant: &Variant) -> Self
fn from_variant(variant: &Variant) -> Self
§impl<K, V> FromIterator<(K, V)> for Dictionary
impl<K, V> FromIterator<(K, V)> for Dictionary
§fn from_iter<I>(iter: I) -> Dictionarywhere
I: IntoIterator<Item = (K, V)>,
fn from_iter<I>(iter: I) -> Dictionarywhere
I: IntoIterator<Item = (K, V)>,
§impl GodotConvert for Dictionary
impl GodotConvert for Dictionary
§type Via = Dictionary
type Via = Dictionary
Self
is represented in Godot.§impl PartialEq for Dictionary
impl PartialEq for Dictionary
§impl ToGodot for Dictionary
impl ToGodot for Dictionary
§type ToVia<'v> = <Dictionary as GodotConvert>::Via
type ToVia<'v> = <Dictionary as GodotConvert>::Via
to_godot()
, which differs from Via
for pass-by-reference types.§fn to_godot(&self) -> <Dictionary as ToGodot>::ToVia<'_>
fn to_godot(&self) -> <Dictionary as ToGodot>::ToVia<'_>
§fn to_variant(&self) -> Variant
fn to_variant(&self) -> Variant
§impl Var for Dictionary
impl Var for Dictionary
fn get_property(&self) -> <Dictionary as GodotConvert>::Via
fn set_property(&mut self, value: <Dictionary as GodotConvert>::Via)
§fn var_hint() -> PropertyHintInfo
fn var_hint() -> PropertyHintInfo
GodotType::property_info
, e.g. for enums/newtypes.impl GodotType for Dictionary
Auto Trait Implementations§
impl Freeze for Dictionary
impl RefUnwindSafe for Dictionary
impl !Send for Dictionary
impl !Sync for Dictionary
impl Unpin for Dictionary
impl UnwindSafe for Dictionary
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)