Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Dictionary

Una struttura dati incorporata che contiene coppie chiave-valore.

Descrizione

I dizionari sono contenitori associativi che contengono valori riferiti con chiavi univoche. I dizionari manterranno l'ordine di inserimento quando si aggiungono nuove voci. In altri linguaggi di programmazione, questa struttura dati è spesso definita come mappa hash o array associativo.

Puoi definire un dizionario inserendo un elenco separato da virgole di coppie key: value all'interno di parentesi graffe {}.

Creazione di un dizionario:

var my_dict = {} # Crea un dizionario vuoto.

var dict_variable_key = "Another key name"
var dict_variable_value = "value2"
var another_dict = {
    "Some key name": "value1",
    dict_variable_key: dict_variable_value,
}

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }

# Sintassi alternativa in stile Lua.
# Non richiede virgolette attorno alle chiavi, ma solo le stringe costanti possono essere utilizzate come nomi di chiave.
# Inoltre, i nomi di chiavi devono iniziare con una lettera o un trattino basso.
# Qui, `some_key` è una stringa letterale, non una variabile!
another_dict = {
    some_key = 42,
}

var myDict = new Godot.Collections.Dictionary(); // Crea un dizionario vuoto.
var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 }
};

È possibile accedere al valore di un dizionario facendo riferimento alla chiave corrispondente. Nell'esempio precedente, points_dict["White"] restituirà 50. Puoi anche scrivere points_dict.White, che è equivalente. Tuttavia, dovrai usare la sintassi tra parentesi se la chiave con cui accedi al dizionario non è una stringa fissa (come un numero o una variabile).

@export_enum("White", "Yellow", "Orange") var my_color: String
var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
func _ready():
    # Non possiamo usare la sintassi con i punti qui perché `my_color` è una variabile.
    var points = points_dict[my_color]

[Export(PropertyHint.Enum, "White,Yellow,Orange")]
public string MyColor { get; set; }
private Godot.Collections.Dictionary _pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 }
};

public override void _Ready()
{
    int points = (int)_pointsDict[MyColor];
}

Nel codice sopra, a points verrà assegnato il valore associato al colore appropriato selezionato in my_color.

I dizionari possono contenere dati più complessi:

var my_dict = {
    "First Array": [1, 2, 3, 4] # Assegna un Array a una chiave String.
}

var myDict = new Godot.Collections.Dictionary
{
    {"First Array", new Godot.Collections.Array{1, 2, 3, 4}}
};

Per aggiungere una chiave a un dizionario esistente, accedi ad essa come a una chiave esistente e assegnale:

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
points_dict["Blue"] = 150 # Aggiungi "Blue" come chiave e assegna 150 come valore.

var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 }
};
pointsDict["Blue"] = 150; // Aggiungi "Blue" come chiave e assegna 150 come valore.

Infine, i dizionari non tipizzati possono contenere diversi tipi di chiavi e valori nello stesso dizionario:

# Questo è un dizionario valido.
# Per accedere alla stringa "Nested value" di seguito, usa `my_dict.sub_dict.sub_key` o `my_dict["sub_dict"]["sub_key"]`.
# Gli stili di indicizzazione possono essere mescolati e abbinati in base alle tue esigenze.
var my_dict = {
    "String Key": 5,
    4: [1, 2, 3],
    7: "Hello",
    "sub_dict": { "sub_key": "Nested value" },
}

// Questo è un dizionario valido.
// Per accedere alla stringa "Nested value" qui sotto, usa `((Godot.Collections.Dictionary)myDict["sub_dict"])["sub_key"]`.
var myDict = new Godot.Collections.Dictionary {
    { "String Key", 5 },
    { 4, new Godot.Collections.Array{1,2,3} },
    { 7, "Hello" },
    { "sub_dict", new Godot.Collections.Dictionary{ { "sub_key", "Nested value" } } }
};

Le chiavi di un dizionario possono essere iterate con la parola chiave for:

var groceries = { "Orange": 20, "Apple": 2, "Banana": 4 }
for fruit in groceries:
    var amount = groceries[fruit]

