carb::variant::VariantMap

class 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 key_type = Variant : The key type.

using mapped_type = Variant : The mapped value type.

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.

Returns: a const_iterator to the first element in the container. If the container is empty() the iterator will be equal to cend().

const_iterator begin() const noexcept

Creates an iterator to the first element in the container.

Returns: a const_iterator to the first element in the container. If the container is empty() the iterator will be equal to end().

iterator begin() noexcept

Creates an iterator to the first element in the container.

Returns: an iterator to the first element in the container. If the container is empty() the iterator will be equal to end().

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 an iterator to the inserted element (or the existing element that prevented the insertion) and a bool that will be true if insertion took place or false 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 or 1 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 matching key, or end() if no element was found matching key.

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 matching key, or end() if no element was found matching key.

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 matching key 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.