Dictionary

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

Опис

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

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

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

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

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 }

# Альтернативний синтаксис у стилі 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] # Присвоює масив ключу String.
}

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.

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

# Це дійсний словник.
# Щоб отримати доступ до рядка «Вкладене значення» нижче, використовуйте `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" },
}

// Це дійсний словник.
// Щоб отримати доступ до рядка «Вкладене значення» нижче, використовуйте `((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().

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

Примітка

Існують значні відмінності при використанні цього 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, якщо параметр не вдається.

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. Це те саме, що використання оператора [ ] (``масив[index] = valve ``).

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().