Struct gdnative::prelude::Dictionary

pub struct Dictionary<Own = Shared>where
    Own: Ownership,{ /* private fields */ }

A reference-counted Dictionary of Variant key-value pairs.

Generic methods on this type performs Variant conversion every time. This could be significant for complex structures. Users may convert arguments to Variants before calling to avoid this behavior if necessary.

Safety

This is a reference-counted collection with “interior mutability” in Rust parlance. To enforce that the official thread-safety guidelines are followed this type uses the typestate pattern. The typestate Ownership tracks whether there is thread-local or unique access (where pretty much all operations are safe) or whether the value might be “shared”, in which case not all operations are safe.

Implementations

impl<Own> Dictionary<Own>where
    Own: Ownership,

Operations allowed on all Dictionaries at any point in time.

pub fn is_empty(&self) -> bool

Returns true if the Dictionary contains no elements.

pub fn len(&self) -> i32

Returns the number of elements in the Dictionary.

pub fn contains<K>(&self, key: K) -> boolwhere
    K: OwnedToVariant + ToVariantEq,

Returns true if the Dictionary contains the specified key.

pub fn contains_all<ArrayOws>(&self, keys: &VariantArray<ArrayOws>) -> boolwhere
    ArrayOws: Ownership,

Returns true if the Dictionary has all of the keys in the given array.

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

Returns a copy of the value corresponding to the key if it exists.

pub fn get_or<K, D>(&self, key: K, default: D) -> Variantwhere
    K: OwnedToVariant + ToVariantEq,
    D: OwnedToVariant,

Returns a copy of the value corresponding to the key, or default if it doesn’t exist

pub fn get_or_nil<K>(&self, key: K) -> Variantwhere
    K: OwnedToVariant + ToVariantEq,

Returns a copy of the element corresponding to the key, or Nil if it doesn’t exist. Shorthand for self.get_or(key, Variant::nil()).

pub fn update<K, V>(&self, key: K, val: V)where
    K: OwnedToVariant + ToVariantEq,
    V: OwnedToVariant,

Update an existing element corresponding to the key.

Panics

Panics if the entry for key does not exist.

pub unsafe fn get_ref<K>(&self, key: K) -> &Variantwhere
    K: OwnedToVariant + ToVariantEq,

Returns a reference to the value corresponding to the key, inserting a Nil value first if it does not exist.

Safety

The returned reference is invalidated if the same container is mutated through another reference, and other references may be invalidated if the entry does not already exist (which causes this function to insert Nil and thus possibly re-allocate).

Variant is reference-counted and thus cheaply cloned. Consider using get instead.

pub unsafe fn get_mut_ref<K>(&self, key: K) -> &mut Variantwhere
    K: OwnedToVariant + ToVariantEq,

Returns a mutable reference to the value corresponding to the key, inserting a Nil value first if it does not exist.

Safety

The returned reference is invalidated if the same container is mutated through another reference, and other references may be invalidated if the key does not already exist (which causes this function to insert Nil and thus possibly re-allocate). It is also possible to create two mutable references to the same memory location if the same key is provided, causing undefined behavior.

pub fn to_json(&self) -> GodotString

Returns a GodotString of the Dictionary.

pub fn keys(&self) -> VariantArray<Unique>

Returns an array of the keys in the Dictionary.

pub fn values(&self) -> VariantArray<Unique>

Returns an array of the values in the Dictionary.

pub fn hash(&self) -> i32

Return a hashed i32 value representing the dictionary’s contents.

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

Returns an iterator through all key-value pairs in the Dictionary.

Dictionary is reference-counted and have interior mutability in Rust parlance. Modifying the same underlying collection while observing the safety assumptions will not violate memory safely, but may lead to surprising behavior in the iterator.

pub fn duplicate(&self) -> Dictionary<Unique>

Create a copy of the dictionary.

This creates a new dictionary and is not a cheap reference count increment.

impl Dictionary<Shared>

Operations allowed on Dictionaries that might be shared between different threads.

pub fn new_shared() -> Dictionary<Shared>

Create a new shared dictionary.

impl Dictionary<ThreadLocal>

Operations allowed on Dictionaries that may only be shared on the current thread.

