2017-09-12 20:42:36 +00:00
<?xml version="1.0" encoding="UTF-8" ?>
2020-01-26 15:01:49 +00:00
<class name= "Dictionary" version= "3.2" >
2017-09-12 20:42:36 +00:00
<brief_description >
Dictionary type.
</brief_description>
<description >
2020-01-20 08:28:31 +00:00
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 [code]key: value[/code] pairs in curly braces [code]{}[/code].
2019-02-10 20:28:22 +00:00
Erasing elements while iterating over them [b]is not supported[/b].
2019-03-14 00:08:14 +00:00
Creating a dictionary:
[codeblock]
2020-01-20 08:28:31 +00:00
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,
}
[/codeblock]
You can access values of a dictionary by referencing appropriate key in above example [code]points_dir["White"][/code] would return value of 50.
[codeblock]
export(String, "White", "Yellow", "Orange") var my_color
var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
2020-01-23 10:14:14 +00:00
2020-01-20 08:28:31 +00:00
func _ready():
var points = points_dir[my_color]
[/codeblock]
In the above code [code]points[/code] will be assigned the value that is paired with the appropriate color selected in [code]my_color[/code].
Dictionaries can contain more complex data:
[codeblock]
my_dir = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key.
2019-03-14 00:08:14 +00:00
[/codeblock]
To add a key to an existing dictionary, access it like an existing key and assign to it:
[codeblock]
2020-01-20 08:28:31 +00:00
var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
2020-01-23 17:41:49 +00:00
var points_dir["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.
2020-01-20 08:28:31 +00:00
[/codeblock]
Finally, dictionaries can contain different types of keys and values in the same dictionary:
[codeblock]
var my_dir = {"String Key": 5, 4: [1, 2, 3], 7: "Hello"} # This is a valid dictionary.
[/codeblock]
[b]Note:[/b] Unlike [Array]s you can't compare dictionaries directly:
[codeblock]
array1 = [1, 2, 3]
array2 = [1, 2, 3]
2020-01-23 10:14:14 +00:00
2020-01-20 08:28:31 +00:00
func compare_arrays():
2020-01-23 10:14:14 +00:00
print(array1 == array2) # Will print true.
2020-01-20 08:28:31 +00:00
dir1 = {"a": 1, "b": 2, "c": 3}
dir2 = {"a": 1, "b": 2, "c": 3}
2020-01-23 10:14:14 +00:00
2020-01-20 08:28:31 +00:00
func compare_dictionaries():
print(dir1 == dir2) # Will NOT print true.
[/codeblock]
You need to first calculate the dictionary's hash with [method hash] before you can compare them:
[codeblock]
dir1 = {"a": 1, "b": 2, "c": 3}
dir2 = {"a": 1, "b": 2, "c": 3}
2020-01-23 10:14:14 +00:00
2020-01-20 08:28:31 +00:00
func compare_dictionaries():
print(dir1.hash() == dir2.hash()) # Will print true.
2019-03-14 00:08:14 +00:00
[/codeblock]
2017-09-12 20:42:36 +00:00
</description>
<tutorials >
2019-03-14 00:08:14 +00:00
<link > https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_basics.html#dictionary</link>
2017-09-12 20:42:36 +00:00
</tutorials>
<methods >
<method name= "clear" >
<description >
Clear the dictionary, removing all key/value pairs.
</description>
</method>
2017-12-18 07:13:58 +00:00
<method name= "duplicate" >
<return type= "Dictionary" >
</return>
2018-04-10 08:12:42 +00:00
<argument index= "0" name= "deep" type= "bool" default= "False" >
</argument>
2017-12-18 07:13:58 +00:00
<description >
2018-04-17 14:18:57 +00:00
Creates a copy of the dictionary, and returns it.
2017-12-18 07:13:58 +00:00
</description>
</method>
2017-09-12 20:42:36 +00:00
<method name= "empty" >
<return type= "bool" >
</return>
<description >
2019-05-24 02:15:43 +00:00
Returns [code]true[/code] if the dictionary is empty.
2017-09-12 20:42:36 +00:00
</description>
</method>
<method name= "erase" >
2018-08-20 22:35:30 +00:00
<return type= "bool" >
</return>
2018-08-31 20:38:28 +00:00
<argument index= "0" name= "key" type= "Variant" >
2017-09-12 20:42:36 +00:00
</argument>
<description >
2019-06-21 23:04:47 +00:00
Erase a dictionary key/value pair by key. Returns [code]true[/code] if the given key was present in the dictionary, [code]false[/code] otherwise. Does not erase elements while iterating over the dictionary.
2017-09-12 20:42:36 +00:00
</description>
</method>
2018-11-20 08:34:45 +00:00
<method name= "get" >
<return type= "Variant" >
</return>
<argument index= "0" name= "key" type= "Variant" >
</argument>
<argument index= "1" name= "default" type= "Variant" default= "Null" >
</argument>
<description >
2019-06-21 23:04:47 +00:00
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 [code]null[/code] if it is omitted.
2018-11-20 08:34:45 +00:00
</description>
</method>
2017-09-12 20:42:36 +00:00
<method name= "has" >
<return type= "bool" >
</return>
2018-08-31 20:38:28 +00:00
<argument index= "0" name= "key" type= "Variant" >
2017-09-12 20:42:36 +00:00
</argument>
<description >
2019-05-24 02:15:43 +00:00
Returns [code]true[/code] if the dictionary has a given key.
2017-09-12 20:42:36 +00:00
</description>
</method>
<method name= "has_all" >
<return type= "bool" >
</return>
<argument index= "0" name= "keys" type= "Array" >
</argument>
<description >
2019-05-24 02:15:43 +00:00
Returns [code]true[/code] if the dictionary has all of the keys in the given array.
2017-09-12 20:42:36 +00:00
</description>
</method>
<method name= "hash" >
<return type= "int" >
</return>
<description >
2019-11-11 13:18:11 +00:00
Returns a hashed integer value representing the dictionary contents. This can be used to compare dictionaries by value:
[codeblock]
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())
[/codeblock]
2017-09-12 20:42:36 +00:00
</description>
</method>
<method name= "keys" >
<return type= "Array" >
</return>
<description >
2019-05-24 02:15:43 +00:00
Returns the list of keys in the [Dictionary].
2017-09-12 20:42:36 +00:00
</description>
</method>
<method name= "size" >
<return type= "int" >
</return>
<description >
2019-05-24 02:15:43 +00:00
Returns the size of the dictionary (in pairs).
2017-09-12 20:42:36 +00:00
</description>
</method>
<method name= "values" >
<return type= "Array" >
</return>
<description >
2019-05-24 02:15:43 +00:00
Returns the list of values in the [Dictionary].
2017-09-12 20:42:36 +00:00
</description>
</method>
</methods>
<constants >
</constants>
</class>