xpcom/docs/collections.rst

   1 XPCOM Collections
   2 =================
   3
   4 ``nsTArray`` and ``AutoTArray``
   5 -------------------------------
   6
   7 ``nsTArray<T>`` is a typesafe array for holding various objects, similar to ``std::vector<T>``. (note that
   8 ``nsTArray<T>`` is dynamically-sized, unlike ``std::array<T>``) Here's an
   9 incomplete list of mappings between the two:
  10
  11 ================== ==================================================
  12 std::vector<T>     nsTArray<T>
  13 ================== ==================================================
  14 ``size()``         ``Length()``
  15 ``empty()``        ``IsEmpty()``
  16 ``resize()``       ``SetLength()`` or ``SetLengthAndRetainStorage()``
  17 ``capacity()``     ``Capacity()``
  18 ``reserve()``      ``SetCapacity()``
  19 ``push_back()``    ``AppendElement()``
  20 ``insert()``       ``AppendElements()``
  21 ``emplace_back()`` ``EmplaceBack()``
  22 ``clear()``        ``Clear()`` or ``ClearAndRetainStorage()``
  23 ``data()``         ``Elements()``
  24 ``at()``           ``ElementAt()``
  25 ``back()``         ``LastElement()``
  26 ================== ==================================================
  27
  28 Rust Bindings
  29 ~~~~~~~~~~~~~
  30
  31 When the ``thin_vec`` crate is built in Gecko, ``thin_vec::ThinVec<T>`` is
  32 guaranteed to have the same memory layout and allocation strategy as
  33 ``nsTArray``, meaning that the two types may be used interchangeably across
  34 FFI boundaries. The type is **not** safe to pass by-value over FFI
  35 boundaries, due to Rust and C++ differing in when they run destructors.
  36
  37 The element type ``T`` must be memory-compatible with both Rust and C++ code
  38 to use over FFI.
  39
  40 ``nsTHashMap`` and ``nsTHashSet``
  41 ---------------------------------
  42
  43 These types are the recommended interface for writing new XPCOM hashmaps and
  44 hashsets in XPCOM code.
  45
  46 Supported Hash Keys
  47 ~~~~~~~~~~~~~~~~~~~
  48
  49 The following types are supported as the key parameter to ``nsTHashMap`` and
  50 ``nsTHashSet``.
  51
  52 ========================== ======================
  53 Type                       Hash Key
  54 ========================== ======================
  55 ``T*``                     ``nsPtrHashKey<T>``
  56 ``T*``                     ``nsPtrHashKey<T>``
  57 ``nsCString``              ``nsCStringHashKey``
  58 ``nsString``               ``nsStringHashKey``
  59 ``uint32_t``               ``nsUint32HashKey``
  60 ``uint64_t``               ``nsUint64HashKey``
  61 ``intptr_t``               ``IntPtrHashKey``
  62 ``nsCOMPtr<nsISupports>``  ``nsISupportsHashKey``
  63 ``RefPtr<T>``              ``nsRefPtrHashKey<T>``
  64 ``nsID``                   ``nsIDHashKey``
  65 ========================== ======================
  66
  67 Any key not in this list must inherit from the ``PLDHashEntryHdr`` class to
  68 implement manual hashing behaviour.
  69
  70 Class Reference
  71 ~~~~~~~~~~~~~~~
  72
  73 .. note::
  74
  75     The ``nsTHashMap`` and ``nsTHashSet`` types are not declared exactly like
  76     this in code. This is intended largely as a practical reference.
  77
  78 .. cpp:class:: template<K, V> nsTHashMap<K, V>
  79
  80     The ``nsTHashMap<K, V>`` class is currently defined as a thin type alias
  81     around ``nsBaseHashtable``. See the methods defined on that class for
  82     more detailed documentation.
  83
  84     https://searchfox.org/mozilla-central/source/xpcom/ds/nsBaseHashtable.h
  85
  86     .. cpp:function:: uint32_t Count() const
  87
  88     .. cpp:function:: bool IsEmpty() const
  89
  90     .. cpp:function:: bool Get(KeyType aKey, V* aData) const
  91
  92         Get the value, returning a flag indicating the presence of the entry
  93         in the table.
  94
  95     .. cpp:function:: V Get(KeyType aKey) const
  96
  97         Get the value, returning a default-initialized object if the entry is
  98         not present in the table.
  99
 100     .. cpp:function:: Maybe<V> MaybeGet(KeyType aKey) const
 101
 102         Get the value, returning Nothing if the entry is not present in the table.
 103
 104     .. cpp:function:: V& LookupOrInsert(KeyType aKey, Args&&... aArgs) const
 105
 106     .. cpp:function:: V& LookupOrInsertWith(KeyType aKey, F&& aFunc) const
 107
 108 .. cpp:class:: template<K> nsTHashSet<K>
 109
 110     The ``nsTHashSet<K>`` class is currently defined as a thin type alias
 111     around ``nsTBaseHashSet``. See the methods defined on that class for
 112     more detailed documentation.
 113
 114     https://searchfox.org/mozilla-central/source/xpcom/ds/nsTHashSet.h