Dictionary

Une structure de données intégrée qui contient des paires clé-valeur.

Description

Les dictionnaires sont des conteneurs associatifs qui contient des valeurs référencées par des clés uniques. Les dictionnaires préservent l'ordre d'insertion lors de l'ajout d'éléments. Dans d'autres langages de programmation, cette structure de données est souvent appelée table de hachage ou tableau associatif.

Vous pouvez définir un dictionnaire avec une liste de paires au format clé : valeur séparées par des virgules entre des accolades {}.

Créer un dictionnaire :

var mon_dict = {} # Crée un dictionnaire vide.

var dict_variable_cle = "Une autre clé"
var dict_variable_valeur = "valeur2"
var autre_dict = {
    "Une clé": "valeur1",
    dict_variable_cle : dict_variable_valeur,
}

var dict_points = {"Blanc": 50, "Jaune": 75, "Orange": 100}

# Syntaxe alternative façon Lua.
# Ne nécessite pas de guillemets autour des clés, mais seules les chaines de caractères constantes peuvent être utilisées comme nom pour les clés.
# De plus, les noms des clés doivent commencer par une lettre ou un tiret du bas ("_").
# Ici, `une_cle` est une chaine de caractère, pas une variable !
another_dict = {
    une_cle = 42,
}

var monDict = new Godot.Collections.Dictionary(); // Crée un dictionnaire vide.
var dictPoints= new Godot.Collections.Dictionary
{
    {"Blanc", 50},
    {"Jaune", 75},
    {"Orange", 100}
};

Vous pouvez accéder aux valeurs d'un dictionnaire en utilisant la clé associée. Dans l'exemple suivant, dict_points["Blanc"] renverra 50. Vous pouvez aussi écrire dict_points.Blanc, qui est équivalent. Par contre, vous devez utiliser la syntaxe avec les accolades si la clé n'est pas une chaine de caractère constante (comme un nombre ou une variable).

export(string, "Blanc", "Jaune", "Orange") var ma_couleur: String
var dict_points = {"Blanc": 50, "Jaune": 75, "Orange": 100}
func _ready():
    # On ne peut pas utiliser la syntaxe en point puisque `ma_couleur` est une variable.
    var points = dict_points[ma_couleur]

[Export(PropertyHint.Enum, "Blanc,Jaune,Orange")]
public string MaCouleur { get; set; }
private Godot.Collections.Dictionary _dictPoints= new Godot.Collections.Dictionary
{
    {"Blanc", 50},
    {"Jaune", 75},
    {"Orange", 100}
};

public override void _Ready()
{
    int points = (int)_dictPoints[MaCouleur];
}

Dans l'exemple au-dessus, points sera assigné à une valeur associée à la couleur choisie dans ma_couleur.

Les dictionnaires peuvent contenir des données plus complexes :

var mon_dict = {
    "Premier tableau": [1, 2, 3, 4] # Assigne un Array (Tableau) à un clé String.
}

var monDict= new Godot.Collections.Dictionary
{
    {"Premier tableau", new Godot.Collections.Array{1, 2, 3, 4}}
};

Pour ajouter une clé à un dictionnaire déjà existant, accédez-y comme si c'était une clé existante et associez lui une valeur :

var dict_points = {"Blanc": 50, "Jaune": 75, "Orange": 100}
points_dict["Bleu"] = 150 # Ajoute "Bleu" comme clé et assigne 150 pour sa valeur.

var dictPoints = new Godot.Collections.Dictionary
{
    {"Blanc", 50},
    {"Jaune", 75},
    {"Orange", 100}
};
pointsDict["Blue"] = 150; // Ajoute "Bleu" comme clé et assigne 150 pour sa valeur.

Enfin, les dictionnaires non typés peuvent utiliser différents types de clés et de valeurs dans le même dictionnaire :

# Ceci est un dictionnaire valide.
# Pour accéder à "Sous valeur" en-dessous, utilisez `mon_dict.sous_dict.sous_cle` ou `mon_dict["sous_dict"]["sous_cle"]`.
# Les styles d'accès peuvent être mélangés suivant les besoins.
var mon_dict = {
    "Clé String": 5,
    4: [1, 2, 3],
    7: "Hello",
    "sous_dict": {"sous_cle": "Sous valeur"},
}

// Ceci est un dictionnaire valide.
// Pour accéder à "Sous valeur" en-dessous, utilisez`((Godot.Collections.Dictionary)monDict["sous_dict"])["sous_cle"]`.
var monDict = new Godot.Collections.Dictionary {
    {"Clé String", 5},
    {4, new Godot.Collections.Array{1,2,3}},
    {7, "Hello"},
    {"sous_dict", new Godot.Collections.Dictionary{{"sous_cle", "Sous valeur"}}}
};

