Skip to content

Commit 0b5a7c3

Browse files
skyace65skyace65
authored
Merge pull request #10988 from Calinou/cpp-usage-guidelines-link-to-core-types
Move C++ container type information from C++ usage guidelines to Core types
2 parents 3f65fd4 + 8d87843 commit 0b5a7c3

File tree

3 files changed

+109
-158
lines changed

3 files changed

+109
-158
lines changed

‎about/faq.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -579,7 +579,7 @@ general-purpose library, but we had special requirements for Godot.
579579
* We use our custom String type, as the one provided by STL is too basic and lacks proper
580580
internationalization support.
581581

582-
Check out :ref:`Godot's container types <doc_cpp_godot_types>` for alternatives.
582+
Check out :ref:`Godot's container types <doc_core_types>` for alternatives.
583583

584584
Why does Godot not use exceptions?
585585
----------------------------------

‎contributing/development/core_and_modules/core_types.rst‎

Lines changed: 105 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -20,20 +20,17 @@ more difficult to read.
2020
In general, care is not taken to use the most efficient datatype for a
2121
given task unless using large structures or arrays. ``int`` is used
2222
through most of the code unless necessary. This is done because nowadays
23-
every device has at least a 32 bits bus and can do such operations in
23+
every device has at least a 32-bit bus and can do such operations in
2424
one cycle. It makes code more readable too.
2525

26-
For files or memory sizes, ``size_t`` is used, which is warranted to be
27-
64 bits.
26+
For files or memory sizes, ``size_t`` is used, which is guaranteed to be
27+
64-bit.
2828

2929
For Unicode characters, CharType instead of wchar_t is used, because
3030
many architectures have 4 bytes long wchar_t, where 2 bytes might be
3131
desired. However, by default, this has not been forced and CharType maps
3232
directly to wchar_t.
3333

34-
References:
35-
~~~~~~~~~~~
36-
3734
- `core/typedefs.h <https://github.com/godotengine/godot/blob/master/core/typedefs.h>`__
3835

3936
Memory model
@@ -63,7 +60,7 @@ remain constant. In other words, leave 10-20% of your memory free
6360
and perform all small allocations and you are fine.
6461

6562
Godot ensures that all objects that can be allocated dynamically are
66-
small (less than a few kb at most). But what happens if an allocation is
63+
small (less than a few kB at most). But what happens if an allocation is
6764
too large (like an image or mesh geometry or large array)? In this case
6865
Godot has the option to use a dynamic memory pool. This memory needs to
6966
be locked to be accessed, and if an allocation runs out of memory, the
@@ -85,20 +82,21 @@ For C-style allocation, Godot provides a few macros:
8582
memrealloc()
8683
memfree()
8784
88-
These are equivalent to the usual malloc, realloc, free of the standard C
89-
library.
85+
These are equivalent to the usual ``malloc()``, ``realloc()``, and ``free()``
86+
of the C standard library.
9087

9188
For C++-style allocation, special macros are provided:
9289

9390
.. code-block:: none
9491
95-
memnew( Class / Class(args) )
96-
memdelete( instance )
92+
memnew(Class / Class(args))
93+
memdelete(instance)
9794
98-
memnew_arr( Class , amount )
99-
memdelete_arr( pointer to array )
95+
memnew_arr(Class, amount)
96+
memdelete_arr(pointer_to_array)
10097
101-
which are equivalent to new, delete, new[] and delete[].
98+
These are equivalent to ``new``, ``delete``, ``new[]``, and ``delete[]``
99+
respectively.
102100

103101
memnew/memdelete also use a little C++ magic and notify Objects right
104102
after they are created, and right before they are deleted.
@@ -128,107 +126,122 @@ its storage strategy. Prefer ``Vector<>`` (or ``LocalVector<>``) over
128126
``List<>`` unless you're sure you need it, as cache locality and memory
129127
fragmentation tend to be more important with small collections.
130128

131-
References:
132-
~~~~~~~~~~~
133-
134129
- `core/os/memory.h <https://github.com/godotengine/godot/blob/master/core/os/memory.h>`__
135130

136131
Containers
137132
----------
138133

