Skip to content

# 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 array before iterator `pos`.
2. Inserts `cnt` copies of `val` into array before iterator `pos`.
3. Inserts elements from range `[first, last)` into array before iterator `pos`.
4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
5. Inserts elements from range `[first, last)` into object.

## 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)
  begin of the range of elements to insert
`last` (in)
  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 range of elements 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};

        // 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 initializer list 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 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 range of elements into 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.

Last update: May 1, 2022
Back to top