mirror of
https://github.com/nlohmann/json.git
synced 2026-10-13 01:47:11 +00:00
223 lines
6.0 KiB
Markdown
223 lines
6.0 KiB
Markdown
# <small>nlohmann::basic_json::</small>operator+=
|
|
|
|
```cpp
|
|
// (1)
|
|
reference operator+=(basic_json&& val);
|
|
reference operator+=(const basic_json& val);
|
|
|
|
// (2)
|
|
reference operator+=(const typename object_t::value_type& val);
|
|
|
|
// (3)
|
|
reference operator+=(initializer_list_t init);
|
|
```
|
|
|
|
1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an
|
|
empty array is created before appending `val`.
|
|
|
|
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
|
|
is created before inserting `val`.
|
|
|
|
3. This function allows using `operator+=` with an initializer list. In case
|
|
|
|
1. the current value is an object,
|
|
2. the initializer list `init` contains only two elements, and
|
|
3. the first element of `init` is a string,
|
|
|
|
`init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
|
|
Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
|
|
|
|
## 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()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the
|
|
[`end()`](end.md) iterator is invalidated.
|
|
|
|
For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again
|
|
invalidates all iterators and all references.
|
|
|
|
## Parameters
|
|
|
|
`val` (in)
|
|
: the value to add to the JSON array/object
|
|
|
|
`init` (in)
|
|
: an initializer list
|
|
|
|
## Return value
|
|
|
|
`#!cpp *this`
|
|
|
|
## Exception safety
|
|
|
|
Strong guarantee: if an exception is thrown, there are no changes to any JSON value. As an exception, a `#!json null`
|
|
value is converted to an empty array or object before the element is added and keeps that type if adding the element
|
|
throws.
|
|
|
|
## Exceptions
|
|
|
|
1. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
|
|
JSON array or null; example: `"cannot use push_back() with number"`
|
|
2. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
|
|
JSON object or null; example: `"cannot use push_back() with number"`
|
|
3. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
|
|
JSON array or null; example: `"cannot use push_back() with number"`
|
|
|
|
## Complexity
|
|
|
|
1. Amortized constant.
|
|
2. Logarithmic in the size of the container, O(log(`size()`)).
|
|
3. Linear in the size of the initializer list `init`.
|
|
|
|
## Notes
|
|
|
|
(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both
|
|
interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, see
|
|
[#235](https://github.com/nlohmann/json/issues/235) for more information.
|
|
|
|
## Examples
|
|
|
|
??? example "Example: (1) add element to array"
|
|
|
|
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
|
|
was silently converted to a JSON array.
|
|
|
|
```cpp
|
|
#include <iostream>
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
// create JSON values
|
|
json array = {1, 2, 3, 4, 5};
|
|
json null;
|
|
|
|
// print values
|
|
std::cout << array << '\n';
|
|
std::cout << null << '\n';
|
|
|
|
// add values
|
|
array.push_back(6);
|
|
array += 7;
|
|
null += "first";
|
|
null += "second";
|
|
|
|
// print values
|
|
std::cout << array << '\n';
|
|
std::cout << null << '\n';
|
|
}
|
|
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
[1,2,3,4,5]
|
|
null
|
|
[1,2,3,4,5,6,7]
|
|
["first","second"]
|
|
|
|
```
|
|
|
|
??? example "Example: (2) add element to object"
|
|
|
|
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
|
|
was silently converted to a JSON object.
|
|
|
|
```cpp
|
|
#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
|
|
object.push_back(json::object_t::value_type("three", 3));
|
|
object += json::object_t::value_type("four", 4);
|
|
null += json::object_t::value_type("A", "a");
|
|
null += json::object_t::value_type("B", "b");
|
|
|
|
// print values
|
|
std::cout << object << '\n';
|
|
std::cout << null << '\n';
|
|
}
|
|
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{"one":1,"two":2}
|
|
null
|
|
{"four":4,"one":1,"three":3,"two":2}
|
|
{"A":"a","B":"b"}
|
|
|
|
```
|
|
|
|
??? example "Example: (3) add to object from initializer list"
|
|
|
|
The example shows how initializer lists are treated as objects when possible.
|
|
|
|
```cpp
|
|
#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:
|
|
object.push_back({"three", 3}); // object is extended
|
|
object += {"four", 4}; // object is extended
|
|
null.push_back({"five", 5}); // null is converted to array
|
|
|
|
// print values
|
|
std::cout << object << '\n';
|
|
std::cout << null << '\n';
|
|
|
|
// would throw:
|
|
//object.push_back({1, 2, 3});
|
|
}
|
|
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{"one":1,"two":2}
|
|
null
|
|
{"four":4,"one":1,"three":3,"two":2}
|
|
[["five",5]]
|
|
|
|
```
|
|
|
|
## See also
|
|
|
|
- [emplace_back](emplace_back.md) add a value to an array
|
|
- [push_back](push_back.md) add a value to an array/object
|
|
|
|
## Version history
|
|
|
|
1. Since version 1.0.0.
|
|
2. Since version 1.0.0.
|
|
3. Since version 2.0.0.
|