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

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

Опис

Словники — це асоціативні контейнери, що містять значення, на які посилаються унікальні ключі. При додаванні нових записів словники зберігають порядок вставки. В інших мовах програмування цю структуру даних часто називають хеш-картою або асоціативним масивом.

Словник можна визначити, розмістивши список пар ключ: значення, розділених комами, у фігурних дужках {}.

Створення словника:

var my_dict = {} # Створює порожній словник.

var dict_variable_key = "Інша назва ключа"
var dict_variable_value = "value2"
var another_dict = {
 "Деяка назва ключа": "value1",
    dict_variable_key: dict_variable_value,
}

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

# Альтернативний синтаксис у стилі Lua.
# Не вимагає лапок навколо ключів, але як імена ключів можна використовувати лише рядкові константи.
# Крім того, імена ключів повинні починатися з літери або підкреслення.
# Тут `some_key` — це рядковий літерал, а не змінна!
another_dict = {
 some_key = 42,
}

var myDict = new Godot.Collections.Dictionary(); // Створює порожній словник.
var pointsDict = new Godot.Collections.Dictionary
{
 { "White", 50 },
 { "Yellow", 75 },
 { "Orange", 100 },
};

Ви можете отримати доступ до значення словника, посилаючись на відповідний ключ. У наведеному вище прикладі points_dict["White"] поверне 50. Ви також можете написати points_dict.White, що є еквівалентним. Однак вам доведеться використовувати синтаксис з дужками, якщо ключ, за яким ви отримуєте доступ до словника, не є фіксованим рядком (наприклад, число або змінна).

@export_enum("White", "Yellow", "Orange") var my_color: String
var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
func _ready():
 # Тут ми не можемо використовувати синтаксис з крапкою, оскільки `my_color` є змінною.
    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];
}

У наведеному вище коді points буде присвоєно значення, яке відповідає кольору, вибраному в my_color.

Словники можуть містити більш складні дані:

var my_dict = {
 "First Array": [1, 2, 3, 4] # Присвоює масив ключу-рядку.
}

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

Щоб додати ключ до існуючого словника, зверніться до нього як до існуючого ключа та присвойте йому значення:

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
points_dict["Blue"] = 150 # Додайте "Blue" як ключ і присвойте йому значення 150.

var pointsDict = new Godot.Collections.Dictionary
{
 { "White", 50 },
 { "Yellow", 75 },
 { "Orange", 100 },
};
pointsDict["Blue"] = 150; // Додаємо "Blue" як ключ і присвоюємо йому значення 150.

Нарешті, нетипізовані словники можуть містити різні типи ключів і значень в одному словнику:

# Це дійсний словник.
# Щоб отримати доступ до рядка "Nested value" нижче, використовуйте `my_dict.sub_dict.sub_key` або `my_dict["sub_dict"][" sub_key"]`.
# Стилі індексації можна змішувати та поєднувати залежно від ваших потреб.
var my_dict = {
 "String Key": 5,
 4: [1, 2, 3],
 7: "Hello",
 "sub_dict": { "sub_key": "Nested value" },
}

// Це дійсний словник.
// Щоб отримати доступ до рядка "Nested value" нижче, використовуйте `((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" } } },
};

Ключі словника можна перебирати за допомогою ключового слова 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` — це ключ, `amount` — це значення.
}

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

# Створює типізований словник із ключами типу String та значеннями типу int.
# Спроба використання будь-якого іншого типу для ключів або значень призведе до помилки.
var typed_dict: Dictionary[String, int] = {
 "some_key": 1,
 "some_other_key": 2,
}

# Створює типізований словник із ключами типу String та значеннями будь-якого типу.
# Спроба використання будь-якого іншого типу для ключів призведе до помилки.
var typed_dict_key_only: Dictionary[String, Variant] = {
 "some_key": 12.34,
 "some_other_key": "string",
}

// Створює типізований словник із ключами типу String та значеннями типу int.
// Спроба використання будь-якого іншого типу для ключів або значень призведе до помилки.
var typedDict = new Godot.Collections.Dictionary<String, int> {
 {"some_key", 1},
 {"some_other_key", 2},
};

// Створює типізований словник із ключами типу String та значеннями будь-якого типу.
// Спроба використання будь-якого іншого типу для ключів призведе до помилки.
var typedDictKeyOnly = new Godot.Collections.Dictionary<String, Variant> {
 {"some_key", 12.34},
 {"some_other_key", "string"},
};

Примітка: Словники завжди передаються за посиланням. Щоб отримати копію словника, яку можна змінювати незалежно від оригінального словника, використовуйте duplicate().

Примітка: Видалення елементів під час ітерації по словниках не підтримується і призведе до непередбачуваної поведінки.

Примітка: У булевому контексті словник буде обчислюватися як false, якщо він порожній ({}). В іншому випадку словник завжди обчислюватиметься як 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 🔗

Повертає відповідне значення для заданого key у словнику. Якщо key не існує, повертає default або null, якщо параметр не вказано.

Примітка: Якщо аргумент default є обчислювально ресурсоємним або має небажані побічні ефекти, рекомендується замість нього використовувати метод has():

# Завжди викликає `expensive_function()`.
dict.get("key", expensive_function())
# Викликає `expensive_function()` тільки якщо ключ не існує.
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().