Les clés d'un dictionnaire peuvent être itérées dessus avec le mot-clé for :

var courses = {"Orange": 20, "Pomme": 2, "Banane": 4}
for fruit in courses :
    var quantite = courses[fruit]

var courses = new Godot.Collections.Dictionary{{"Orange", 20}, {"Pomme", 2}, {"Banane", 4}};
foreach (var (fruit, quantite) in courses)
{
    // `fruit` est la clé, `quantite` est la valeur.
}

Pour imposer un certain type pour les clés et les valeurs, vous pouvez créer un dictionnaire typé. Les dictionnaires typés ne peuvent contenir que des clés et des valeurs des types donnés, ou qui héritent des classes données :

# Crée un dictionnaire typé avec des clés de type String et des valeurs de type int.
# Essayer d'utiliser un autre type pour les clés ou les valeurs résultera en une erreur.
var dict_type: Dictionary[String, int] = {
    "une_cle": 1,
    "une_autre_cle": 2,
}

# Crée un dictionnaire typé avec des clés de type String et des valeurs de n'importe quel type.
# Essayer d'utiliser un autre type pour les clés résultera en une erreur.
var dict_type_cle_seulement: Dictionary[String, Variant] = {
    "une_cle": 12.34,
    "une_autre_cle": "string",
}

// Crée un dictionnaire typé avec des clés de type String et des valeurs de type int.
// Essayer d'utiliser un autre type pour les clés ou les valeurs résultera en une erreur.
var dictType = new Godot.Collections.Dictionary<String, int> {
    {"une_cle", 1},
    {"une_autre_cle", 2},
};

// Crée un dictionnaire typé avec des clés de type String et des valeurs de n'importe quel type.
// Essayer d'utiliser un autre type pour les clés résultera en une erreur.
var dictTypeCleSeulement = new Godot.Collections.Dictionary<String, Variant> {
    {"une_cle", 12.34},
    {"une_autre_cle", "string"},
};

Note : Les dictionnaires sont toujours passés par référence. Pour obtenir une copie d'un dictionnaire qui peut être modifié de manière indépendante de l'original, utilisez duplicate().

Note : Effacer des éléments lors de l'itération d'un dictionnaire n'est pas supporté et va résulter en un comportement imprévisible.

Note

Il y a des différences notables dans l'utilisation de cette API en C#. Voir Différences de l'API C# par rapport à GDScript pour plus d'informations.

Tutoriels

Constructeurs

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)

Méthodes

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

Opérateurs

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

Descriptions des constructeurs

Dictionary Dictionary() 🔗

Construit un Dictionary vide.

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

Crée un dictionnaire typé depuis le dictionnaire base. Un dictionnaire typé ne peut contenir que des clés et des valeurs des types donnés, ou qui héritent des classes données, telles que décrits par les paramètres du constructeur.

Dictionary Dictionary(from: Dictionary)

Renvoie le même dictionnaire que from. Si vous avez besoin d'une copie du dictionnaire, utilisez duplicate().

Descriptions des méthodes

void assign(dictionary: Dictionary) 🔗

Assigne des éléments d'un autre dictionnaire dictionary dans le dictionnaire. Redimensionne le dictionnaire pour faire correspondre à dictionary. Effectue des conversions de type si le dictionnaire est typé.

void clear() 🔗

Vide le dictionnaire, en supprimant toutes les entrées de celui-ci.

Dictionary duplicate(deep: bool = false) const 🔗

Renvoie une nouvelle copie du dictionnaire.

Par défaut, une copie superficielle (shallow copy) est renvoyée : toutes les clés Array, Dictionary et Resource imbriquées sont partagés avec le dictionnaire original. Modifier l'un dans un dictionnaire va aussi modifier l'autre.

Si deep vaut true, une copie profonde (deep copy) est renvoyée : tous les tableaux et les dictionnaires imbriqués sont également dupliqués (récursivement). Les Resources sont cependant toujours partagées avec le dictionnaire original.

Dictionary duplicate_deep(deep_subresources_mode: int = 1) const 🔗

Duplicates this dictionary, deeply, like duplicate()(true), with extra control over how subresources are handled.

deep_subresources_mode must be one of the values from DeepDuplicateMode. By default, only internal resources will be duplicated (recursively).

bool erase(key: Variant) 🔗

