Sylvestre Ledru
3035033c92
Convert xpcom/docs/*.rst to MyST-flavored Markdown. Update stringguide.xpidl :ref: targets to the explicit (stringguide-xpidl)= MyST anchor. Differential Revision: https://phabricator.services.mozilla.com/D304220
109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
# 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`
|
|
```
|