Overhaul Variant Documentation
Co-Authored-By: Mew Pur Pur <85438892+MewPurPur@users.noreply.github.com>
This commit is contained in:
Micky
parent
28e65b0e4e
commit
f6ce87ff6c
|
|
@ -1,83 +1,117 @@
|
|||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<class name="Variant" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
||||
<brief_description>
|
||||
The most important data type in Godot.
|
||||
The most fundamental data type in Godot.
|
||||
</brief_description>
|
||||
<description>
|
||||
In computer programming, a Variant class is a class that is designed to store a variety of other types. Dynamic programming languages like PHP, Lua, JavaScript and GDScript like to use them to store variables' data on the backend. With these Variants, properties are able to change value types freely.
|
||||
[codeblocks]
|
||||
[gdscript]
|
||||
var foo = 2 # foo is dynamically an integer
|
||||
foo = "Now foo is a string!"
|
||||
foo = RefCounted.new() # foo is an Object
|
||||
var bar: int = 2 # bar is a statically typed integer.
|
||||
# bar = "Uh oh! I can't make statically typed variables become a different type!"
|
||||
[/gdscript]
|
||||
[csharp]
|
||||
// C# is statically typed. Once a variable has a type it cannot be changed. You can use the `var` keyword to let the compiler infer the type automatically.
|
||||
var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is `long`.
|
||||
// foo = "foo was and will always be an integer. It cannot be turned into a string!";
|
||||
var boo = "Boo is a string!";
|
||||
var ref = new RefCounted(); // var is especially useful when used together with a constructor.
|
||||
In computer programming, a [Variant] class is designed to store a variety of other types. Dynamic programming languages like PHP, Lua, JavaScript, and GDScript tend to use them to store the data of variables internally.
|
||||
|
||||
// Godot also provides a Variant type that works like a union of all the Variant-compatible types.
|
||||
Variant fooVar = 2; // fooVar is dynamically an integer (stored as a `long` in the Variant type).
|
||||
fooVar = "Now fooVar is a string!";
|
||||
fooVar = new RefCounted(); // fooVar is a GodotObject.
|
||||
[/csharp]
|
||||
[/codeblocks]
|
||||
Godot tracks all scripting API variables within Variants. Without even realizing it, you use Variants all the time. When a particular language enforces its own rules for keeping data typed, then that language is applying its own custom logic over the base Variant scripting API.
|
||||
- GDScript automatically wrap values in them. It keeps all data in plain Variants by default and then optionally enforces custom static typing rules on variable types.
|
||||
- C# is statically typed, but uses its own implementation of the Variant type in place of Godot's [Variant] class when it needs to represent a dynamic value. C# Variant can be assigned any compatible type implicitly but converting requires an explicit cast.
|
||||
The global [method @GlobalScope.typeof] function returns the enumerated value of the Variant type stored in the current variable (see [enum Variant.Type]).
|
||||
Godot tracks all scripting API variables within variants. When a particular language enforces its own rules for keeping data typed, that language is applying its own custom logic over the base Variant scripting API:
|
||||
- GDScript automatically wraps values in them. It keeps all data in plain variants by default and then optionally enforces custom static typing rules on variable types.
|
||||
- C# is statically typed, but uses its own implementation of Variant when it needs to represent a dynamic value. A Variant can be assigned any compatible type implicitly, but converting requires an explicit cast.
|
||||
|
||||
?? This allows Variants to facilitate communication between all of Godot's systems. These systems are all made more accessible in Godot.
|
||||
?? Using variants
|
||||
?? Their dynamic nature allows Variant types to simplify communication between all of Godot's systems.
|
||||
|
||||
A [Variant] in Godot can store almost any data type inside of it. Those can be roughly categorized as:
|
||||
- The [code]null[/code] type. It represents no value, or nothing assigned, and is the default type. In Godot, all [code]void[/code] functions return [code]null[/code].
|
||||
- [b]Atomic[/b] types, the most basic data types in Godot: [bool], [int], [float], [String].
|
||||
- [b]Complex[/b] types, which consist of atomic types. They represent common structures like vectors and colors, and allow you to easily work with them: [Color], [Vector2], [Transform3D], etc.
|
||||
- [b]Container[/b] types, which can store multiple other variants, including other containers: [Dictionary], [Array]. This also includes packed arrays, which are like an [Array] that can only hold one type of data and handle it very efficiently: [PackedColorArray], [PackedInt32Array], etc.
|
||||
- The [Object] type, inherited by every object in Godot, such as [Node], [Resource], [Engine], etc.
|
||||
- Miscellaneous types that do not belong in a specific category: [Callable], [Signal], [RID], etc.
|
||||
In GDScript, to check the type of a variant, you can use the [code]is[/code] operator or [method @GlobalScope.typeof], which will return one of the [enum Variant.Type] constants.
|
||||
[codeblocks]
|
||||
[gdscript]
|
||||
var foo = 2
|
||||
match typeof(foo):
|
||||
var my_variant = 2
|
||||
if my_variant is int:
|
||||
print("my_variant is an integer.")
|
||||
elif my_variant is Object:
|
||||
print("my_variant is an object.)
|
||||
|
||||
match typeof(my_variant):
|
||||
TYPE_NIL:
|
||||
print("foo is null")
|
||||
print("my_variant is null.")
|
||||
TYPE_INT:
|
||||
print("foo is an integer")
|
||||
print("my_variant is an integer.")
|
||||
TYPE_OBJECT:
|
||||
# Note that Objects are their own special category.
|
||||
# To get the name of the underlying Object type, you need the `get_class()` method.
|
||||
print("foo is a(n) %s" % foo.get_class()) # inject the class name into a formatted string.
|
||||
# Note that this does not get the script's `class_name` global identifier.
|
||||
# If the `class_name` is needed, use `foo.get_script().get_global_name()` instead.
|
||||
print("my_variant is a(n) %s." % my_variant.get_class())
|
||||
|
||||
[/gdscript]
|
||||
[csharp]
|
||||
Variant foo = 2;
|
||||
switch (foo.VariantType)
|
||||
Variant my_variant = 2;
|
||||
switch (my_variant.VariantType)
|
||||
{
|
||||
case Variant.Type.Nil:
|
||||
GD.Print("foo is null");
|
||||
GD.Print("my_variant is null");
|
||||
break;
|
||||
case Variant.Type.Int:
|
||||
GD.Print("foo is an integer");
|
||||
GD.Print("my_variant is an integer");
|
||||
break;
|
||||
case Variant.Type.Object:
|
||||
// Note that Objects are their own special category.
|
||||
// You can convert a Variant to a GodotObject and use reflection to get its name.
|
||||
GD.Print($"foo is a(n) {foo.AsGodotObject().GetType().Name}");
|
||||
GD.Print("my_variant is an object");
|
||||
break;
|
||||
}
|
||||
[/csharp]
|
||||
[/codeblocks]
|
||||
A Variant takes up only 20 bytes and can store almost any engine datatype inside of it. Variants are rarely used to hold information for long periods of time. Instead, they are used mainly for communication, editing, serialization and moving data around.
|
||||
Godot has specifically invested in making its Variant class as flexible as possible; so much so that it is used for a multitude of operations to facilitate communication between all of Godot's systems.
|
||||
A Variant:
|
||||
- Can store almost any datatype.
|
||||
- Can perform operations between many variants. GDScript uses Variant as its atomic/native datatype.
|
||||
- Can be hashed, so it can be compared quickly to other variants.
|
||||
- Can be used to convert safely between datatypes.
|
||||
- Can be used to abstract calling methods and their arguments. Godot exports all its functions through variants.
|
||||
- Can be used to defer calls or move data between threads.
|
||||
- Can be serialized as binary and stored to disk, or transferred via network.
|
||||
- Can be serialized to text and use it for printing values and editable settings.
|
||||
- Can work as an exported property, so the editor can edit it universally.
|
||||
- Can be used for dictionaries, arrays, parsers, etc.
|
||||
[b]Containers (Array and Dictionary):[/b] Both are implemented using variants. A [Dictionary] can match any datatype used as key to any other datatype. An [Array] just holds an array of Variants. Of course, a Variant can also hold a [Dictionary] and an [Array] inside, making it even more flexible.
|
||||
Modifications to a container will modify all references to it. A [Mutex] should be created to lock it if multi-threaded access is desired.
|
||||
[b]Note:[/b] To get the name of the underlying Object type, see [method get_class()]. In C#, you can convert a [Variant] to a [code]GodotObject[/code] and use reflection to get its name.
|
||||
[codeblocks]
|
||||
[gdscript]
|
||||
print("obj is a(n) %s." % obj.get_class())
|
||||
[/gdscript]
|
||||
[csharp]
|
||||
GD.Print($"obj is a(n) {obj.AsGodotObject().GetType().Name}");
|
||||
[/csharp]
|
||||
[/codeblocks]
|
||||
|
||||
Variants allow properties to change their type freely.
|
||||
[codeblocks]
|
||||
[gdscript]
|
||||
var my_variant = 2 # my_variant is dynamically an integer.
|
||||
my_variant = "Now my_variant is a string!"
|
||||
my_variant = RefCounted.new() # my_variant is now an Object.
|
||||
|
||||
var number: int = 2 # bar is a statically typed integer.
|
||||
# number = "Uh oh! I can't change the type of statically typed variables!"
|
||||
[/gdscript]
|
||||
[csharp]
|
||||
// C# is statically typed. Once a variable has a type it cannot be changed.
|
||||
// You can use the `var` keyword to let the compiler infer the type automatically.
|
||||
var number = 2; // number is a 32-bit integer (int).
|
||||
// number = "number will always be an integer. It cannot be turned into a string!";
|
||||
var message = "boo is a string!";
|
||||
var ref = new RefCounted(); // var is especially useful when used together with a constructor.
|
||||
|
||||
// Godot also provides a Variant type that works like a union of all the Variant-compatible types.
|
||||
Variant myVar = 2; // myVar is dynamically an integer (stored as a `long` in the Variant type).
|
||||
myVar = "Now myVar is a string!";
|
||||
myVar = new RefCounted(); // myVar is now a GodotObject.
|
||||
[/csharp]
|
||||
[/codeblocks]
|
||||
|
||||
[b]Value VS. Reference[/b]
|
||||
Most variants are passed by [b]value[/b]: When assigned or passed in a function, an independent copy is created which does not affect the original.
|
||||
[codeblock]
|
||||
var first_number = 6
|
||||
var other_number = first_number
|
||||
|
||||
first_number += 4
|
||||
|
||||
print(first_number) # Prints 10
|
||||
print(other_number) # Prints 6
|
||||
[/codeblock]
|
||||
All container types and [Object]-inheriting types are passed by [b]reference[/b]: When assigned or passed in a function, the same reference is passed. Any changes applied to the new variable will also affect the original variable, as they both point to the same reference.
|
||||
[codeblock]
|
||||
var first_array = [2, 5, 0, 8]
|
||||
var other_array = first_array
|
||||
|
||||
my_array.erase(0)
|
||||
|
||||
print(first_array) # Prints [2, 5, 8]
|
||||
print(other_array) # Prints [2, 5, 8]
|
||||
[/codeblock]
|
||||
If necessary, most of these types also provide methods to create independent copies, such as [method Array.duplicate] and [method Node.duplicate]. To check if two references are the same, use [method @GlobalScope.is_same] or, for [Object] types, the equality ([code]==[/code]) operator.
|
||||
</description>
|
||||
<tutorials>
|
||||
<link title="Variant class introduction">$DOCS_URL/contributing/development/core_and_modules/variant_class.html</link>
|
||||
|
|
|
|||
Loading…
Reference in New Issue