Skip to content

Commit c82da08

Browse files
CalinouCalinou
committed
Add a table listing STL datatypes and their Godot equivalents in C++ usage guidelines
This is more comprehensive than the previous advice.
1 parent 4124f61 commit c82da08

File tree

1 file changed

+66
-12
lines changed

1 file changed

+66
-12
lines changed

‎contributing/development/cpp_usage_guidelines.rst‎

Lines changed: 66 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -53,18 +53,72 @@ as Godot provides its own data types (among other things).
5353
See :ref:`doc_faq_why_not_stl` for more information.
5454

5555
This means that pull requests should **not** use ``std::string``,
56-
``std::vector`` and the like. Instead, use Godot's datatypes as described below:
57-
58-
- Use ``String`` instead of ``std::string``.
59-
- Use ``Vector`` instead of ``std::vector``. In some cases, ``LocalVector``
60-
can be used as an alternative (ask core developers first).
61-
- Use ``Array`` instead of ``std::array``.
62-
63-
.. note::
64-
65-
Godot also has a List datatype (which is a linked list). While List is already used
66-
in the codebase, it typically performs worse than other datatypes like Vector
67-
and Array. Therefore, List should be avoided in new code unless necessary.
56+
``std::vector`` and the like. Instead, use Godot's datatypes as described below.
57+
A 📜 icon denotes the type is part of :ref:`Variant <doc_variant_class>`. This
58+
means it can be used as a parameter or return value of a method exposed to the
59+
scripting API.
60+
61+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
62+
| Godot datatype | Closest C++ STL datatype | Comment |
63+
+========================+==========================+=======================================================================================+
64+
| ``String`` 📜 | ``std::string`` | **Use this as the "default" string type.** ``String`` uses UTF-32 encoding |
65+
| | | to improve performance thanks to its fixed character size. |
66+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
67+
| ``StringName`` 📜 | ``std::string`` | Uses string interning for fast comparisons. Use this for static strings that are |
68+
| | | referenced frequently and used in multiple locations in the engine. |
69+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
70+
| ``Vector`` | ``std::vector`` | **Use this as the "default" vector type.** Uses copy-on-write (COW) semantics. |
71+
| | | This means it's generally slower but can be copied around almost for free. |
72+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
73+
| ``LocalVector`` | ``std::vector`` | Closer to ``std::vector`` in semantics. In most situations, ``Vector`` should be |
74+
| | | preferred. |
75+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
76+
| ``Array`` 📜 | ``std::vector`` | Values can be of any Variant type. No static typing is imposed. |
77+
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
78+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
79+
| ``TypedArray`` 📜 | ``std::vector`` | Subclass of ``Array`` but with static typing for its elements. |
80+
| | | Not to be confused with ``Packed*Array``, which is internally a ``Vector``. |
81+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
82+
| ``Packed*Array`` 📜 | ``std::vector`` | Alias of ``Vector``, e.g. ``PackedColorArray = Vector<Color>``. |
83+
| | | Only a limited list of packed array types are available |
84+
| | | (use ``TypedArray`` otherwise). |
85+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
86+
| ``List`` | ``std::list`` | Linked list type. Generally slower than other array/vector types. Prefer using |
87+
| | | other types in new code, unless using ``List`` avoids the need for type conversions. |
88+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
89+
| ``Span`` | ``std::span`` | Represents read-only access to a contiguous array without needing to copy any data. |
90+
| | | See `pull request description <https://github.com/godotengine/godot/pull/100293>`__ |
91+
| | | for details. |
92+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
93+
| ``HashSet`` | ``std::unordered_set`` | **Use this as the "default" set type.** |
94+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
95+
| ``RBSet`` | ``std::set`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__ |
96+
| | | for faster access. |
97+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
98+
| ``VSet`` | ``std::flat_set`` | Uses copy-on-write (COW) semantics. |
99+
| | | This means it's generally slower but can be copied around almost for free. |
100+
| | | The performance benefits of ``VSet`` aren't established, so prefer using other types. |
101+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
102+
| ``HashMap`` | ``std::unordered_map`` | **Use this as the "default" map type.** Does not preserve insertion order. |
103+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
104+
| ``AHashMap`` | ``std::unordered_map`` | Array-based implementation of a hash map. Does not preserve insertion order. |
105+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
106+
| ``OAHashMap`` | ``std::unordered_map`` | Does not preserve insertion order. |
107+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
108+
| ``RBMap`` | ``std::map`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__ |
109+
| | | for faster access. |
110+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
111+
| ``VMap`` | ``std::flat_map`` | Uses copy-on-write (COW) semantics. |
112+
| | | This means it's generally slower but can be copied around almost for free. |
113+
| | | The performance benefits of ``VMap`` aren't established, so prefer using other types. |
114+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
115+
| ``Dictionary`` 📜 | ``std::unordered_map`` | Keys and values can be of any Variant type. No static typing is imposed. |
116+
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
117+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
118+
| ``TypedDictionary`` 📜 | ``std::unordered_map`` | Subclass of ``Dictionary`` but with static typing for its keys and values. |
119+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
120+
| ``Pair`` | ``std::pair`` | Stores a single key-value pair. |
121+
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
68122

69123
``auto`` keyword
70124
~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)