1# basic_json::emplace 2 3```cpp 4template<class... Args> 5std::pair<iterator, bool> emplace(Args&& ... args); 6``` 7 8Inserts a new element into a JSON object constructed in-place with the given `args` if there is no element with the key 9in the container. If the function is called on a JSON null value, an empty object is created before appending the value 10created from `args`. 11 12## Template parameters 13 14`Args` 15: compatible types to create a `basic_json` object 16 17## Parameters 18 19`args` (in) 20: arguments to forward to a constructor of `basic_json` 21 22## Return value 23 24a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and 25a `#!cpp bool` denoting whether the insertion took place. 26 27## Exceptions 28 29Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON 30object or `#!json null`; example: `"cannot use emplace() with number"` 31 32## Complexity 33 34Logarithmic in the size of the container, O(log(`size()`)). 35 36## Examples 37 38??? example 39 40 The example shows how `emplace()` can be used to add elements to a JSON object. Note how the `#!json null` value was 41 silently converted to a JSON object. Further note how no value is added if there was already one value stored with 42 the same key. 43 44 ```cpp 45 --8<-- "examples/emplace.cpp" 46 ``` 47 48 Output: 49 50 ```json 51 --8<-- "examples/emplace.output" 52 ``` 53 54## Version history 55 56- Since version 2.0.8. 57