godot-docs/classes/class_dictionary.rst

: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/<name>/doc_classes.

.. _class_Dictionary:

Dictionary
==========

Dictionary type.

Description
-----------

Dictionary type. Associative container which contains values referenced by unique keys. Dictionaries are always passed by reference.

Erasing elements while iterating over them **is not supported**.

Creating a dictionary:

::

    var d = {4: 5, "A key": "A value", 28: [1, 2, 3]}

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

::

    d[4] = "hello"  # Add integer 4 as a key and assign the String "hello" as its value.
    d["Godot"] = 3.01  # Add String "Godot" as a key and assign the value 3.01 to it.

Tutorials
---------

- `#dictionary <../getting_started/scripting/gdscript/gdscript_basics.html#dictionary>`_ in :doc:`../getting_started/scripting/gdscript/gdscript_basics`

Methods
-------

+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| void                                | :ref:`clear<class_Dictionary_method_clear>` **(** **)**                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Dictionary<class_Dictionary>` | :ref:`duplicate<class_Dictionary_method_duplicate>` **(** :ref:`bool<class_bool>` deep=False **)**                                |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`             | :ref:`empty<class_Dictionary_method_empty>` **(** **)**                                                                           |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`             | :ref:`erase<class_Dictionary_method_erase>` **(** :ref:`Variant<class_Variant>` key **)**                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>`       | :ref:`get<class_Dictionary_method_get>` **(** :ref:`Variant<class_Variant>` key, :ref:`Variant<class_Variant>` default=Null **)** |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`             | :ref:`has<class_Dictionary_method_has>` **(** :ref:`Variant<class_Variant>` key **)**                                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`             | :ref:`has_all<class_Dictionary_method_has_all>` **(** :ref:`Array<class_Array>` keys **)**                                        |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`               | :ref:`hash<class_Dictionary_method_hash>` **(** **)**                                                                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>`           | :ref:`keys<class_Dictionary_method_keys>` **(** **)**                                                                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`               | :ref:`size<class_Dictionary_method_size>` **(** **)**                                                                             |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>`           | :ref:`values<class_Dictionary_method_values>` **(** **)**                                                                         |
+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+

Method Descriptions
-------------------

.. _class_Dictionary_method_clear:

- void **clear** **(** **)**

Clear the dictionary, removing all key/value pairs.

----

.. _class_Dictionary_method_duplicate:

- :ref:`Dictionary<class_Dictionary>` **duplicate** **(** :ref:`bool<class_bool>` deep=False **)**

Creates a copy of the dictionary, and returns it.

----

.. _class_Dictionary_method_empty:

- :ref:`bool<class_bool>` **empty** **(** **)**

Returns ``true`` if the dictionary is empty.

----

.. _class_Dictionary_method_erase:

- :ref:`bool<class_bool>` **erase** **(** :ref:`Variant<class_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<class_Variant>` **get** **(** :ref:`Variant<class_Variant>` key, :ref:`Variant<class_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<class_bool>` **has** **(** :ref:`Variant<class_Variant>` key **)**

Returns ``true`` if the dictionary has a given key.

----

.. _class_Dictionary_method_has_all:

- :ref:`bool<class_bool>` **has_all** **(** :ref:`Array<class_Array>` keys **)**

Returns ``true`` if the dictionary has all of the keys in the given array.

----

.. _class_Dictionary_method_hash:

- :ref:`int<class_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<class_Array>` **keys** **(** **)**

Returns the list of keys in the ``Dictionary``.

----

.. _class_Dictionary_method_size:

- :ref:`int<class_int>` **size** **(** **)**

Returns the size of the dictionary (in pairs).

----

.. _class_Dictionary_method_values:

- :ref:`Array<class_Array>` **values** **(** **)**

Returns the list of values in the ``Dictionary``.