Skip to content

Add notes to Dictionary, HashMap and Array. #10914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 11, 2025
Merged

Add notes to Dictionary, HashMap and Array. #10914

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions about/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -579,6 +579,8 @@ general-purpose library, but we had special requirements for Godot.
* We use our custom String type, as the one provided by STL is too basic and lacks proper
internationalization support.

Check out :ref:`Godot's container types <doc_cpp_godot_types>` for alternatives.

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

Expand Down
6 changes: 5 additions & 1 deletion contributing/development/cpp_usage_guidelines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ variables and ``nullptr`` is encouraged when possible. Still, try to keep your
use of modern C++ features conservative. Their use needs to serve a real
purpose, such as improving code readability or performance.

.. _doc_cpp_godot_types:

Standard Template Library
~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -75,6 +77,7 @@ scripting API.
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``Array`` 📜 | ``std::vector`` | Values can be of any Variant type. No static typing is imposed. |
| | | Uses shared reference counting, similar to ``std::shared_ptr``. |
| | | Uses Vector<Variant> internally. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``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``. |
Expand All @@ -99,7 +102,7 @@ scripting API.
| | | This means it's generally slower but can be copied around almost for free. |
| | | The performance benefits of ``VSet`` aren't established, so prefer using other types. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``HashMap`` | ``std::unordered_map`` | **Use this as the "default" map type.** Does not preserve insertion order. |
| ``HashMap`` | ``std::unordered_map`` | **Use this as the "default" map type.** Preserves insertion order. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is std::unordered_map still the closest analogue? Or does std have a map type that preserves insertion order?

On a related note. I have very vague memories that the fact that HashMap preserves insertion order was an implementation detail and we didn't want that fact to be part of the contract with users.

I'll do a quick search on RC and see if I can find some discussion about it to refresh my memory

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't find anything conclusive, but it seems that we use HashMap in a lot of places that rely on preserving insertion order.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's also documented behavior:

Dictionaries will preserve the insertion order when adding new entries.

I think the window to change this has closed 😅

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only for exposed APIs, but yeah. I think considering that both JS and Python do also preserve insertion order on their dicts (with some caveats) and the low barrier we aim for with GDScript, this seems fine.

+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``AHashMap`` | ``std::unordered_map`` | Array-based implementation of a hash map. Does not preserve insertion order. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
Expand All @@ -114,6 +117,7 @@ scripting API.
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``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``. |
| | | Preserves insertion order. Uses ``HashMap<Variant>`` internally. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
| ``TypedDictionary`` 📜 | ``std::unordered_map`` | Subclass of ``Dictionary`` but with static typing for its keys and values. |
+------------------------+--------------------------+---------------------------------------------------------------------------------------+
Expand Down