carb::variant::VariantMap¶
Defined in carb/variant/VariantTypes.h
Inheritance Relationships¶
Base Type¶
public carb::IObject
(carb::IObject)
-
class
carb::variant
::
VariantMap
: public carb::IObject¶ An associative array (i.e.
“map”) of key/value Variant pairs that can itself be contained in a Variant.
Similar in many respects to
std::unordered_map
, but reference-counted and implemented within carb.variant.plugin.Created via IVariant::createMap().
Note
This is an unordered container, meaning that iterating over all values may not be in the same order as they were inserted. This is a unique container, meaning that inserting a key that already exists in the container will replace the previous key/value pair.
Public Types
-
using
value_type
= KeyValuePair¶ The value type.
-
using
size_type
= size_t¶ Unsigned integer type.
-
using
difference_type
= ptrdiff_t¶ Signed integer type.
-
using
reference
= value_type&¶ Reference type.
-
using
const_reference
= const value_type&¶ Const reference type.
-
using
pointer
= value_type*¶ Pointer type.
-
using
const_pointer
= const value_type*¶ Const pointer type.
Public Functions
-
const_iterator
cbegin
() const noexcept¶ Creates an iterator to the first element in the container.
-
const_iterator
begin
() const noexcept¶ Creates an iterator to the first element in the container.
-
iterator
begin
() noexcept¶ Creates an iterator to the first element in the container.
-
const_iterator
cend
() const noexcept¶ Creates an iterator to the past-the-end element in the container.
- Returns
a
const_iterator
to the past-the-end element in the container. This iterator is a placeholder; attempting to access it results in undefined behavior.
-
const_iterator
end
() const noexcept¶ Creates an iterator to the past-the-end element in the container.
- Returns
a
const_iterator
to the past-the-end element in the container. This iterator is a placeholder; attempting to access it results in undefined behavior.
-
iterator
end
() noexcept¶ Creates an iterator to the past-the-end element in the container.
- Returns
an
iterator
to the past-the-end element in the container. This iterator is a placeholder; attempting to access it results in undefined behavior.
-
bool
empty
() const noexcept¶ Checks if the container is empty.
- Returns
true
if the container is empty;false
otherwise.
-
virtual size_t
size
() const noexcept = 0¶ Returns the number of keys contained.
- Returns
the number of keys contained.
-
std::pair<iterator, bool>
insert
(const Variant &key, Variant value)¶ Attempts to insert a new element into the container.
If insertion is successful, all iterators, references and pointers are invalidated.
Warning
Variant comparison rules are taken in account. For instance, since Variant(bool) is considered equal with Variant(int) for false/0 and true/1, these values would conflict.
- Parameters
key – The key to insert into the map.
value – The value to associate with
key
. If the key already exists in the container, this value is not used.
- Returns
A
pair
consisting of aniterator
to the inserted element (or the existing element that prevented the insertion) and abool
that will betrue
if insertion took place orfalse
if insertion did not take place.
-
size_t
erase
(const Variant &key) noexcept¶ Erases a key from the map.
- Parameters
key – The key value to erase.
- Returns
The number of entries removed from the map. This will be
0
if the key was not found or1
if the key was found and removed.
-
iterator
erase
(const_iterator pos) noexcept¶ Removes the given element.
References, pointers and iterators to the erased element are invalidated. All other iterators, pointers and references remain valid.
- Parameters
pos – The
const_iterator
to the element to remove. This iterator must be valid and dereferenceable.- Returns
the iterator immediately following
pos
.
-
find_iterator
erase
(const_find_iterator pos) noexcept¶ Removes the given element.
References, pointers and iterators to the erased element are invalidated. All other iterators, pointers and references remain valid.
- Parameters
pos – The
const_find_iterator
to the element to remove. This iterator must be valid and dereferenceable.- Returns
the iterator immediately following
pos
.
-
find_iterator
find
(const Variant &key) noexcept¶ Finds the first element with the specified key.
Note
find_iterator
objects returned from this function will only iterate through elements with the same key; they cannot be used to iterate through the entire container.- Parameters
key – The key to search for.
- Returns
a
find_iterator
to the first element matchingkey
, or end() if no element was found matchingkey
.
-
const_find_iterator
find
(const Variant &key) const noexcept¶ Finds the first element with the specified key.
Note
const_find_iterator
objects returned from this function will only iterate through elements with the same key; they cannot be used to iterate through the entire container.- Parameters
key – The key to search for.
- Returns
a
const_find_iterator
to the first element matchingkey
, or end() if no element was found matchingkey
.
-
bool
contains
(const Variant &key) const noexcept¶ Checks whether the container has an element matching a given key.
- Parameters
key – The key of the element to search for.
- Returns
true
if at least one element matchingkey
exists in the container;false
otherwise.
-
size_t
count
(const Variant &key) const noexcept¶ Counts the number of elements matching a given key.
Note
as this is a unique container, this will always be either 0 or 1.
- Parameters
key – The key to count.
- Returns
the number of elements matching
key
.
-
mapped_type &
at
(const Variant &key)¶ Access specified element with bounds checking.
This function is only available if exceptions are enabled.
- Parameters
key – The key of the element to find.
- Throws
std::out_of_range – if no such element exists.
- Returns
a reference to the mapped value of the element with key equivalent to
key
.
-
const mapped_type &
at
(const Variant &key) const¶ Access specified element with bounds checking.
This function is only available if exceptions are enabled.
- Parameters
key – The key of the element to find.
- Throws
std::out_of_range – if no such element exists.
- Returns
a reference to the mapped value of the element with key equivalent to
key
.
-
mapped_type &
operator[]
(const Variant &key)¶ Returns a reference to a value that is mapped to the given key, performing an insertion if such key does not already exist.
If
key
does not exist, the returned type will be a default-constructed Variant.- Parameters
key – the key of the element to find or insert
- Returns
a reference to the mapped_type mapped to
key
.
-
virtual void
clear
() noexcept = 0¶ Clears the contents.
O(n) over capacity().
Erases all elements from the container. After this call size() returns zero. Invalidates all iterators, pointers and references to contained elements.
Note
This does not free the memory used by the container. To free the hash table memory, use
rehash(0)
after this call.
-
virtual size_t
capacity
() const noexcept = 0¶ Returns the number of elements that can be stored with the current memory usage.
- See
- Returns
the number of elements that can be stored with the current memory usage.
-
virtual void
reserve
(size_t n) noexcept = 0¶ Reserves space for at least the specified number of elements and regenerates the hash table.
Sets capacity() of
*this
to a value greater-than-or-equal-ton
. If capacity() already exceedsn
, nothing happens.If a rehash occurs, all iterators, pointers and references to existing elements are invalidated.
- Parameters
n – The desired minimum capacity of
*this
.
-
virtual void
rehash
(size_t n) noexcept = 0¶ Sets the capacity of the container to the lowest valid value greater-than-or-equal-to the given value, and rehashes the container.
If
n
is less-than size(), size() is used instead.If the container is empty and
n
is zero, the memory for the container is freed.After this function is called, all iterators, pointers and references to existing elements are invalidated.
- Parameters
n – The minimum capacity for the container. The actual size of the container may be larger than this.
-
virtual size_t
addRef
() = 0¶ Atomically add one to the reference count.
- Returns
The current reference count after one was added, though this value may change before read if other threads are also modifying the reference count. The return value is guaranteed to be non-zero.
-
virtual size_t
release
() = 0¶ Atomically subtracts one from the reference count.
If the result is zero, carb::deleteHandler() is called for
this
.- Returns
The current reference count after one was subtracted. If zero is returned, carb::deleteHandler() was called for
this
.
Public Static Functions
-
static inline carb::InterfaceDesc
getInterfaceDesc
()¶ Returns information about this interface. Auto-generated by CARB_PLUGIN_INTERFACE(). *
- Returns
The carb::InterfaceDesc struct with information about this interface.
-
using