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

Вбудована структура даних, яка має ключові пари.

Опис

Dictionaries are associative containers that contain values referenced by unique keys. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is often referred to as a hash map or an associative array.

You can define a dictionary by placing a comma-separated list of key: value pairs inside curly braces {}.

Creating a dictionary:

var my_dict = {} # Creates an empty dictionary.

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 }

# Alternative Lua-style syntax.
# Doesn't require quotes around keys, but only string constants can be used as key names.
# Additionally, key names must start with a letter or an underscore.
# Here, `some_key` is a string literal, not a variable!
another_dict = {
    some_key = 42,
}

var myDict = new Godot.Collections.Dictionary(); // Creates an empty dictionary.
var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 },
};

You can access a dictionary's value by referencing its corresponding key. In the above example, points_dict["White"] will return 50. You can also write points_dict.White, which is equivalent. However, you'll have to use the bracket syntax if the key you're accessing the dictionary with isn't a fixed string (such as a number or variable).

@export_enum("White", "Yellow", "Orange") var my_color: String
var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
func _ready():
    # We can't use dot syntax here as `my_color` is a variable.
    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];
}

In the above code, points will be assigned the value that is paired with the appropriate color selected in my_color.

Dictionaries can contain more complex data:

var my_dict = {
    "First Array": [1, 2, 3, 4] # Assigns an Array to a String key.
}

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

To add a key to an existing dictionary, access it like an existing key and assign to it:

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.

var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 },
};
pointsDict["Blue"] = 150; // Add "Blue" as a key and assign 150 as its value.

Finally, untyped dictionaries can contain different types of keys and values in the same dictionary:

# This is a valid dictionary.
# To access the string "Nested value" below, use `my_dict.sub_dict.sub_key` or `my_dict["sub_dict"]["sub_key"]`.
# Indexing styles can be mixed and matched depending on your needs.
var my_dict = {
    "String Key": 5,
    4: [1, 2, 3],
    7: "Hello",
    "sub_dict": { "sub_key": "Nested value" },
}

// This is a valid dictionary.
// To access the string "Nested value" below, use `((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" } } },
};

