diff options
Diffstat (limited to 'xpcom/docs/collections.rst')
| -rw-r--r-- | xpcom/docs/collections.rst | 114 |
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 |