139-
Godot provides also a set of common containers:
140-
141-
- Vector
142-
- List
143-
- Set
144-
- Map
145-
146-
They aim to be as minimal as possible, as templates
147-
in C++ are often inlined and make the binary size much fatter, both in
148-
debug symbols and code. List, Set and Map can be iterated using
149-
pointers, like this:
150-
151-
.. code-block:: cpp
152-
153-
for(List<int>::Element *E=somelist.front();E;E=E->next()) {
154-
print_line(E->get()); // print the element
155-
}
156-
157-
The Vector<> class also has a few nice features:
158-
159-
- It does copy on write, so making copies of it is cheap as long as
160-
they are not modified.
161-
- It supports multi-threading, by using atomic operations on the
162-
reference counter.
163-
164-
References:
165-
~~~~~~~~~~~
166-
167-
- `core/templates/vector.h <https://github.com/godotengine/godot/blob/master/core/templates/vector.h>`__
168-
- `core/templates/list.h <https://github.com/godotengine/godot/blob/master/core/templates/list.h>`__
169-
- `core/templates/set.h <https://github.com/godotengine/godot/blob/master/core/templates/hash_set.h>`__
170-
- `core/templates/map.h <https://github.com/godotengine/godot/blob/master/core/templates/hash_map.h>`__
171-
172-
String
173-
------
174-
175-
Godot also provides a String class. This class has a huge amount of
176-
features, full Unicode support in all the functions (like case
177-
operations) and utf8 parsing/extracting, as well as helpers for
178-
conversion and visualization.
179-
180-
References:
181-
~~~~~~~~~~~
182-
183-
- `core/string/ustring.h <https://github.com/godotengine/godot/blob/master/core/string/ustring.h>`__
184-
185-
StringName
186-
----------
187-
188-
StringNames are like a String, but they are unique. Creating a
189-
StringName from a string results in a unique internal pointer for all
190-
equal strings. StringNames are useful for using strings as
191-
identifier, as comparing them is basically comparing a pointer.
192-
193-
Creation of a StringName (especially a new one) is slow, but comparison
194-
is fast.
195-
196-
References:
197-
~~~~~~~~~~~
198-
199-
- `core/string/string_name.h <https://github.com/godotengine/godot/blob/master/core/string/string_name.h>`__
134+
Godot provides its own set of containers, which means STL containers like ``std::string``
135+
and ``std::vector`` are generally not used in the codebase.
136+
137+
A 📜 icon denotes the type is part of :ref:`Variant <doc_variant_class>`. This
138+
means it can be used as a parameter or return value of a method exposed to the
139+
scripting API.
140+
141+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
142+
| Godot datatype | Closest C++ STL datatype | Comment |
143+
+=======================+==========================+=======================================================================================+
144+
| |string| 📜 | ``std::string`` | **Use this as the "default" string type.** ``String`` uses UTF-32 encoding |
145+
| | | to improve performance thanks to its fixed character size. |
146+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
147+
| |vector| | ``std::vector`` | **Use this as the "default" vector type.** Uses copy-on-write (COW) semantics. |
148+
| | | This means it's generally slower but can be copied around almost for free. |
149+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
150+
| |hash_set| | ``std::unordered_set`` | **Use this as the "default" set type.** |
151+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
152+
| |hash_map| | ``std::unordered_map`` | **Use this as the "default" map type.** Preserves insertion order. |
153+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
154+
| |string_name| 📜 | ``std::string`` | Uses string interning for fast comparisons. Use this for static strings that are |
155+
| | | referenced frequently and used in multiple locations in the engine. |
156+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
157+
| |local_vector| | ``std::vector`` | Closer to ``std::vector`` in semantics. In most situations, ``Vector`` should be |
158+
| | | preferred. |
159+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
160+
| |array| 📜 | ``std::vector`` | Values can be of any Variant type. No static typing is imposed. |
161+
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
162+
| | | Uses Vector<Variant> internally. |
163+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
164+
| |typed_array| 📜 | ``std::vector`` | Subclass of ``Array`` but with static typing for its elements. |
165+
| | | Not to be confused with ``Packed*Array``, which is internally a ``Vector``. |
166+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
167+
| |packed_array| 📜 | ``std::vector`` | Alias of ``Vector``, e.g. ``PackedColorArray = Vector<Color>``. |
168+
| | | Only a limited list of packed array types are available |
169+
| | | (use ``TypedArray`` otherwise). |
170+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
171+
| |list| | ``std::list`` | Linked list type. Generally slower than other array/vector types. Prefer using |
172+
| | | other types in new code, unless using ``List`` avoids the need for type conversions. |
173+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
174+
| |fixed_vector| | ``std::array`` | Vector with a fixed capacity (more similar to ``boost::container::static_vector``). |
175+
| | | This container type is more efficient than other vector-like types because it makes |
176+
| | | no heap allocations. |
177+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
178+
| |span| | ``std::span`` | Represents read-only access to a contiguous array without needing to copy any data. |
179+
| | | See `pull request description <https://github.com/godotengine/godot/pull/100293>`__ |
180+
| | | for details. |
181+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
182+
| |rb_set| | ``std::set`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__ |
183+
| | | for faster access. |
184+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
185+
| |v_set| | ``std::flat_set`` | Uses copy-on-write (COW) semantics. |
186+
| | | This means it's generally slower but can be copied around almost for free. |
187+
| | | The performance benefits of ``VSet`` aren't established, so prefer using other types. |
188+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
189+
| |a_hash_map| | ``std::unordered_map`` | Array-based implementation of a hash map. Does not preserve insertion order. |
190+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
191+
| |rb_map| | ``std::map`` | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black-tree>`__ |
192+
| | | for faster access. |
193+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
194+
| |dictionary| 📜 | ``std::unordered_map`` | Keys and values can be of any Variant type. No static typing is imposed. |
195+
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
196+
| | | Preserves insertion order. Uses ``HashMap<Variant>`` internally. |
197+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
198+
| |typed_dictionary| 📜 | ``std::unordered_map`` | Subclass of ``Dictionary`` but with static typing for its keys and values. |
199+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
200+
| |pair| | ``std::pair`` | Stores a single key-value pair. |
201+
+-----------------------+--------------------------+---------------------------------------------------------------------------------------+
202+
203+
.. |string| replace:: `String <https://github.com/godotengine/godot/blob/master/core/string/ustring.h>`__
204+
.. |vector| replace:: `Vector <https://github.com/godotengine/godot/blob/master/core/templates/vector.h>`__
205+
.. |hash_set| replace:: `HashSet <https://github.com/godotengine/godot/blob/master/core/templates/hash_set.h>`__
206+
.. |hash_map| replace:: `HashMap <https://github.com/godotengine/godot/blob/master/core/templates/hash_map.h>`__
207+
.. |string_name| replace:: `StringName <https://github.com/godotengine/godot/blob/master/core/string/string_name.h>`__
208+
.. |local_vector| replace:: `LocalVector <https://github.com/godotengine/godot/blob/master/core/templates/local_vector.h>`__
209+
.. |array| replace:: `Array <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
210+
.. |typed_array| replace:: `TypedArray <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
211+
.. |packed_array| replace:: `Packed*Array <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
212+
.. |list| replace:: `List <https://github.com/godotengine/godot/blob/master/core/templates/list.h>`__
213+
.. |fixed_vector| replace:: `FixedVector <https://github.com/godotengine/godot/blob/master/core/templates/fixed_vector.h>`__
214+
.. |span| replace:: `Span <https://github.com/godotengine/godot/blob/master/core/templates/span.h>`__
215+
.. |rb_set| replace:: `RBSet <https://github.com/godotengine/godot/blob/master/core/templates/rb_set.h>`__
216+
.. |v_set| replace:: `VSet <https://github.com/godotengine/godot/blob/master/core/templates/vset.h>`__
217+
.. |a_hash_map| replace:: `AHashMap <https://github.com/godotengine/godot/blob/master/core/templates/a_hash_map.h>`__
218+
.. |rb_map| replace:: `RBMap <https://github.com/godotengine/godot/blob/master/core/templates/rb_map.h>`__
219+
.. |dictionary| replace:: `Dictionary <https://github.com/godotengine/godot/blob/master/core/variant/dictionary.h>`__
220+
.. |typed_dictionary| replace:: `TypedDictionary <https://github.com/godotengine/godot/blob/master/core/variant/dictionary.h>`__
221+
.. |pair| replace:: `Pair <https://github.com/godotengine/godot/blob/master/core/templates/pair.h>`__
200222

201223
Math types
202224
----------
203225

204-
There are several linear math types available in the core/math
205-
directory.
206-
207-
References:
208-
~~~~~~~~~~~
226+
There are several linear math types available in the ``core/math``
227+
directory:
209228

210229
- `core/math <https://github.com/godotengine/godot/tree/master/core/math>`__
211230

212231
NodePath
213232
--------
214233

215234
This is a special datatype used for storing paths in a scene tree and
216-
referencing them fast.
217-
218-
References:
219-
~~~~~~~~~~~
235+
referencing them in an optimized manner:
220236

221237
- `core/string/node_path.h <https://github.com/godotengine/godot/blob/master/core/string/node_path.h>`__
222238

223239
RID
224240
---
225241

226-
RIDs are resource IDs. Servers use these to reference data stored in
242+
RIDs are *Resource IDs*. Servers use these to reference data stored in
227243
them. RIDs are opaque, meaning that the data they reference can't be
228244
accessed directly. RIDs are unique, even for different types of
229-
referenced data.
230-
231-
References:
232-
~~~~~~~~~~~
245+
referenced data:
233246

234247
- `core/templates/rid.h <https://github.com/godotengine/godot/blob/master/core/templates/rid.h>`__

0 commit comments

Comments
 (0)