:github_url: hide .. Generated automatically by doc/tools/makerst.py in Godot's source tree. .. DO NOT EDIT THIS FILE, but the Dictionary.xml source instead. .. The source is found in doc/classes or modules//doc_classes. .. _class_Dictionary: Dictionary ========== Dictionary type. Description ----------- Dictionary type. Associative container which contains values referenced by unique keys. Dictionary are composed of pairs of keys (which must be unique) and values. You can define a dictionary by placing a comma separated list of ``key: value`` pairs in curly braces ``{}``. Erasing elements while iterating over them **is not supported**. Creating a dictionary: :: var my_dir = {} # Creates an empty dictionary. var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} var my_dir = { key1: value1, key2: value2, key3: value3, } You can access values of a dictionary by referencing appropriate key in above example ``points_dir["White"]`` would return value of 50. :: export(String, "White", "Yellow", "Orange") var my_color var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} func _ready(): var points = points_dir[my_color] 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: :: my_dir = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key. To add a key to an existing dictionary, access it like an existing key and assign to it: :: var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} var points_dir["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value. Finally, dictionaries can contain different types of keys and values in the same dictionary: :: var my_dir = {"String Key": 5, 4: [1, 2, 3], 7: "Hello"} # This is a valid dictionary. **Note:** Unlike :ref:`Array`\ s you can't compare dictionaries directly: :: array1 = [1, 2, 3] array2 = [1, 2, 3] func compare_arrays(): print(array1 == array2) # Will print true. dir1 = {"a": 1, "b": 2, "c": 3} dir2 = {"a": 1, "b": 2, "c": 3} func compare_dictionaries(): print(dir1 == dir2) # Will NOT print true. You need to first calculate the dictionary's hash with :ref:`hash` before you can compare them: :: dir1 = {"a": 1, "b": 2, "c": 3} dir2 = {"a": 1, "b": 2, "c": 3} func compare_dictionaries(): print(dir1.hash() == dir2.hash()) # Will print true. Tutorials --------- - `#dictionary <../tutorials/scripting/gdscript/gdscript_basics.html#dictionary>`_ in :doc:`../tutorials/scripting/gdscript/gdscript_basics` Methods ------- +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear` **(** **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary` | :ref:`duplicate` **(** :ref:`bool` deep=false **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`empty` **(** **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`erase` **(** :ref:`Variant` key **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get` **(** :ref:`Variant` key, :ref:`Variant` default=null **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has` **(** :ref:`Variant` key **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_all` **(** :ref:`Array` keys **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`hash` **(** **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`keys` **(** **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`size` **(** **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`values` **(** **)** | +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ Method Descriptions ------------------- .. _class_Dictionary_method_clear: - void **clear** **(** **)** Clear the dictionary, removing all key/value pairs. ---- .. _class_Dictionary_method_duplicate: - :ref:`Dictionary` **duplicate** **(** :ref:`bool` deep=false **)** Creates a copy of the dictionary, and returns it. ---- .. _class_Dictionary_method_empty: - :ref:`bool` **empty** **(** **)** Returns ``true`` if the dictionary is empty. ---- .. _class_Dictionary_method_erase: - :ref:`bool` **erase** **(** :ref:`Variant` key **)** Erase a dictionary key/value pair by key. Returns ``true`` if the given key was present in the dictionary, ``false`` otherwise. Does not erase elements while iterating over the dictionary. ---- .. _class_Dictionary_method_get: - :ref:`Variant` **get** **(** :ref:`Variant` key, :ref:`Variant` default=null **)** Returns the current value for the specified key in the ``Dictionary``. If the key does not exist, the method returns the value of the optional default argument, or ``null`` if it is omitted. ---- .. _class_Dictionary_method_has: - :ref:`bool` **has** **(** :ref:`Variant` key **)** Returns ``true`` if the dictionary has a given key. ---- .. _class_Dictionary_method_has_all: - :ref:`bool` **has_all** **(** :ref:`Array` keys **)** Returns ``true`` if the dictionary has all of the keys in the given array. ---- .. _class_Dictionary_method_hash: - :ref:`int` **hash** **(** **)** Returns a hashed integer value representing the dictionary contents. This can be used to compare dictionaries by value: :: var dict1 = {0: 10} var dict2 = {0: 10} # The line below prints `true`, whereas it would have printed `false` if both variables were compared directly. print(dict1.hash() == dict2.hash()) ---- .. _class_Dictionary_method_keys: - :ref:`Array` **keys** **(** **)** Returns the list of keys in the ``Dictionary``. ---- .. _class_Dictionary_method_size: - :ref:`int` **size** **(** **)** Returns the size of the dictionary (in pairs). ---- .. _class_Dictionary_method_values: - :ref:`Array` **values** **(** **)** Returns the list of values in the ``Dictionary``.