.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 =========================== Concurrently safe modifiers =========================== All member functions in this section can be performed concurrently with each other, lookup methods and while traversing the container. Emplacing elements ------------------ .. code:: cpp template std::pair emplace( Args&&... args ); Attempts to insert an element constructed in-place from ``args`` into the container. **Returns**: ``std::pair`` where ``iterator`` points to the inserted element or to an existing element with equal key. Boolean value is ``true`` if insertion took place; ``false``, otherwise. **Requirements**: the type ``value_type`` must meet the ``EmplaceConstructible`` requirements from the [container.requirements] ISO C++ Standard section. --------------------------------------------------------------------------------------------- .. code:: cpp template iterator emplace_hint( const_iterator hint, Args&&... args ); Attempts to insert an element constructed in-place from ``args`` into the container. Optionally uses the parameter ``hint`` as a suggestion to where the node should be placed. **Returns**: an ``iterator`` to the inserted element or to an existing element with equal key. **Requirements**: the type ``value_type`` must meet the ``EmplaceConstructible`` requirements from the [container.requirements] ISO C++ Standard section. Inserting values ---------------- .. code:: cpp std::pair insert( const value_type& value ); Attempts to insert ``value`` into the container. **Returns**: ``std::pair``, where ``iterator`` points to the inserted element or to an existing element with equal key. Boolean value is ``true`` if insertion took place; ``false``, otherwise. **Requirements**: the type ``value_type`` must meet the ``CopyInsertable`` requirements from the [container.requirements] ISO C++ Standard section. --------------------------------------------------------------------------------------------- .. code:: cpp iterator insert( const_iterator hint, const value_type& value ); Attempts to insert ``value`` into the container. Optionally uses the parameter ``hint`` as a suggestion to where the element should be placed. **Returns**: an ``iterator`` to the inserted element or to an existing element with equal key. **Requirements**: the type ``value_type`` must meet the ``CopyInsertable`` requirements from the [container.requirements] ISO C++ Standard section. --------------------------------------------------------------------------------------------- .. code:: cpp template std::pair insert( P&& value ); Equivalent to ``emplace(std::forward

(value))``. This overload only participates in overload resolution if ``std::is_constructible::value`` is ``true``. --------------------------------------------------------------------------------------------- .. code:: cpp template iterator insert( const_iterator hint, P&& value ); Equivalent to ``emplace_hint(hint, std::forward

(value))``. This overload only participates in overload resolution if ``std::is_constructible::value`` is ``true``. --------------------------------------------------------------------------------------------- .. code:: cpp std::pair insert( value_type&& value ); Attempts to insert ``value`` into the container using move semantics. ``value`` is left in a valid, but unspecified state. **Returns**: ``std::pair``, where ``iterator`` points to the inserted element or to an existing element with equal key. Boolean value is ``true`` if insertion took place; ``false``, otherwise. **Requirements**: the type ``value_type`` must meet the ``MoveInsertable`` requirements from the [container.requirements] ISO C++ Standard section. --------------------------------------------------------------------------------------------- .. code:: cpp iterator insert( const_iterator hint, value_type&& other ); Attempts to insert ``value`` into the container using move semantics. Optionally uses the parameter ``hint`` as a suggestion to where the element should be placed. ``value`` is left in a valid, but unspecified state. **Returns**: an ``iterator`` to the inserted element or to an existing element with equal key. **Requirements**: the type ``value_type`` must meet the ``MoveInsertable`` requirements from the [container.requirements] ISO C++ Standard section. Inserting sequences of elements ------------------------------- .. code:: cpp template void insert( InputIterator first, InputIterator last ); Attempts to insert all items from the half-open interval ``[first, last)`` into the container. If the interval ``[first, last)`` contains multiple elements with equal keys, it is unspecified which element should be inserted. **Requirements**: the type ``InputIterator`` must meet the requirements of `InputIterator` from the ``[input.iterators]`` ISO C++ Standard section. --------------------------------------------------------------------------------------------- .. code:: cpp void insert( std::initializer_list init ); Equivalent to ``insert(init.begin(), init.end())``. Inserting nodes --------------- .. code:: cpp std::pair insert( node_type&& nh ); If the node handle ``nh`` is empty, does nothing. Otherwise, attempts to insert the node owned by ``nh`` into the container. If the insertion fails, node handle ``nh`` keeps ownership of the node. Otherwise, ``nh`` is left in an empty state. No copy or move constructors of ``value_type`` are performed. The behavior is undefined if ``nh`` is not empty and ``get_allocator() != nh.get_allocator()``. **Returns**: ``std::pair``, where ``iterator`` points to the inserted element or to an existing element with key equal to ``nh.key()``. Boolean value is ``true`` if insertion took place; ``false``, otherwise. --------------------------------------------------------------------------------------------- .. code:: cpp iterator insert( const_iterator hint, node_type&& nh ); If the node handle ``nh`` is empty, does nothing. Otherwise, attempts to insert the node owned by ``nh`` into the container. Optionally uses the parameter ``hint`` as a suggestion to where the node should be placed. If the insertion fails, node handle ``nh`` keeps ownership of the node. Otherwise, ``nh`` is left in an empty state. No copy or move constructors of ``value_type`` are performed. The behavior is undefined if ``nh`` is not empty and ``get_allocator() != nh.get_allocator()``. **Returns**: an iterator pointing to the inserted element or to an existing element with key equal to ``nh.key()``. **Merging containers** .. code:: cpp template void merge( concurrent_unordered_map& source ); template void merge( concurrent_unordered_map&& source ); template void merge( concurrent_unordered_multimap& source ); template void merge( concurrent_unordered_multimap&& source ); Transfers those elements from ``source`` which keys do not exist in the container. In case of merging with the container with multiple elements with equal keys, it is unspecified which element would be transferred. No copy or move constructors of ``value_type`` are performed. The behavior is undefined if ``get_allocator() != source.get_allocator()``.