object::emplace

## `object::emplace`

Construct an element in-place.

### Synopsis

    template<
        class Arg>
    std::pair< object::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.

If the insertion occurs and results in a rehashing of the container, all iterators and references are invalidated. Otherwise, they are not affected. Rehashing occurs only if the new number of elements is greater than `capacity()`.

### Complexity

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` otherwise.

### 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
--- | ---
`boost::system::system_error` | The size of the key would exceed `string::max_size`.

Edit this page