mirror of
https://github.com/nlohmann/json.git
synced 2026-07-09 12:05:10 +00:00
deploy: 7c9208bfb3
This commit is contained in:
nlohmann
@@ -0,0 +1,266 @@
|
||||
# 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`.
|
||||
1. Inserts `cnt` copies of `val` into an array before iterator `pos`.
|
||||
1. Inserts elements from range `[first, last)` into an array before iterator `pos`.
|
||||
1. Inserts elements from initializer list `ilist` into an array before iterator `pos`.
|
||||
1. 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()`](https://json.nlohmann.me/api/basic_json/end/index.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](https://json.nlohmann.me/api/basic_json/end/index.md) 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`](https://json.nlohmann.me/api/ordered_json/index.md), 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`.
|
||||
1. iterator pointing to the first element inserted, or `pos` if `cnt==0`
|
||||
1. iterator pointing to the first element inserted, or `pos` if `first==last`
|
||||
1. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
|
||||
1. (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`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if called on JSON values other than arrays; example: `"cannot use insert() with string"`
|
||||
- Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) if called on an iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
|
||||
1. The function can throw the following exceptions:
|
||||
- Throws [`type_error.309`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if called on JSON values other than arrays; example: `"cannot use insert() with string"`
|
||||
- Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) if called on an iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
|
||||
1. The function can throw the following exceptions:
|
||||
- Throws [`type_error.309`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if called on JSON values other than arrays; example: `"cannot use insert() with string"`
|
||||
- Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) 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`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator210) if `first` and `last` do not belong to the same JSON value; example: `"iterators do not fit"`
|
||||
- Throws [`invalid_iterator.211`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator211) if `first` or `last` are iterators into container for which insert is called; example: `"passed iterators may not belong to container"`
|
||||
1. The function can throw the following exceptions:
|
||||
- Throws [`type_error.309`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if called on JSON values other than arrays; example: `"cannot use insert() with string"`
|
||||
- Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) if called on an iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
|
||||
1. The function can throw the following exceptions:
|
||||
- Throws [`type_error.309`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error309) if called on JSON values other than objects; example: `"cannot use insert() with string"`
|
||||
- Throws [`invalid_iterator.202`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator202) if `first` or `last` do not point to an object; example: `"iterators first and last must point to objects"`
|
||||
- Throws [`invalid_iterator.210`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator210) 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.
|
||||
1. Linear in `cnt` plus linear in the distance between `pos` and end of the container.
|
||||
1. Linear in `std::distance(first, last)` plus linear in the distance between `pos` and end of the container.
|
||||
1. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container.
|
||||
1. 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"}
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [emplace](https://json.nlohmann.me/api/basic_json/emplace/index.md) add a value to an object
|
||||
- [emplace_back](https://json.nlohmann.me/api/basic_json/emplace_back/index.md) add a value to an array
|
||||
- [push_back](https://json.nlohmann.me/api/basic_json/push_back/index.md) add a value to an array/object
|
||||
- [update](https://json.nlohmann.me/api/basic_json/update/index.md) merges objects
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 1.0.0.
|
||||
1. Added in version 3.0.0.
|
||||
Reference in New Issue
Block a user