nlohmann::basic_json::insert

// (1)
iterator insert(const_iterator pos, const basic_json& val);
iterator insert(const_iterator pos, basic_json&& val);

// (2)
iterator insert(const_iterator pos, size_type cnt, const basic_json& val);

// (3)
iterator insert(const_iterator pos, const_iterator first, const_iterator last);

// (4)
iterator insert(const_iterator pos, initializer_list_t ilist);

// (5)
void insert(const_iterator first, const_iterator last);

1. Inserts element val into an array before iterator pos.
2. Inserts cnt copies of val into an array before iterator pos.
3. Inserts elements from range [first, last) into an array before iterator pos.
4. Inserts elements from initializer list ilist into an array before iterator pos.
5. Inserts elements from range [first, last) into an object.

Iterator invalidation

For all cases where an element is added to an array, a reallocation can happen, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise, only the end() iterator is invalidated. Also, any iterator or reference after the insertion point will point to the same index, which is now a different value.

For ordered_json, also adding an element to an object can yield a reallocation which again invalidates all iterators and all references. Also, any iterator or reference after the insertion point will point to the same index, which is now a different value.

Parameters

pos (in)

iterator before which the content will be inserted; may be the end() iterator

val (in)

value to insert

cnt (in)

number of copies of val to insert

first (in)

the start of the range of elements to insert

last (in)

the end of the range of elements to insert

ilist (in)

initializer list to insert the values from

Return value

1. iterator pointing to the inserted val.
2. iterator pointing to the first element inserted, or pos if cnt==0
3. iterator pointing to the first element inserted, or pos if first==last
4. iterator pointing to the first element inserted, or pos if ilist is empty
5. (none)

Exception safety

Strong exception safety: if an exception occurs, the original value stays intact.

Exceptions

1. The function can throw the following exceptions:
   • Throws type_error.309 if called on JSON values other than arrays; example: "cannot use insert() with string"
   • Throws invalid_iterator.202 if called on an iterator which does not belong to the current JSON value; example: "iterator does not fit current value"
2. The function can throw the following exceptions:
   • Throws type_error.309 if called on JSON values other than arrays; example: "cannot use insert() with string"
   • Throws invalid_iterator.202 if called on an iterator which does not belong to the current JSON value; example: "iterator does not fit current value"
3. The function can throw the following exceptions:
   • Throws type_error.309 if called on JSON values other than arrays; example: "cannot use insert() with string"
   • Throws invalid_iterator.202 if called on an iterator which does not belong to the current JSON value; example: "iterator does not fit current value"
   • Throws invalid_iterator.210 if first and last do not belong to the same JSON value; example: "iterators do not fit"
   • Throws invalid_iterator.211 if first or last are iterators into container for which insert is called; example: "passed iterators may not belong to container"
4. The function can throw the following exceptions:
   • Throws type_error.309 if called on JSON values other than arrays; example: "cannot use insert() with string"
   • Throws invalid_iterator.202 if called on an iterator which does not belong to the current JSON value; example: "iterator does not fit current value"
5. The function can throw the following exceptions:
   • Throws type_error.309 if called on JSON values other than objects; example: "cannot use insert() with string"
   • Throws invalid_iterator.202 if called on an iterator which does not belong to the current JSON value; example: "iterator does not fit current value"
   • Throws invalid_iterator.210 if first and last do not belong to the same JSON value; example: "iterators do not fit"

Complexity

1. Constant plus linear in the distance between pos and end of the container.
2. Linear in cnt plus linear in the distance between pos and end of the container.
3. Linear in std::distance(first, last) plus linear in the distance between pos and end of the container.
4. Linear in ilist.size() plus linear in the distance between pos and end of the container.
5. Logarithmic: O(N*log(size() + N)), where N is the number of elements to insert.

Examples

Example (1): insert element into array

The example shows how insert() is used.

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

using json = nlohmann::json;

int main()
{
    // create a JSON array
    json v = {1, 2, 3, 4};

    // insert number 10 before number 3
    auto new_pos = v.insert(v.begin() + 2, 10);

    // output new array and result of insert call
    std::cout << *new_pos << '\n';
    std::cout << v << '\n';
}

Output:

10
[1,2,10,3,4]

Example (2): insert copies of element into array

The example shows how insert() is used.

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

using json = nlohmann::json;

int main()
{
    // create a JSON array
    json v = {1, 2, 3, 4};

    // insert number 7 copies of number 7 before number 3
    auto new_pos = v.insert(v.begin() + 2, 7, 7);

    // output new array and result of insert call
    std::cout << *new_pos << '\n';
    std::cout << v << '\n';
}

Output:

7
[1,2,7,7,7,7,7,7,7,3,4]

Example (3): insert a range of elements into an array

The example shows how insert() is used.

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

using json = nlohmann::json;

int main()
{
    // create a JSON array
    json v = {1, 2, 3, 4};

    // create a JSON array to copy values from
    json v2 = {"one", "two", "three", "four"};

    // insert range from v2 before the end of array v
    auto new_pos = v.insert(v.end(), v2.begin(), v2.end());

    // output new array and result of insert call
    std::cout << *new_pos << '\n';
    std::cout << v << '\n';
}

Output:

"one"
[1,2,3,4,"one","two","three","four"]

Example (4): insert elements from an initializer list into an array

The example shows how insert() is used.

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

using json = nlohmann::json;

int main()
{
    // create a JSON array
    json v = {1, 2, 3, 4};

    // insert range from v2 before the end of array v
    auto new_pos = v.insert(v.end(), {7, 8, 9});

    // output new array and result of insert call
    std::cout << *new_pos << '\n';
    std::cout << v << '\n';
}

Output:

7
[1,2,3,4,7,8,9]

Example (5): insert a range of elements into an object

The example shows how insert() is used.

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

using json = nlohmann::json;

int main()
{
    // create two JSON objects
    json j1 = {{"one", "eins"}, {"two", "zwei"}};
    json j2 = {{"eleven", "elf"}, {"seventeen", "siebzehn"}};

    // output objects
    std::cout << j1 << '\n';
    std::cout << j2 << '\n';

    // insert range from j2 to j1
    j1.insert(j2.begin(), j2.end());

    // output result of insert call
    std::cout << j1 << '\n';
}

Output:

{"one":"eins","two":"zwei"}
{"eleven":"elf","seventeen":"siebzehn"}
{"eleven":"elf","one":"eins","seventeen":"siebzehn","two":"zwei"}

Version history

1. Added in version 1.0.0.
2. Added in version 1.0.0.
3. Added in version 1.0.0.
4. Added in version 1.0.0.
5. Added in version 3.0.0.