godot/doc/classes/Dictionary.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="Dictionary" category="Built-In Types" version="3.2">
	<brief_description>
		Dictionary type.
	</brief_description>
	<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 [code]key: value[/code] pairs in curly braces [code]{}[/code].
		Erasing elements while iterating over them [b]is not supported[/b].
		Creating a dictionary:
		[codeblock]
		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}
		
		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.
		[/codeblock]
		To add a key to an existing dictionary, access it like an existing key and assign to it:
		[codeblock]
		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.
		[/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]
		
		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.
		[/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}
		
		func compare_dictionaries():
		    print(dir1.hash() == dir2.hash()) # Will print true.
		[/codeblock]
	</description>
	<tutorials>
		<link>https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_basics.html#dictionary</link>
	</tutorials>
	<methods>
		<method name="clear">
			<description>
				Clear the dictionary, removing all key/value pairs.
			</description>
		</method>
		<method name="duplicate">
			<return type="Dictionary">
			</return>
			<argument index="0" name="deep" type="bool" default="False">
			</argument>
			<description>
				Creates a copy of the dictionary, and returns it.
			</description>
		</method>
		<method name="empty">
			<return type="bool">
			</return>
			<description>
				Returns [code]true[/code] if the dictionary is empty.
			</description>
		</method>
		<method name="erase">
			<return type="bool">
			</return>
			<argument index="0" name="key" type="Variant">
			</argument>
			<description>
				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.
			</description>
		</method>
		<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>
				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.
			</description>
		</method>
		<method name="has">
			<return type="bool">
			</return>
			<argument index="0" name="key" type="Variant">
			</argument>
			<description>
				Returns [code]true[/code] if the dictionary has a given key.
			</description>
		</method>
		<method name="has_all">
			<return type="bool">
			</return>
			<argument index="0" name="keys" type="Array">
			</argument>
			<description>
				Returns [code]true[/code] if the dictionary has all of the keys in the given array.
			</description>
		</method>
		<method name="hash">
			<return type="int">
			</return>
			<description>
				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]
			</description>
		</method>
		<method name="keys">
			<return type="Array">
			</return>
			<description>
				Returns the list of keys in the [Dictionary].
			</description>
		</method>
		<method name="size">
			<return type="int">
			</return>
			<description>
				Returns the size of the dictionary (in pairs).
			</description>
		</method>
		<method name="values">
			<return type="Array">
			</return>
			<description>
				Returns the list of values in the [Dictionary].
			</description>
		</method>
	</methods>
	<constants>
	</constants>
</class>