Dictionary

Встроенная структура данных, содержащая пары ключ-значение.

Описание

Dictionaries (Словари) — это ассоциативные контейнеры, содержащие значения, на которые ссылаются уникальные ключи. Словари сохраняют порядок добавления новых записей. В других языках программирования эта структура данных часто называется "hash map" или ассоциативным массивом.

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

Создание словаря:

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 key).
}

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 # 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.

Наконец, нетипизированные словари могут содержать различные типы ключей и значений в одном и том же словаре:

# Это действительный словарь.
# Чтобы получить доступ к строке "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` - значение.
}

Чтобы обеспечить определённый тип ключей и значений, можно создать typed dictionary. Типизированные словари могут содержать только ключи и значения заданных типов или наследуемые от заданных классов:

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

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

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

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

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

Примечание: Удаление элементов при итерации по словарям не поддерживается и приведет к непредсказуемому поведению.

Примечание

Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.

Обучающие материалы

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

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 до тех пор, пока существует key, даже если его соответствующее значение равно 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 = { "item": "sword", "quantity": 2 }
var other_dict = { "quantity": 15, "color": "silver" }

# Перезапись существующих ключей по умолчанию отключена.
dict.merge(other_dict)
print(dict)  # { "item": "sword", "quantity": 2, "color": "silver" }

# С возможностью перезаписи существующих ключей.
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",
};

// Перезапись существующих ключей по умолчанию отключена.
dict.Merge(otherDict);
GD.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" }

// С возможностью перезаписи существующих ключей.
dict.Merge(otherDict, true);
GD.Print(dict); // { "item": "sword", "quantity": 15, "color": "silver" }

Примечание: merge() не рекурсивен. Вложенные словари рассматриваются как ключи, которые могут быть перезаписаны или нет в зависимости от значения overwrite, но они никогда не будут объединены вместе.

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

Возвращает копию этого словаря, объединенную с другим dictionary. По умолчанию дублирующиеся ключи не копируются, если только overwrite не равна true. См. также merge().

Этот метод полезен для быстрого создания словарей со значениями по умолчанию:

var base = { "fruit": "apple", "vegetable": "potato" }
var extra = { "fruit": "orange", "dressing": "vinegar" }
# Выводит { "fruit": "orange", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base))
# Выводит { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" }
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().