The keys of a dictionary can be iterated with the for keyword:

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` is the key, `amount` is the value.
}

To enforce a certain type for keys and values, you can create a typed dictionary. Typed dictionaries can only contain keys and values of the given types, or that inherit from the given classes:

# Creates a typed dictionary with String keys and int values.
# Attempting to use any other type for keys or values will result in an error.
var typed_dict: Dictionary[String, int] = {
    "some_key": 1,
    "some_other_key": 2,
}

# Creates a typed dictionary with String keys and values of any type.
# Attempting to use any other type for keys will result in an error.
var typed_dict_key_only: Dictionary[String, Variant] = {
    "some_key": 12.34,
    "some_other_key": "string",
}

// Creates a typed dictionary with String keys and int values.
// Attempting to use any other type for keys or values will result in an error.
var typedDict = new Godot.Collections.Dictionary<String, int> {
    {"some_key", 1},
    {"some_other_key", 2},
};

// Creates a typed dictionary with String keys and values of any type.
// Attempting to use any other type for keys will result in an error.
var typedDictKeyOnly = new Godot.Collections.Dictionary<String, Variant> {
    {"some_key", 12.34},
    {"some_other_key", "string"},
};

Note: Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use duplicate().

Note: Erasing elements while iterating over dictionaries is not supported and will result in unpredictable behavior.

Note: In a boolean context, a dictionary will evaluate to false if it's empty ({}). Otherwise, a dictionary will always evaluate to true.

Примітка

Існують значні відмінності при використанні цього API із С#. Більше інформації: ref:doc_c_sharp_differences.

Посібники

Конструктори

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)

Методи

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

Оператори

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

Описи конструкторів

Dictionary 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)

Створює введений словник зі словника base. Типізований словник може містити лише ключі та значення заданих типів або ті, що успадковуються від заданих класів, як описано в параметрах цього конструктора.

Dictionary Dictionary(from: Dictionary)

Повертає той самий словник, що й from. Якщо вам потрібна копія словника, використовуйте duplicate().

Описи методів

void assign(dictionary: Dictionary) 🔗

Призначає елементи іншого dictionary до словника. Змінює розмір словника відповідно до dictionary. Виконує перетворення типів, якщо словник набраний.

void clear() 🔗

Очистити словник, видаляючи всі записи з нього.

Dictionary duplicate(deep: bool = false) const 🔗

Повертає нову копію словника.

За замовчуванням повертається неглибока копія: усі вкладені ключі та значення Array, Dictionary та Resource спільні з оригінальним словником. Зміна будь-якого з них в одному словнику також вплине на них в іншому.

Якщо deep має значення true, повертається глибока копія: усі вкладені масиви та словники також дублюються (рекурсивно). Однак будь-який Resource все ще спільний з оригінальним словником.

Dictionary duplicate_deep(deep_subresources_mode: int = 1) const 🔗

Дублює цей словник, глибоко, подібно до duplicate() при передачі true, з додатковим контролем над обробкою підресурсів.

deep_subresources_mode має бути одним зі значень з DeepDuplicateMode. За замовчуванням (рекурсивно) будуть дублюватися лише внутрішні ресурси.

bool erase(key: Variant) 🔗

Видалити запис словника за допомогою ключа, якщо він існує. Повертає true, якщо надана key існувала в словнику, інакше false.

Примітка: Не стирайте записи, в той час як ітерація над словником. Ви можете ітерувати над keys() масив замість.

Variant find_key(value: Variant) const 🔗

Знаходиться і повертає перший ключ, який пов'язаний значенням value, або null, якщо він не знайдений.

Примітка: null також є дійсним ключем. Якщо всередині словника, find_key() може дати в оману результати.

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) 🔗

Отримує значення та перевіряє, чи встановлено ключ. Якщо key існує у словнику, це поводиться як get(). В іншому випадку значення default вставляється у словник та повертається.

int get_typed_key_builtin() const 🔗

Повертає вбудований тип Variant ключів введеного словника як константу Variant.Type. Якщо ключі не введено, повертає @GlobalScope.TYPE_NIL. Дивіться також is_typed_key().

StringName get_typed_key_class_name() const 🔗

Повертає вбудовану назву класу ключів введеного словника, якщо вбудований тип Variant — @GlobalScope.TYPE_OBJECT. В іншому випадку повертає порожній StringName. Дивіться також is_typed_key() і Object.get_class().

Variant get_typed_key_script() const 🔗

Повертає екземпляр Script, пов’язаний із ключами цього введеного словника, або null, якщо він не існує. Дивіться також is_typed_key().

int get_typed_value_builtin() const 🔗

Повертає вбудований тип Variant значень введеного словника як константу Variant.Type. Якщо значення не введено, повертає @GlobalScope.TYPE_NIL. Дивіться також is_typed_value().

StringName get_typed_value_class_name() const 🔗

Повертає вбудовану назву класу значень введеного словника, якщо вбудованим типом Variant є @GlobalScope.TYPE_OBJECT. В іншому випадку повертає порожній StringName. Дивіться також is_typed_value() і Object.get_class().

Variant get_typed_value_script() const 🔗

Повертає екземпляр Script, пов’язаний зі значеннями цього введеного словника, або null, якщо він не існує. Дивіться також is_typed_value().

bool has(key: Variant) const 🔗

Повертає true, якщо словник містить запис із заданим key.

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

print(my_dict.has("Godot")) # Виводить true
print(my_dict.has(210))     # Виводить true
print(my_dict.has(4))       # Виводить false

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

GD.Print(myDict.ContainsKey("Godot")); // Виводить True
GD.Print(myDict.ContainsKey(210));     // Виводить True
GD.Print(myDict.ContainsKey(4));       // Виводить False

У GDScript це еквівалентно оператору in:

if "Godot" in { "Godot": 4 }:
    print("Ключ тут!) # Буде надруковано.

Примітка: Цей метод повертає true, якщо існує ключ параметра, навіть якщо його відповідне значення дорівнює null.

bool has_all(keys: Array) const 🔗

Повертає true, якщо словник містить усі ключі з заданого масиву keys.

var data = { "width": 10, "height": 20 }
data.has_all(["height", "width"]) # Виводить true

int hash() const 🔗

Повертає хешоване 32-бітове ціле число, що представляє вміст словника.

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

print(dict1.hash() == dict2.hash()) # Виводить true

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

// Godot.Collections.Dictionary не має методу Hash(). Натомість використовуйте GD.Hash().
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Виводить True

Примітка: Словники з однаковими записами, але в різному порядку, не матимуть однакового хешу.

Примітка: Словники з однаковими хеш-значеннями не гарантовано будуть однаковими через колізії хеш-значень. Навпаки, словники з різними хеш-значеннями гарантовано будуть різними.

bool is_empty() const 🔗

Повертає true, якщо словник порожній (його розмір 0). Див. також size().

bool is_read_only() const 🔗

Повертає true, якщо словник доступний лише для читання. Див. make_read_only(). Словники автоматично стають доступними лише для читання, якщо їх оголошено з ключовим словом const.

bool is_same_typed(dictionary: Dictionary) const 🔗

Повертає true, якщо словник введено так само, як dictionary.

bool is_same_typed_key(dictionary: Dictionary) const 🔗

Повертає true, якщо ключі словника введені так само, як і ключі dictionary.

bool is_same_typed_value(dictionary: Dictionary) const 🔗

Повертає true, якщо значення словника введено так само, як і значення dictionary.

bool is_typed() const 🔗

Повертає true, якщо словник введено. Введені словники можуть зберігати лише ключі/значення відповідного типу та забезпечувати безпеку типу для оператора []. Методи введеного словника все ще повертають Variant.

bool is_typed_key() const 🔗

Повертає true, якщо введено ключі словника.

bool is_typed_value() const 🔗

Повертає true, якщо введено значення словника.

Array keys() const 🔗

Повертає список ключів у словнику.

void make_read_only() 🔗

Зроблює словниковий читання, тобто відключає модифікацію вмісту словника. Не застосовуватися до невидимого вмісту, наприклад, вмісту непристойних словників.

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

Додає записи зі словника dictionary до цього словника. За замовчуванням дублікати ключів не копіюються, якщо overwrite не має значення true.

var dict = { "предмет": "шабля", "кількість": 2 }
var other_dict = { "кількість": 15, "колір": "срібний" }

# Перезапис існуючих ключів вимкнено за замовчуванням.
dict.merge(other_dict)
print(dict) # { "предмет": "шабля", "кількість": 2, "колір": "срібний" }

# З увімкненим перезаписом існуючих ключів.
dict.merge(other_dict, true)
print(dict) # { "предмет": "шабля", "кількість": 15, "колір": "срібний" }

var dict = new Godot.Collections.Dictionary
{
    ["предмет"] = "шабля",
    ["кількість"] = 2,
};

var otherDict = new Godot.Collections.Dictionary
{
    ["кількість"] = 15,
    ["колір"] = "срібний",
};

// Перезапис існуючих ключів вимкнено за замовчуванням.
dict.Merge(otherDict);
GD.Print(dict); // { "предмет": "шабля", "кількість": 2, "колір": "срібний" }

// З увімкненим перезаписом існуючих ключів.
dict.Merge(otherDict, true);
GD.Print(dict); // { "предмет": "шабля", "кількість": 15, "колір": "срібний" }

**Примітка: ** merge() не рекурсивний. Вкладені словники вважаються ключами, які можуть бути перезаписані чи ні, залежно від значення overwrite, але вони ніколи не будуть об’єднані разом.

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

Повертає копію цього словника, об’єднаного з іншим dictionary. За замовчуванням дублікати ключів не копіюються, якщо overwrite не має значення true. Дивіться також merge().

Цей метод корисний для швидкого створення словників зі значеннями за замовчуванням:

var base = { "фрукт": "яблуко", "овоч": "картопля" }
var extra = { "фрукт": "апельсин", "заправка": "оцет" }
# Виведе { "фрукт": "апельсин", "овоч": "картопля", "заправка": "оцет" }
print(extra.merged(base))
# Виведе { "фрукт": "яблуко", "овоч": "картопля", "заправка": "оцет" }
print(extra.merged(base, true))

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

Повертаємо true, якщо два словники містять ті ж ключі та значення, внутрішні Dictionary та Array ключі та значення порівнюються з рекурсивно.

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

Встановлює значення елемента за заданим key рівним заданому value. Повертає true, якщо значення встановлено успішно. Не вдається та повертає false, якщо словник доступний лише для читання або якщо key та value не відповідають типам словника. Це те саме, що й використання оператора [] (dict[key] = value).

int size() const 🔗

Повертає кількість записів у словнику. Порожні словники ({ }) завжди повертають 0. Див. також is_empty().

void sort() 🔗

Сортує словник у порядку зростання за ключем. Остаточний порядок залежить від порівняння "менше ніж" (<) між ключами.

var numbers = { "c": 2, "a": 0, "b": 1 }
numbers.sort()
print(numbers) # Друкує { "a": 0, "b": 1, "c": 2 }

Цей метод гарантує, що записи словника впорядковані послідовно, коли викликаються keys() або values(), або коли словник потрібно перетворити на рядок за допомогою @GlobalScope.str() або JSON.stringify().

Array values() const 🔗

Повертає список значень у цьому словнику.

Описи операторів

bool operator !=(right: Dictionary) 🔗

Повертає true, якщо два словники не містять однакових ключів і значень.

bool operator ==(right: Dictionary) 🔗

Повертає true, якщо два словники містять однакові ключі та значення. Порядок записів не має значення.

Примітка: У C#, за конвенцією, цей оператор порівнює адреси. Якщо необхідно порівнювати за значенням, скористайтеся ітерацією по обидвох словниках.

Variant operator [](key: Variant) 🔗

Повертає відповідне значення для заданого key у словнику. Якщо запис не існує, виконується помилка та повертається null. Для безпечного доступу використовуйте get() або has().