Skip to content


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

compatible types to create a basic_json object


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 bool denoting whether the insertion took place.


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


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



The example shows how emplace() can be used to add elements to a JSON object. Note how the 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.

#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
    // create JSON values
    json object = {{"one", 1}, {"two", 2}};
    json null;

    // print values
    std::cout << object << '\n';
    std::cout << null << '\n';

    // add values
    auto res1 = object.emplace("three", 3);
    null.emplace("A", "a");
    null.emplace("B", "b");

    // the following call will not add an object, because there is already
    // a value stored at key "B"
    auto res2 = null.emplace("B", "c");

    // print values
    std::cout << object << '\n';
    std::cout << *res1.first << " " << std::boolalpha << res1.second << '\n';

    std::cout << null << '\n';
    std::cout << *res2.first << " " << std::boolalpha << res2.second << '\n';


3 true
"b" false

Version history

  • Since version 2.0.8.