var groceries = new Godot.Collections.Dictionary{ { "Orange", 20 }, { "Apple", 2 }, { "Banana", 4 } };
foreach (var (fruit, amount) in groceries)
{
    // `fruit` è la chiave, `amount` è il valore.
}

Per imporre un determinato tipo per le chiavi e i valori, è possibile creare un dizionario tipizzato. I dizionari tipizzati possono contenere solo chiavi e valori dei tipi specificati o che ereditano dalle classi specificate:

# Crea un dizionario tipizzato con chiavi String e valori int.
# Utilizzare qualsiasi altro tipo per le chiavi o i valori genererà un errore.
var typed_dict: Dictionary[String, int] = {
    "some_key": 1,
    "some_other_key": 2,
}

# Crea un dizionario tipizzato con chiavi String e valori di qualsiasi tipo.
# Utilizzare qualsiasi altro tipo per le chiavi genererà un errore.
var typed_dict_key_only: Dictionary[String, Variant] = {
    "some_key": 12.34,
    "some_other_key": "string",
}

// Crea un dizionario tipizzato con chiavi String e valori int.
// Utilizzare qualsiasi altro tipo per le chiavi o i valori genererà un errore.
var typedDict = new Godot.Collections.Dictionary<String, int> {
    {"some_key", 1},
    {"some_other_key", 2},
};

// Crea un dizionario tipizzato con chiavi String e valori di qualsiasi tipo.
// Utilizzare qualsiasi altro tipo per le chiavi genererà un errore.
var typedDictKeyOnly = new Godot.Collections.Dictionary<String, Variant> {
    {"some_key", 12.34},
    {"some_other_key", "string"},
};

Nota: I dizionari sono sempre passati per riferimento. Per ottenere una copia di un dizionario che si può modificare indipendentemente dal dizionario originale, usa duplicate().

Nota: Rimuovere elementi durante un'iterazione su un dizionario non è supportato e causerà comportamenti imprevedibili.

Nota: In un contesto booleano, un dizionario sarà valutato come false se è vuoto ({}). Altrimenti, un dizionario sarà sempre valutato come true.

Nota

Ci sono differenze sostanziali quando si usa questa API con C#. Vedi Differenze dell'API C# rispetto a GDScript per maggiori informazioni.

Tutorial

Costruttori

Dictionary	Dictionary()
Dictionary	Dictionary(base: Dictionary, key_type: int, key_class_name: StringName, key_script: Variant, value_type: int, value_class_name: StringName, value_script: Variant)
Dictionary	Dictionary(from: Dictionary)

Metodi

void	assign(dictionary: Dictionary)
void	clear()
Dictionary	duplicate(deep: bool = false) const
Dictionary	duplicate_deep(deep_subresources_mode: int = 1) const
bool	erase(key: Variant)
Variant	find_key(value: Variant) const
Variant	get(key: Variant, default: Variant = null) const
Variant	get_or_add(key: Variant, default: Variant = null)
int	get_typed_key_builtin() const
StringName	get_typed_key_class_name() const
Variant	get_typed_key_script() const
int	get_typed_value_builtin() const
StringName	get_typed_value_class_name() const
Variant	get_typed_value_script() const
bool	has(key: Variant) const
bool	has_all(keys: Array) const
int	hash() const
bool	is_empty() const
bool	is_read_only() const
bool	is_same_typed(dictionary: Dictionary) const
bool	is_same_typed_key(dictionary: Dictionary) const
bool	is_same_typed_value(dictionary: Dictionary) const
bool	is_typed() const
bool	is_typed_key() const
bool	is_typed_value() const
Array	keys() const
void	make_read_only()
void	merge(dictionary: Dictionary, overwrite: bool = false)
Dictionary	merged(dictionary: Dictionary, overwrite: bool = false) const
bool	recursive_equal(dictionary: Dictionary, recursion_count: int) const
bool	set(key: Variant, value: Variant)
int	size() const
void	sort()
Array	values() const

Operatori

bool	operator !=(right: Dictionary)
bool	operator ==(right: Dictionary)
Variant	operator [](key: Variant)

Descrizioni dei costruttori

Dictionary Dictionary() 🔗

Costruisce un Dictionary vuoto.