Retire l'entrée du dictionnaire par sa clé, si elle existe. Renvoie true si la clé key donnée existait dans le dictionnaire, sinon false.

Note : N'effacez pas d'entrées lors de l'itération sur le dictionnaire. Vous pouvez itérer sur le tableau keys() à la place.

Variant find_key(value: Variant) const 🔗

Trouve et renvoie la première clé dont la valeur associée est égale à value, ou null si elle n'est pas trouvée.

Note : null est également une clé valide. Si elle est dans le dictionnaire, find_key() peut donner des résultats trompeurs.

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

Renvoie la valeur correspondante de la clé key donnée dans le dictionnaire. Si la clé key n'existe pas, renvoie default ou null si le paramètre est omis.

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

Obtient une valeur et assure que la clé est définie. Si la key existe dans le dictionnaire, cela se comporte comme get(). Sinon, la valeur default est insérée dans le dictionnaire et renvoyée.

int get_typed_key_builtin() const 🔗

Renvoie le type Variant intégré des clés du dictionnaire de type en tant que constante Variant.Type. Si les clés ne sont pas typées, renvoie @GlobalScope.TYPE_NIL. Voir aussi is_typed_key().

StringName get_typed_key_class_name() const 🔗

Renvoie le nom de classe intégrée des clés du dictionnaire typé, si le type Variant intégré est @GlobalScope.TYPE_OBJECT. Sinon, renvoie un StringName vide. Voir aussi is_typed_key() et Object.get_class().

Variant get_typed_key_script() const 🔗

Renvoie l'instance Script associée aux clés de ce dictionnaire, ou null si elle n'existe pas. Voir aussi is_typed_key().

int get_typed_value_builtin() const 🔗

Renvoie le type Variant intégré des valeurs du dictionnaire typé en tant que constante Variant.Type. Si les valeurs ne sont pas typées, renvoie @GlobalScope.TYPE_NIL. Voir aussi is_typed_value().

StringName get_typed_value_class_name() const 🔗

Renvoie le nom de classe intégrée des valeurs du dictionnaire typé, si le type Variant intégré est @GlobalScope.TYPE_OBJECT. Sinon, renvoie un StringName vide. Voir aussi is_typed_value() et Object.get_class().

Variant get_typed_value_script() const 🔗

Renvoie l'instance Script associée aux valeurs de ce dictionnaire, ou null si elle n'existe pas. Voir aussi is_typed_value().

bool has(key: Variant) const 🔗

Renvoie true si le dictionnaire contient une entrée avec la clé key donnée.

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

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

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

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

En GDScript, cela équivaut à l'opérateur in :

if "Godot" in {"Godot": 4}:
    print("La clé est ici !") # Sera affiché.

Note: Cette méthode renvoie true tant que la key existe, même si sa valeur correspondante est null.

bool has_all(keys: Array) const 🔗

Returns true if the dictionary contains all keys in the given keys array.

var data = { "width": 10, "height": 20 }
data.has_all(["height", "width"]) # Returns true

int hash() const 🔗

Renvoie une valeur d'entier de 32 bits hachée représentant le contenu du dictionnaire.

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

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

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

// Godot.Collections.Dictionary n'a pas de méthode Hash(). Utilisez GD.Hash() à la place.
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Affiche True

Note : Les dictionnaires avec les mêmes entrées mais dans un ordre différent n'auront pas le même hachage.

Note : Les dictionnaires avec des valeurs de hachage égales ne sont pas garantis d'être le même, en raison des collisions de hachage. Au contraire, les dictionnaires avec différentes valeurs de hachage sont garantis d'être différents.

bool is_empty() const 🔗

Renvoie true si le dictionnaire est vide (sa taille est de 0). Voir aussi size().

bool is_read_only() const 🔗

Renvoie true si le dictionnaire est en lecture seule. Voir make_read_only(). Les dictionnaires sont automatiquement en lecture seule s'ils sont déclarés avec le mot-clé const.

bool is_same_typed(dictionary: Dictionary) const 🔗

Renvoie true si le dictionnaire est typé de la même manière que le dictionnaire dictionary.

bool is_same_typed_key(dictionary: Dictionary) const 🔗

Renvoie true si les clés du dictionnaire sont typées de la même manière que les clés du dictionnaire dictionary.

bool is_same_typed_value(dictionary: Dictionary) const 🔗

Renvoie true si les valeurs du dictionnaire sont typées de la même manière que les valeurs du dictionnaire dictionary.

bool is_typed() const 🔗

Renvoie true si le dictionnaire est typé. Les dictionnaires typés ne peuvent stocker que des clés et des valeurs du type associé et fournissent une sûreté du typage pour l'opérateur []. Les méthodes des dictionnaires typés renvoient toujours des Variant.