pub fn new_thread_local() -> Dictionary<ThreadLocal>

Create a new thread-local dictionary.

impl<Own> Dictionary<Own>where
    Own: NonUniqueOwnership,

Operations allowed on Dictionaries that are not unique.

pub unsafe fn assume_unique(self) -> Dictionary<Unique>

Assume that this is the only reference to this dictionary, on which operations that change the container size can be safely performed.

Safety

It isn’t thread-safe to perform operations that change the container size from multiple threads at the same time. Creating multiple Unique references to the same collections, or violating the thread-safety guidelines in non-Rust code will cause undefined behavior.

impl<Own> Dictionary<Own>where
    Own: LocalThreadOwnership,

Operations allowed on Dictionaries that can only be referenced to from the current thread.

pub fn insert<K, V>(&self, key: K, val: V)where
    K: OwnedToVariant + ToVariantEq,
    V: OwnedToVariant,

Inserts or updates the value of the element corresponding to the key.

pub fn erase<K>(&self, key: K)where
    K: OwnedToVariant + ToVariantEq,

Erase a key-value pair in the Dictionary by the specified key.

pub fn clear(&self)

Clears the Dictionary, removing all key-value pairs.

impl Dictionary<Unique>

Operations allowed on unique Dictionaries.

pub fn new() -> Dictionary<Unique>

Creates an empty Dictionary.

pub fn into_shared(self) -> Dictionary<Shared>

Put this dictionary under the “shared” access type.

pub fn into_thread_local(self) -> Dictionary<ThreadLocal>

Put this dictionary under the “thread-local” access type.

Trait Implementations

impl CoerceFromVariant for Dictionary<Shared>

fn coerce_from_variant(v: &Variant) -> Dictionary<Shared>

impl<Own> Debug for Dictionary<Own>where
    Own: Ownership,

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

Formats the value using the given formatter.

impl Default for Dictionary<Shared>

fn default() -> Dictionary<Shared>

Returns the “default value” for a type.

impl Default for Dictionary<ThreadLocal>

fn default() -> Dictionary<ThreadLocal>

Returns the “default value” for a type.

impl Default for Dictionary<Unique>

fn default() -> Dictionary<Unique>

Returns the “default value” for a type.

impl<Own> Drop for Dictionary<Own>where
    Own: Ownership,

fn drop(&mut self)

Executes the destructor for this type.

impl Export for Dictionary<Shared>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(
    _hint: Option<<Dictionary<Shared> as Export>::Hint>
) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl<K, V, Own> Extend<(K, V)> for Dictionary<Own>where
    Own: LocalThreadOwnership,
    K: ToVariantEq + OwnedToVariant,
    V: OwnedToVariant,

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

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬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<Dictionary<Unique>> for Dictionary<Shared>

fn from(dict: Dictionary<Unique>) -> Dictionary<Shared>

Converts to this type from the input type.

impl From<Dictionary<Unique>> for Dictionary<ThreadLocal>

fn from(dict: Dictionary<Unique>) -> Dictionary<ThreadLocal>

Converts to this type from the input type.

impl<K, V> FromIterator<(K, V)> for Dictionary<Unique>where
    K: ToVariantEq + OwnedToVariant,
    V: OwnedToVariant,

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

Creates a value from an iterator.

impl FromVariant for Dictionary<Shared>

fn from_variant(
    variant: &Variant
) -> Result<Dictionary<Shared>, FromVariantError>

impl<'a, Own> IntoIterator for &'a Dictionary<Own>where
    Own: Ownership,

type Item = (Variant, Variant)

The type of the elements being iterated over.

type IntoIter = Iter<'a, Own>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a Dictionary<Own> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl IntoIterator for Dictionary<Unique>

type Item = (Variant, Variant)

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> <Dictionary<Unique> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<Own> NewRef for Dictionary<Own>where
    Own: NonUniqueOwnership,

fn new_ref(&self) -> Dictionary<Own>

Creates a new reference to the underlying object.

impl OwnedToVariant for Dictionary<Unique>

fn owned_to_variant(self) -> Variant

impl ToVariant for Dictionary<Shared>

fn to_variant(&self) -> Variant