Dictionary Dictionary(base: Dictionary, key_type: int, key_class_name: StringName, key_script: Variant, value_type: int, value_class_name: StringName, value_script: Variant)

Crea un dizionario tipizzato dal dizionario base. Un dizionario tipizzato può contenere solo chiavi e valori dei tipi specificati, o che ereditano dalle classi specificate, come descritto dai parametri di questo costruttore.

Dictionary Dictionary(from: Dictionary)

Restituisce lo stesso dizionario di from. Se hai bisogno di una copia del dizionario, usa duplicate().

Descrizioni dei metodi

void assign(dictionary: Dictionary) 🔗

Assegna elementi di un altro dictionary in questo dizionario. Ridimensiona il dizionario per corrispondere a dictionary. Esegue le conversioni di tipo se il dizionario è tipizzato.

void clear() 🔗

Pulisce il dizionario, rimuovendo tutte le voci da esso.

Dictionary duplicate(deep: bool = false) const 🔗

Restituisce una nuova copia del dizionario.

Normalmente, viene restituita una copia superficiale: tutti gli elementi annidati di tipo Array, Dictionary e Resource sono condivisi con il dizionario originale. Modificarli in un dizionario li influenzerà anche nell'altro.

Se deep è true, viene restituita una copia profonda: anche tutti gli array e i dizionari annidati sono duplicati (ricorsivamente). Tuttavia, qualsiasi oggetto Resource rimane condiviso con il dizionario originale.

Dictionary duplicate_deep(deep_subresources_mode: int = 1) const 🔗

Duplica questo dizionario profondamente, come duplicate() quando si passa true, con più controllo su come le sotto-risorse sono gestite.

deep_subresources_mode deve essere uno dei valori di DeepDuplicateMode. Come predefinito, solo le risorse interne saranno duplicate (ricorsivamente).

bool erase(key: Variant) 🔗

Rimuove la voce del dizionario per chiave, se esiste. Restituisce true se la key specificata esisteva nel dizionario, altrimenti false.

Nota: Non rimuovere le voci durante l'iterazione sul dizionario. Puoi iterare sull'array di keys() invece.

Variant find_key(value: Variant) const 🔗

Trova e restituisce la prima chiave il cui valore associato è uguale a value, o null se non viene trovato.

Nota: Anche null è una chiave valida. Se è all'interno del dizionario, find_key() potrebbe dare risultati ingannevoli.

Variant get(key: Variant, default: Variant = null) const 🔗

Returns the corresponding value for the given key in the dictionary. If the key does not exist, returns default, or null if the parameter is omitted.

Note: If the default argument is computationally expensive or has unwanted side effects, consider using the has() method instead:

# Always calls `expensive_function()`.
dict.get("key", expensive_function())
# Calls `expensive_function()` only if the key does not exist.
dict.get("key") if dict.has("key") else expensive_function()

Variant get_or_add(key: Variant, default: Variant = null) 🔗

Ottiene un valore e assicura che la chiave sia impostata. Se la chiave key esiste nel dizionario, si comporta come get(). Altrimenti, il valore default viene inserito nel dizionario e restituito.

int get_typed_key_builtin() const 🔗

Restituisce il tipo di Variant integrato delle chiavi del dizionario tipizzato come constante di Variant.Type. Se le chiavi non sono tipizzate, restituisce @GlobalScope.TYPE_NIL. Vedi anche is_typed_key().

StringName get_typed_key_class_name() const 🔗

Restituisce il nome della classe integrata delle chiavi del dizionario tipizzato, se il tipo di Variant incorporato è @GlobalScope.TYPE_OBJECT. Altrimenti, restituisce un StringName vuoto. Vedi anche is_typed_key() e Object.get_class().

Variant get_typed_key_script() const 🔗

Restituisce l'istanza di Script associata alle chiavi di questo dizionario tipizzato, o null se non esiste. Vedi anche is_typed().

int get_typed_value_builtin() const 🔗

Restituisce il tipo di Variant integrato dei valori del dizionario tipizzato come constante di Variant.Type. Se i valori non sono tipizzati, restituisce @GlobalScope.TYPE_NIL. Vedi anche is_typed_value().

