Source code
Revision control
Copy as Markdown
Other Tools
# 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.
:::
```{eval-rst}
.. 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.
:searchfox:`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
```
```{eval-rst}
.. 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.
:searchfox:`xpcom/ds/nsTHashSet.h`
```