bool is_typed_key() const 🔗

Renvoie true si les clés du dictionnaire sont typées.

bool is_typed_value() const 🔗

Renvoie true si les valeurs du dictionnaire sont typées.

Array keys() const 🔗

Renvoie la liste des clés du dictionnaire.

void make_read_only() 🔗

Oblige le dictionnaire à être en lecture seule, c'est-à-dire désactive la modification du contenu du dictionnaire. Ne s'applique pas au contenu imbriqué, par exemple le contenu de dictionnaires imbriqués.

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

Ajoute des entrées du dictionanaire dictionary à ce dictionnaire. Par défaut, les clés en double ne sont pas copiés, sauf si overwrite vaut true.

var dict = { "objet": "epee", "quantite": 2 }
var autre_dict = { "quantite": 15, "couleur": "argent" }

# L'écrasement des clés existantes est désactivé par défaut.
dict.merge(autre_dict)
print(dict)  # { "objet": "epee", "quantite": 2, "couleur": "argent" }

# Avec l'écrasement des clés activé.
dict.merge(autre_dict, true)
print(dict)  # { "objet": "epee", "quantite": 15, "couleur": "argent" }

var dict = new Godot.Collections.Dictionary
{
    ["objet"] = "epee",
    ["quantite"] = 2,
};

var autreDict = new Godot.Collections.Dictionary
{
    ["quantite"] = 15,
    ["couleur"] = "argent",
};

// L'écrasement des clés existantes est désactivé par défaut.
dict.Merge(autreDict);
GD.Print(dict); // { "objet": "epee", "quantite": 2, "couleur": "argent" }

// Avec l'écrasement des clés activé.
dict.Merge(autreDict, true);
GD.Print(dict); // { "objet": "epee", "quantite": 15, "couleur": "argent" }

Note : merge() n'est pas récursive. Les dictionnaires imbriqués sont considérés comme des clés qui peuvent être remplacées ou non selon la valeur de overwrite, mais ils ne seront jamais fusionnés ensemble.

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

Renvoie une copie de ce dictionnaire fusionné avec l'autre dictionnaire dictionary. Par défaut, les clés en double ne sont pas copiées, sauf si overwrite vaut true. Voir aussi merge().

Cette méthode est utile pour créer rapidement des dictionnaires avec des valeurs par défaut :

var base = { "fruit": "pomme", "legume": "patate" }
var extra = { "fruit": "orange", "assaisonnement": "vinaigre" }
# Affiche { "fruit": "orange", "legume": "patate", "assaisonnement": "vinaigre" }
print(extra.merged(base))
# Affiche { "fruit": "pomme", "legume": "patate", "assaisonnement": "vinaigre" }
print(extra.merged(base, true))

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

Renvoie true si les deux dictionnaires contiennent les mêmes clés et valeurs, les clés des Dictionary et Array intérieurs sont comparées récursivement.

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

Définit la valeur de l'élément à la clé key donnée à la valeur value donnée. Ceci est identique à l'utilisation de l'opérateur ```` (tableau[index] = valeur).

int size() const 🔗

Renvoie le nombre d'entrées dans le dictionnaire. Les dictionnaires vides ({ }) renvoient toujours 0. Voir aussi is_empty().

void sort() 🔗

Trie le dictionnaire en ordre ascendant, par clé. L'ordre final dépend de la comparaison "inférieur à" (<) entre les clés..

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

Cette méthode garantit que les entrées du dictionnaire sont triées de manière consistante lorsque keys() ou values() sont appelées, ou lorsque le dictionnaire doit être converti en une chaîne par @GlobalScope.str() ou JSON.stringify().

Array values() const 🔗

Renvoie la liste des valeurs dans ce dictionnaire.

Descriptions des opérateurs

bool operator !=(right: Dictionary) 🔗

Renvoie true si les deux dictionnaires ne contiennent pas les mêmes clés et valeurs.

bool operator ==(right: Dictionary) 🔗

Renvoie true si les deux dictionnaires contiennent les mêmes clés et valeurs. L'ordre des entrées n'a aucune importance.

Note : En C#, par convention, cet opérateur compare par référence. Si vous devez comparer par valeur, itérez sur les deux dictionnaires.

Variant operator [](key: Variant) 🔗

Renvoie la valeur correspondante à la clé key donnée dans le dictionnaire. Si l'entrée n'existe pas, échoue et renvoie null. Pour un accès sécurisé, utilisez get() ou has().