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

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 #!cpp cnt==0
3. iterator pointing to the first element inserted, or pos if #!cpp first==last
4. iterator pointing to the first element inserted, or pos if ilist is empty
5. (none)

Exception safety

Overload (1) gives the strong guarantee: if an exception is thrown, there are no changes in the JSON value.

Overloads (2) to (5) give the basic guarantee: if an exception is thrown while the elements or members are copied (for example, std::bad_alloc), the JSON value may be partially modified, but it stays a valid array or object.

The exceptions listed below are thrown before the JSON value is changed.

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"
   • Throws invalid_iterator.202 if first or last do not point to an array; example: "iterators first and last must point to arrays"
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 first or last do not point to an object; example: "iterators first and last must point to objects"
   • 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 #!cpp 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. O(N*log(size() + N)), where N is the number of elements to insert.

Examples

??? example "Example: (1) insert element into array"

The example shows how `insert()` is used.

```cpp
--8<-- "examples/insert.cpp"
```

Output:

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

??? example "Example: (2) insert copies of element into array"

The example shows how `insert()` is used.

```cpp
--8<-- "examples/insert__count.cpp"
```

Output:

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

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

The example shows how `insert()` is used.

```cpp
--8<-- "examples/insert__range.cpp"
```

Output:

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

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

The example shows how `insert()` is used.

```cpp
--8<-- "examples/insert__ilist.cpp"
```

Output:

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

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

The example shows how `insert()` is used.

```cpp
--8<-- "examples/insert__range_object.cpp"
```

Output:

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

See also

• emplace - add a value to an object
• emplace_back - add a value to an array
• push_back - add a value to an array/object
• update - merges objects
• Modifying values - the article on modifying values

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. Fixed in version 3.13.0 to copy the values before inserting; before, an ilist that referred to elements of the array being inserted into could insert wrong values, because the range insert could move from or shift an element before it was copied.
5. Added in version 3.0.0.