StringName get_typed_value_class_name() const 🔗

Restituisce il nome della classe integrata dei valori del dizionario tipizzato, se il tipo di Variant integrato è @GlobalScope.TYPE_OBJECT. Altrimenti, restituisce un StringName vuoto. Vedi anche is_typed_value() e Object.get_class().

Variant get_typed_value_script() const 🔗

Restituisce l'istanza di Script associata ai valori di questo dizionario tipizzato, o null se non esiste. Vedi anche is_typed_value().

bool has(key: Variant) const 🔗

Restituisce true se il dizionario contiene una voce con la key specificata.

var my_dict = {
    "Godot" : 4,
    210 : null,
}

print(my_dict.has("Godot")) # Stampa true
print(my_dict.has(210))     # Stampa true
print(my_dict.has(4))       # Stampa false

var myDict = new Godot.Collections.Dictionary
{
    { "Godot", 4 },
    { 210, default },
};

GD.Print(myDict.ContainsKey("Godot")); // Stampa True
GD.Print(myDict.ContainsKey(210));     // Stampa True
GD.Print(myDict.ContainsKey(4));       // Stampa False

In GDScript, questo è equivalente all'operatore in:

if "Godot" in { "Godot": 4 }:
    print("La chiave è qui!") # Verrà stampato.

Nota: Questo metodo restituisce true finché esiste la chiave key, anche se il suo valore corrispondente è null.

bool has_all(keys: Array) const 🔗

Restituisce true se il dizionario contiene tutte le chiavi nell'array keys specificato.

var data = { "larghezza" : 10, "altezza" : 20 }
data.has_all(["altezza", "larghezza"]) # Restituisce true

int hash() const 🔗

Restituisce un valore intero di hash a 32 bit che rappresenta il contenuto del dizionario.

var dict1 = { "A": 10, "B": 2 }
var dict2 = { "A": 10, "B": 2 }

print(dict1.hash() == dict2.hash()) # Stampa true

var dict1 = new Godot.Collections.Dictionary{ {"A", 10 }, { "B", 2 } };
var dict2 = new Godot.Collections.Dictionary{ {"A", 10 }, { "B", 2 } };

// Godot.Collections.Dictionary non ha un metodo Hash(). Usa invece GD.Hash().
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Stampa true

Nota: I dizionari con le stesse voci ma in un ordine diverso non avranno lo stesso hash.

Nota: I dizionari con valori uguali di hash non sono garantiti di essere uguali, a causa delle collisioni di hash. Al contrario, i dizionari con valori diversi di hash sono sicuramente diversi.

bool is_empty() const 🔗

Restituisce true se il dizionario è vuoto (la sua dimensione è 0). Vedi anche size().

bool is_read_only() const 🔗

Restituisce true se il dizionario è di sola lettura. Vedi make_read_only(). I dizionari sono automaticamente di sola lettura se dichiarati con la parola chiave const.

bool is_same_typed(dictionary: Dictionary) const 🔗

Restituisce true se il dizionario è tipizzato nello stesso modo di dictionary.

bool is_same_typed_key(dictionary: Dictionary) const 🔗

Restituisce true se le chiavi del dizionario sono tipizzate nello stesso modo delle chiavi di dictionary.

bool is_same_typed_value(dictionary: Dictionary) const 🔗

Restituisce true se i valori del dizionario sono tipizzati nello stesso modo dei valori di dictionary.

bool is_typed() const 🔗

Restituisce true se il dizionario è tipizzato. I dizionari tipizzati possono memorizzare solo chiavi/valori del tipo associato e fornire sicurezza di tipo per l'operatore []. I metodi del dizionario tipizzato restituiscono comunque Variant.

bool is_typed_key() const 🔗

Restituisce true se le chiavi del dizionario sono tipizzate.

bool is_typed_value() const 🔗

Restituisce true se i valori del dizionario sono tipizzati.

Array keys() const 🔗

Restituisce la lista delle chiavi nel dizionario.

void make_read_only() 🔗

Rende il dizionario di sola lettura, ovvero disabilita la modifica del contenuto del dizionario. Non si applica al contenuto innestato, ad esempio il contenuto dei dizionari innestati.

