json/docs/mkdocs/docs/api/basic_json/emplace.md

nlohmann::basic_json::emplace

template<class... Args>
std::pair<iterator, bool> emplace(Args&& ... args);

Inserts a new element into a JSON object constructed in-place with the given args if there is no element with the key in the container. If the function is called on a JSON null value, an empty object is created before appending the value created from args.

Template parameters

Args

compatible types to create a basic_json object

Iterator invalidation

For ordered_json, adding a value to an object can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

Parameters

args (in)

arguments to forward to a constructor of basic_json

Return value

a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and a #!cpp bool denoting whether the insertion took place.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

Exceptions

Throws type_error.311 when called on a type other than JSON object or #!json null; example: "cannot use emplace() with number"

Complexity

Logarithmic in the size of the container, O(log(size())).

Examples

??? example

The example shows how `emplace()` can be used to add elements to a JSON object. Note how the `#!json null` value was
silently converted to a JSON object. Further note how no value is added if there was already one value stored with
the same key.
        
```cpp
--8<-- "examples/emplace.cpp"
```

Output:

```json
--8<-- "examples/emplace.output"
```

See also

• emplace_back add a value to an array
• insert add values to an array/object
• Modifying values - the article on modifying values

Version history

• Since version 2.0.8.