Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext
object::emplace

Construct an element in-place.

Synopsis
template<
    class Arg>
std::pair< iterator, bool >
emplace(
    string_view key,
    Arg&& arg);
Description

Inserts a new element into the container constructed in-place with the given argument if there is no element with the key in the container. The element is inserted after all the existing elements. If the insertion occurs and results in a rehashing of the container, all iterators are invalidated. Otherwise, iterators are not affected. References are not invalidated. Rehashing occurs only if the new number of elements is greater than capacity().

Complexity

Amortized constant on average, worst case linear in size().

Exception Safety

Strong guarantee. Calls to memory_resource::allocate may throw.

Return Value

A std::pair where first is an iterator to the existing or inserted element, and second is true if the insertion took place or false if the assignment took place.

Parameters

Name

Description

key

The key used for lookup and insertion

arg

The argument used to construct the value. This will be passed as std::forward<Arg>(arg) to the value constructor.

Exceptions

Type

Thrown On

std::length_error

if key is too long


PrevUpHomeNext