void merge(dictionary: Dictionary, overwrite: bool = false) 🔗

Aggiunge voci da dictionary a questo dizionario. Per impostazione predefinita, le chiavi duplicate non vengono copiate, a meno che overwrite non sia true.

var dict = { "item": "sword", "quantity": 2 }
var other_dict = { "quantity": 15, "color": "silver" }

# La sovrascrittura delle chiavi esistenti è disabilitata per impostazione predefinita.
dict.merge(other_dict)
print(dict)  # { "item": "sword", "quantity": 2, "color": "silver" }

# Con la sovrascrittura delle chiavi esistenti abilitata.
dict.merge(other_dict, true)
print(dict)  # { "item": "sword", "quantity": 15, "color": "silver" }

var dict = new Godot.Collections.Dictionary
{
    ["item"] = "sword",
    ["quantity"] = 2,
};

var otherDict = new Godot.Collections.Dictionary
{
    ["quantity"] = 15,
    ["color"] = "silver",
};

// La sovrascrittura delle chiavi esistenti è disabilitata per impostazione predefinita.
dict.Merge(otherDict);
GD.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" }

// Con la sovrascrittura delle chiavi esistenti abilitata.
dict.Merge(otherDict, true);
GD.Print(dict); // { "item": "sword", "quantity": 15, "color": "silver" }

Nota: merge() non è ricorsivo. I dizionari annidati sono considerati chiavi che possono essere sovrascritte o meno a seconda del valore di overwrite, ma non verranno mai uniti insieme.

Dictionary merged(dictionary: Dictionary, overwrite: bool = false) const 🔗

Restituisce una copia di questo dizionario unita all'altro dictionary. Per impostazione predefinita, le chiavi duplicate non vengono copiate, a meno che overwrite non sia true. Vedi anche merge().

Questo metodo è utile per creare rapidamente dizionari con valori predefiniti:

var base = { "fruit": "apple", "vegetable": "potato" }
var extra = { "fruit": "orange", "dressing": "vinegar" }
# Stampa { "fruit": "orange", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base))
# Stampa { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base, true))

bool recursive_equal(dictionary: Dictionary, recursion_count: int) const 🔗

Restituisce true se i due dizionari contengono le stesse chiavi e valori, le chiavi e i valori interni di tipo Dictionary e Array sono confrontati ricorsivamente.

bool set(key: Variant, value: Variant) 🔗

Imposta il valore dell'elemento alla chiave key sul valore value. Restituisce true se il valore è impostato correttamente. Fallisce e restituisce false se il dizionario è di sola lettura o se key e value non corrispondono ai tipi del dizionario. Questo equivale a usare l'operatore [] (dict[key] = value).

int size() const 🔗

Restituisce il numero di voci nel dizionario. I dizionari vuoti ({ }) restituiscono sempre 0. Vedi anche is_empty().

void sort() 🔗

Ordina il dizionario in ordine crescente, per chiave. L'ordine finale dipende dal confronto "minore di" (<) tra le chiavi.

var numbers = { "c": 2, "a": 0, "b": 1 }
numbers.sort()
print(numbers) # Stampa { "a": 0, "b": 1, "c": 2 }

Questo metodo garantisce che le voci del dizionario siano ordinate consistentemente quando vengono chiamati keys() o values(), oppure quando c'è bisogno di convertire il dizionario in una stringa attraverso @GlobalScope.str() o JSON.stringify().

Array values() const 🔗

Restituisce la lista dei valori in questo dizionario.

Descrizioni degli operatori

bool operator !=(right: Dictionary) 🔗

Restituisce true se i due dizionari non contengono le stesse chiavi e valori.

bool operator ==(right: Dictionary) 🔗

Restituisce true se i due dizionari contengono le stesse chiavi e valori. L'ordine delle voci non ha importanza.

Nota: In C#, per convenzione, questo operatore confronta per riferimento. Se devi confrontare per valore, itera su entrambi i dizionari.

Variant operator [](key: Variant) 🔗

Restituisce il valore corrispondente per la chiave key nel dizionario. Se la voce non esiste, fallisce e restituisce null. Per un accesso sicuro, usa get() o has().