summaryrefslogtreecommitdiffstats
path: root/xpcom/docs/collections.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /xpcom/docs/collections.rst
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'xpcom/docs/collections.rst')
-rw-r--r--xpcom/docs/collections.rst114
1 files changed, 114 insertions, 0 deletions
diff --git a/xpcom/docs/collections.rst b/xpcom/docs/collections.rst
new file mode 100644
index 0000000000..8c9356e499
--- /dev/null
+++ b/xpcom/docs/collections.rst
@@ -0,0 +1,114 @@
+XPCOM Collections
+=================
+
+``nsTArray`` and ``AutoTArray``
+-------------------------------
+
+``nsTArray<T>`` is a typesafe array for holding various objects, similar to ``std::vector<T>``. (note that
+``nsTArray<T>`` is dynamically-sized, unlike ``std::array<T>``) Here's an
+incomplete list of mappings between the two:
+
+================== ==================================================
+std::vector<T> nsTArray<T>
+================== ==================================================
+``size()`` ``Length()``
+``empty()`` ``IsEmpty()``
+``resize()`` ``SetLength()`` or ``SetLengthAndRetainStorage()``
+``capacity()`` ``Capacity()``
+``reserve()`` ``SetCapacity()``
+``push_back()`` ``AppendElement()``
+``insert()`` ``AppendElements()``
+``emplace_back()`` ``EmplaceBack()``
+``clear()`` ``Clear()`` or ``ClearAndRetainStorage()``
+``data()`` ``Elements()``
+``at()`` ``ElementAt()``
+``back()`` ``LastElement()``
+================== ==================================================
+
+Rust Bindings
+~~~~~~~~~~~~~
+
+When the ``thin_vec`` crate is built in Gecko, ``thin_vec::ThinVec<T>`` is
+guaranteed to have the same memory layout and allocation strategy as
+``nsTArray``, meaning that the two types may be used interchangeably across
+FFI boundaries. The type is **not** safe to pass by-value over FFI
+boundaries, due to Rust and C++ differing in when they run destructors.
+
+The element type ``T`` must be memory-compatible with both Rust and C++ code
+to use over FFI.
+
+``nsTHashMap`` and ``nsTHashSet``
+---------------------------------
+
+These types are the recommended interface for writing new XPCOM hashmaps and
+hashsets in XPCOM code.
+
+Supported Hash Keys
+~~~~~~~~~~~~~~~~~~~
+
+The following types are supported as the key parameter to ``nsTHashMap`` and
+``nsTHashSet``.
+
+========================== ======================
+Type Hash Key
+========================== ======================
+``T*`` ``nsPtrHashKey<T>``
+``T*`` ``nsPtrHashKey<T>``
+``nsCString`` ``nsCStringHashKey``
+``nsString`` ``nsStringHashKey``
+``uint32_t`` ``nsUint32HashKey``
+``uint64_t`` ``nsUint64HashKey``
+``intptr_t`` ``IntPtrHashKey``
+``nsCOMPtr<nsISupports>`` ``nsISupportsHashKey``
+``RefPtr<T>`` ``nsRefPtrHashKey<T>``
+``nsID`` ``nsIDHashKey``
+========================== ======================
+
+Any key not in this list must inherit from the ``PLDHashEntryHdr`` class to
+implement manual hashing behaviour.
+
+Class Reference
+~~~~~~~~~~~~~~~
+
+.. note::
+
+ The ``nsTHashMap`` and ``nsTHashSet`` types are not declared exactly like
+ this in code. This is intended largely as a practical reference.
+
+.. cpp:class:: template<K, V> nsTHashMap<K, V>
+
+ The ``nsTHashMap<K, V>`` class is currently defined as a thin type alias
+ around ``nsBaseHashtable``. See the methods defined on that class for
+ more detailed documentation.
+
+ https://searchfox.org/mozilla-central/source/xpcom/ds/nsBaseHashtable.h
+
+ .. cpp:function:: uint32_t Count() const
+
+ .. cpp:function:: bool IsEmpty() const
+
+ .. cpp:function:: bool Get(KeyType aKey, V* aData) const
+
+ Get the value, returning a flag indicating the presence of the entry
+ in the table.
+
+ .. cpp:function:: V Get(KeyType aKey) const
+
+ Get the value, returning a default-initialized object if the entry is
+ not present in the table.
+
+ .. cpp:function:: Maybe<V> MaybeGet(KeyType aKey) const
+
+ Get the value, returning Nothing if the entry is not present in the table.
+
+ .. cpp:function:: V& LookupOrInsert(KeyType aKey, Args&&... aArgs) const
+
+ .. cpp:function:: V& LookupOrInsertWith(KeyType aKey, F&& aFunc) const
+
+.. cpp:class:: template<K> nsTHashSet<K>
+
+ The ``nsTHashSet<K>`` class is currently defined as a thin type alias
+ around ``nsTBaseHashSet``. See the methods defined on that class for
+ more detailed documentation.
+
+ https://searchfox.org/mozilla-central/source/xpcom/ds/nsTHashSet.h