Skip to content

Commit be9be7f

Browse files
mhilbrunnermhilbrunner
authored
Merge pull request #10093 from Calinou/variant-not-null
Document Variant not being nullable
2 parents 82dc5e3 + cbf61b3 commit be9be7f

File tree

2 files changed

+122
-23
lines changed

2 files changed

+122
-23
lines changed

‎contributing/development/core_and_modules/variant_class.rst‎

Lines changed: 117 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,21 @@ Variant class
66
About
77
-----
88

9-
Variant is the most important datatype of Godot, it's the most important
10-
class in the engine. A Variant takes up only 20 bytes and can store
11-
almost any engine datatype inside of it. Variants are rarely used to
12-
hold information for long periods of time, instead they are used mainly
13-
for communication, editing, serialization and generally moving data
14-
around.
9+
Variant is the most important datatype in Godot. A Variant takes up only 24
10+
bytes on 64-bit platforms (20 bytes on 32-bit platforms) and can store almost
11+
any engine datatype inside of it. Variants are rarely used to hold information
12+
for long periods of time, instead they are used mainly for communication,
13+
editing, serialization and generally moving data around.
1514

1615
A Variant can:
1716

18-
- Store almost any datatype
17+
- Store almost any datatype.
1918
- Perform operations between many variants (GDScript uses Variant as
2019
its atomic/native datatype).
21-
- Be hashed, so it can be compared quickly to other variants
22-
- Be used to convert safely between datatypes
20+
- Be hashed, so it can be compared quickly to other variants.
21+
- Be used to convert safely between datatypes.
2322
- Be used to abstract calling methods and their arguments (Godot
24-
exports all its functions through variants)
23+
exports all its functions through variants).
2524
- Be used to defer calls or move data between threads.
2625
- Be serialized as binary and stored to disk, or transferred via
2726
network.
@@ -34,27 +33,122 @@ Basically, thanks to the Variant class, writing Godot itself was a much,
3433
much easier task, as it allows for highly dynamic constructs not common
3534
of C++ with little effort. Become a friend of Variant today.
3635

37-
References:
38-
~~~~~~~~~~~
36+
.. note::
37+
38+
All types within Variant except Nil and Object **cannot** be ``null`` and
39+
must always store a valid value. These types within Variant are therefore
40+
called *non-nullable* types.
41+
42+
One of the Variant types is *Nil* which can only store the value ``null``.
43+
Therefore, it is possible for a Variant to contain the value ``null``, even
44+
though all Variant types excluding Nil and Object are non-nullable.
45+
46+
References
47+
~~~~~~~~~~
3948

4049
- `core/variant/variant.h <https://github.com/godotengine/godot/blob/master/core/variant/variant.h>`__
4150

