• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# basic_json::operator+=
2
3```cpp
4// (1)
5reference operator+=(basic_json&& val);
6reference operator+=(const basic_json& val);
7
8// (2)
9reference operator+=(const typename object_t::value_type& val);
10
11// (3)
12reference operator+=(initializer_list_t init);
13```
14
151. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an
16   empty array is created before appending `val`.
17
182. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
19   is created before inserting `val`.
20
213. This function allows to use `operator+=` with an initializer list. In case
22
23    1. the current value is an object,
24    2. the initializer list `init` contains only two elements, and
25    3. the first element of `init` is a string,
26
27    `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
28    Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
29
30## Parameters
31
32`val` (in)
33:   the value to add to the JSON array/object
34
35`init` (in)
36:   an initializer list
37
38## Return value
39
40`#!cpp *this`
41
42## Exceptions
43
441. The function can throw the following exceptions:
45    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
46      JSON array or null; example: `"cannot use operator+=() with number"`
472. The function can throw the following exceptions:
48    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
49      JSON object or null; example: `"cannot use operator+=() with number"`
50
51## Complexity
52
531. Amortized constant.
542. Logarithmic in the size of the container, O(log(`size()`)).
553. Linear in the size of the initializer list `init`.
56
57## Notes
58
59(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both
60interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, see
61[#235](https://github.com/nlohmann/json/issues/235) for more information.
62
63## Examples
64
65??? example
66
67    The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
68    was silently converted to a JSON array.
69
70    ```cpp
71    --8<-- "examples/push_back.cpp"
72    ```
73
74    Output:
75
76    ```json
77    --8<-- "examples/push_back.output"
78    ```
79
80??? example
81
82    The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
83    was silently converted to a JSON object.
84
85    ```cpp
86    --8<-- "examples/push_back__object_t__value.cpp"
87    ```
88
89    Output:
90
91    ```json
92    --8<-- "examples/push_back__object_t__value.output"
93    ```
94
95??? example
96
97    The example shows how initializer lists are treated as objects when possible.
98
99    ```cpp
100    --8<-- "examples/push_back__initializer_list.cpp"
101    ```
102
103    Output:
104
105    ```json
106    --8<-- "examples/push_back__initializer_list.output"
107    ```
108
109## Version history
110
1111. Since version 1.0.0.
1122. Since version 1.0.0.
1132. Since version 2.0.0.
114