Add a table listing STL datatypes and their Godot equivalents in C++ usage guidelines

contributing/development/cpp_usage_guidelines.rst

@@ -53,18 +53,61 @@ as Godot provides its own data types (among other things).
 See :ref:`doc_faq_why_not_stl` for more information.
 
 This means that pull requests should **not** use ``std::string``,
-``std::vector`` and the like. Instead, use Godot's datatypes as described below:
-
-- Use ``String`` instead of ``std::string``.
-- Use ``Vector`` instead of ``std::vector``. In some cases, ``LocalVector``
-  can be used as an alternative (ask core developers first).
-- Use ``Array`` instead of ``std::array``.
-
-.. note::
-
-    Godot also has a List datatype (which is a linked list). While List is already used
-    in the codebase, it typically performs worse than other datatypes like Vector
-    and Array. Therefore, List should be avoided in new code unless necessary.
+``std::vector`` and the like. Instead, use Godot's datatypes as described below.
+A 📜 icon denotes the type is part of :ref:`Variant <doc_variant_class>`. This
+means it can be used as a parameter or return value of a method exposed to the
+scripting API.
+
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| Godot datatype         | Closest C++ STL datatype | Comment                                                                              |
++========================+==========================+======================================================================================+
+| ``String`` 📜          | ``std::string``          | **Use this as the "default" string type.** ``String`` uses UTF-32 encoding           |
+|                        |                          | to improve performance thanks to its fixed character size.                           |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``StringName`` 📜      | ``std::string``          | Uses string interning for fast comparisons. Use this for static strings that are     |
+|                        |                          | referenced frequently and used in multiple locations in the engine.                  |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``Vector``             | ``std::vector``          | **Use this as the "default" vector type.** Uses copy-on-write (COW) semantics.       |
+|                        |                          | This means it's generally slower but can be copied around almost for free.           |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``LocalVector``        | ``std::vector``          | Closer to ``std::vector`` in semantics. In most situations, ``Vector`` should be     |
+|                        |                          | preferred.                                                                           |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``Array`` 📜           | ``std::vector``          | Values can be of any Variant type. No static typing is imposed.                      |
+|                        |                          | Uses shared reference counting, similar to ``std::shared_ptr``.                      |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``TypedArray`` 📜      | ``std::vector``          | Subclass of ``Array`` but with static typing for its elements.                       |
+|                        |                          | Not to be confused with ``Packed*Array``, which is internally a ``Vector``.          |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``Packed*Array`` 📜    | ``std::vector``          | Alias of ``Vector``, e.g. ``PackedColorArray = Vector<Color>``.                      |
+|                        |                          | Only a limited list of packed array types are available                              |
+|                        |                          | (use ``TypedArray`` otherwise).                                                      |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``List``               | ``std::list``            | Linked list type. Generally slower than other array/vector types. Prefer using       |
+|                        |                          | other types in new code, unless using ``List`` avoids the need for type conversions. |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``Span``               | ``std::span``            | Represents read-only access to a contiguous array without needing to copy any data.  |
+|                        |                          | See `pull request description <https://github.com/godotengine/godot/pull/100293>`__  |
+|                        |                          | for details.                                                                         |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``HashSet``            | ``std::unordered_set``   | **Use this as the "default" set type.**                                              |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``RBSet``              | ``std::unordered_set``   | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__             |
+|                        |                          | for faster access.                                                                   |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``HashMap``            | ``std::unordered_map``   | **Use this as the "default" map type.** Does not preserve insertion order.           |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``AHashMap``           | ``std::unordered_map``   | Array-based implementation of a hash map. Does not preserve insertion order.         |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``OAHashMap``          | ``std::unordered_map``   | Does not preserve insertion order.                                                   |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``Dictionary`` 📜      | ``std::unordered_map``   | Keys and values can be of any Variant type. No static typing is imposed.             |
+|                        |                          | Uses shared reference counting, similar to ``std::shared_ptr``.                      |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``TypedDictionary`` 📜 | ``std::unordered_map``   | Subclass of ``Dictionary`` but with static typing for its keys and values.          |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
+| ``Pair``               | ``std::pair``            | Stores a single key-value pair.                                                      |
++------------------------+--------------------------+--------------------------------------------------------------------------------------+
 
 ``auto`` keyword
 ~~~~~~~~~~~~~~~~