42-
Containers: Dictionary and Array
51+
List of variant types
52+
---------------------
53+
54+
These types are available in Variant:
55+
56+
+---------------------------------+---------------------------+
57+
| Type | Notes |
58+
+=================================+===========================+
59+
| Nil (can only store ``null``) | Nullable type |
60+
+---------------------------------+---------------------------+
61+
| :ref:`class_bool` | |
62+
+---------------------------------+---------------------------+
63+
| :ref:`class_int` | |
64+
+---------------------------------+---------------------------+
65+
| :ref:`class_float` | |
66+
+---------------------------------+---------------------------+
67+
| :ref:`class_string` | |
68+
+---------------------------------+---------------------------+
69+
| :ref:`class_vector2` | |
70+
+---------------------------------+---------------------------+
71+
| :ref:`class_vector2i` | |
72+
+---------------------------------+---------------------------+
73+
| :ref:`class_rect2` | 2D counterpart of AABB |
74+
+---------------------------------+---------------------------+
75+
| :ref:`class_rect2i` | |
76+
+---------------------------------+---------------------------+
77+
| :ref:`class_vector3` | |
78+
+---------------------------------+---------------------------+
79+
| :ref:`class_vector3i` | |
80+
+---------------------------------+---------------------------+
81+
| :ref:`class_transform2d` | |
82+
+---------------------------------+---------------------------+
83+
| :ref:`class_vector4` | |
84+
+---------------------------------+---------------------------+
85+
| :ref:`class_vector4i` | |
86+
+---------------------------------+---------------------------+
87+
| :ref:`class_plane` | |
88+
+---------------------------------+---------------------------+
89+
| :ref:`class_quaternion` | |
90+
+---------------------------------+---------------------------+
91+
| :ref:`class_aabb` | 3D counterpart of Rect2 |
92+
+---------------------------------+---------------------------+
93+
| :ref:`class_basis` | |
94+
+---------------------------------+---------------------------+
95+
| :ref:`class_transform3d` | |
96+
+---------------------------------+---------------------------+
97+
| :ref:`class_projection` | |
98+
+---------------------------------+---------------------------+
99+
| :ref:`class_color` | |
100+
+---------------------------------+---------------------------+
101+
| :ref:`class_stringname` | |
102+
+---------------------------------+---------------------------+
103+
| :ref:`class_nodepath` | |
104+
+---------------------------------+---------------------------+
105+
| :ref:`class_rid` | |
106+
+---------------------------------+---------------------------+
107+
| :ref:`class_object` | Nullable type |
108+
+---------------------------------+---------------------------+
109+
| :ref:`class_callable` | |
110+
+---------------------------------+---------------------------+
111+
| :ref:`class_signal` | |
112+
+---------------------------------+---------------------------+
113+
| :ref:`class_dictionary` | |
114+
+---------------------------------+---------------------------+
115+
| :ref:`class_array` | |
116+
+---------------------------------+---------------------------+
117+
| :ref:`class_packedbytearray` | |
118+
+---------------------------------+---------------------------+
119+
| :ref:`class_packedint32array` | |
120+
+---------------------------------+---------------------------+
121+
| :ref:`class_packedint64array` | |
122+
+---------------------------------+---------------------------+
123+
| :ref:`class_packedfloat32array` | |
124+
+---------------------------------+---------------------------+
125+
| :ref:`class_packedfloat64array` | |
126+
+---------------------------------+---------------------------+
127+
| :ref:`class_packedstringarray` | |
128+
+---------------------------------+---------------------------+
129+
| :ref:`class_packedvector2array` | |
130+
+---------------------------------+---------------------------+
131+
| :ref:`class_packedvector3array` | |
132+
+---------------------------------+---------------------------+
133+
| :ref:`class_packedcolorarray` | |
134+
+---------------------------------+---------------------------+
135+
| :ref:`class_packedvector4array` | |
136+
+---------------------------------+---------------------------+
137+
138+
Containers: Array and Dictionary
43139
--------------------------------
44140

45-
Both are implemented using variants. A Dictionary can match any datatype
46-
used as key to any other datatype. An Array just holds an array of
47-
Variants. Of course, a Variant can also hold a Dictionary and an Array
48-
inside, making it even more flexible.
141+
Both :ref:`class_array` and :ref:`class_dictionary` are implemented using
142+
variants. A Dictionary can match any datatype used as key to any other datatype.
143+
An Array just holds an array of Variants. Of course, a Variant can also hold a
144+
Dictionary or an Array inside, making it even more flexible.
49145

50146
Modifications to a container will modify all references to
51-
it. A Mutex should be created to lock it if multi threaded access is
52-
desired.
53-
54-
Copy-on-write (COW) mode support for containers was dropped with Godot 3.0.
147+
it. A Mutex should be created to lock it if
148+
:ref:`multi-threaded access <doc_using_multiple_threads>` is desired.
55149

56-
References:
57-
~~~~~~~~~~~
150+
References
151+
~~~~~~~~~~
58152

59153
- `core/variant/dictionary.h <https://github.com/godotengine/godot/blob/master/core/variant/dictionary.h>`__
60154
- `core/variant/array.h <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__

‎tutorials/scripting/gdscript/gdscript_basics.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -684,6 +684,11 @@ null
684684
``null`` is an empty data type that contains no information and can not
685685
be assigned any other value.
686686

687+
Only types that inherit from Object can have a ``null`` value
688+
(Object is therefore called a "nullable" type).
689+
:ref:`Variant types <doc_variant_class>` must have a valid value at all times,
690+
and therefore cannot have a ``null`` value.
691+
687692
:ref:`bool <class_bool>`
688693
^^^^^^^^^^^^^^^^^^^^^^^^
689694

0 commit comments

Comments
 (0)