maxmustermann/godot
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #43533 from Calinou/doc-improve-dictionary

Browse source 
Improve the Dictionary class documentation
This commit is contained in:
Rémi Verschelde 2020-11-16 12:52:01 +01:00 committed by GitHub
parent 1b98b19455 5325de4e6b
commit 8e1765d9c7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 47 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/classes/Array.xml
View file

@ -38,8 +38,9 @@
GD.Print(array1 + array2); // Prints [One, 2, 3, Four]
[/csharp]
[/codeblocks]
Note that concatenating with [code]+=[/code] operator will create a new array. If you want to append another array to an existing array, [method append_array] is more efficient.
[b]Note:[/b] Concatenating with the [code]+=[/code] operator will create a new array, which has a cost. If you want to append another array to an existing array, [method append_array] is more efficient.
[b]Note:[/b] Arrays are always passed by reference. To get a copy of an array which can be modified independently of the original array, use [method duplicate].
[b]Note:[/b] When declaring an array with [code]const[/code], the array itself can still be mutated by defining the values at individual indices or pushing/removing elements. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized.
</description>
<tutorials>
</tutorials>

78
doc/classes/Dictionary.xml
View file

@ -11,17 +11,28 @@
Creating a dictionary:
[codeblocks]
[gdscript]
var my_dir = {} # Creates an empty dictionary.
var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
var another_dir = {
key1: value1,
key2: value2,
key3: value3,
var my_dict = {} # Creates an empty dictionary.
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}
# Alternative Lua-style syntax.
# Doesn't require quotes around keys, but only string constants can be used as key names.
# Additionally, key names must start with a letter or an underscore.
# Here, `some_key` is a string literal, not a variable!
another_dict = {
some_key = 42,
}
[/gdscript]
[csharp]
var myDir = new Godot.Collections.Dictionary(); // Creates an empty dictionary.
var pointsDir = new Godot.Collections.Dictionary
var myDict = new Godot.Collections.Dictionary(); // Creates an empty dictionary.
var pointsDict = new Godot.Collections.Dictionary
{
{"White", 50},
{"Yellow", 75},
@ -33,15 +44,15 @@
[codeblocks]
[gdscript]
export(string, "White", "Yellow", "Orange") var my_color
var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
func _ready():
# We can't use dot syntax here as `my_color` is a variable.
var points = points_dir[my_color]
var points = points_dict[my_color]
[/gdscript]
[csharp]
[Export(PropertyHint.Enum, "White,Yellow,Orange")]
public string MyColor { get; set; }
public Godot.Collections.Dictionary pointsDir = new Godot.Collections.Dictionary
public Godot.Collections.Dictionary pointsDict = new Godot.Collections.Dictionary
{
{"White", 50},
{"Yellow", 75},
@ -50,7 +61,7 @@
public override void _Ready()
{
int points = (int)pointsDir[MyColor];
int points = (int)pointsDict[MyColor];
}
[/csharp]
[/codeblocks]
@ -58,7 +69,7 @@
Dictionaries can contain more complex data:
[codeblocks]
[gdscript]
my_dir = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key.
my_dict = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key.
[/gdscript]
[csharp]
var myDir = new Godot.Collections.Dictionary
@ -70,8 +81,8 @@
To add a key to an existing dictionary, access it like an existing key and assign to it:
[codeblocks]
[gdscript]
var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
points_dir["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.
var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.
[/gdscript]
[csharp]
var pointsDir = new Godot.Collections.Dictionary
@ -80,7 +91,7 @@
{"Yellow", 75},
{"Orange", 100}
};
pointsDir["blue"] = 150; // Add "Blue" as a key and assign 150 as its value.
pointsDict["blue"] = 150; // Add "Blue" as a key and assign 150 as its value.
[/csharp]
[/codeblocks]
Finally, dictionaries can contain different types of keys and values in the same dictionary:
@ -89,22 +100,22 @@
# This is a valid dictionary.
# To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`.
# Indexing styles can be mixed and matched depending on your needs.
var my_dir = {
var my_dict = {
"String Key": 5,
4: [1, 2, 3],
7: "Hello",
"sub_dir": {"sub_key": "Nested value"},
"sub_dict": {"sub_key": "Nested value"},
}
[/gdscript]
[csharp]
// This is a valid dictionary.
// To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`.
// Indexing styles can be mixed and matched depending on your needs.
var myDir = new Godot.Collections.Dictionary {
var myDict = new Godot.Collections.Dictionary {
{"String Key", 5},
{4, new Godot.Collections.Array{1,2,3}},
{7, "Hello"},
{"sub_dir", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}}
{"sub_dict", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}}
};
[/csharp]
[/codeblocks]
@ -117,11 +128,11 @@
func compare_arrays():
print(array1 == array2) # Will print true.
var dir1 = {"a": 1, "b": 2, "c": 3}
var dir2 = {"a": 1, "b": 2, "c": 3}
var dict1 = {"a": 1, "b": 2, "c": 3}
var dict2 = {"a": 1, "b": 2, "c": 3}
func compare_dictionaries():
print(dir1 == dir2) # Will NOT print true.
print(dict1 == dict2) # Will NOT print true.
[/gdscript]
[csharp]
// You have to use GD.Hash().
@ -135,35 +146,36 @@
GD.Print(GD.Hash(array1) == GD.Hash(array2)); // Will print true.
}
public Godot.Collections.Dictionary dir1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public Godot.Collections.Dictionary dir2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public void CompareDictionaries()
{
GD.Print(dir1 == dir2); // Will NOT print true.
GD.Print(dict1 == dict2); // Will NOT print true.
}
[/csharp]
[/codeblocks]
You need to first calculate the dictionary's hash with [method hash] before you can compare them:
[codeblocks]
[gdscript]
var dir1 = {"a": 1, "b": 2, "c": 3}
var dir2 = {"a": 1, "b": 2, "c": 3}
var dict1 = {"a": 1, "b": 2, "c": 3}
var dict2 = {"a": 1, "b": 2, "c": 3}
func compare_dictionaries():
print(dir1.hash() == dir2.hash()) # Will print true.
print(dict1.hash() == dict2.hash()) # Will print true.
[/gdscript]
[csharp]
// You have to use GD.Hash().
public Godot.Collections.Dictionary dir1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public Godot.Collections.Dictionary dir2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}};
public void CompareDictionaries()
{
GD.Print(GD.Hash(dir1) == GD.Hash(dir2)); // Will print true.
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Will print true.
}
[/csharp]
[/codeblocks]
[b]Note:[/b] When declaring a dictionary with [code]const[/code], the dictionary itself can still be mutated by defining the values of individual keys. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized.
</description>
<tutorials>
<link title="GDScript basics: Dictionary">https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_basics.html#dictionary</link>
@ -322,7 +334,7 @@
<return type="int">
</return>
<description>
Returns the size of the dictionary (in pairs).
Returns the number of keys in the dictionary.
</description>
</method>
<method name="values">