• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>insert
2
3```cpp
4// (1)
5iterator insert(const_iterator pos, const basic_json& val);
6iterator insert(const_iterator pos, basic_json&& val);
7
8// (2)
9iterator insert(const_iterator pos, size_type cnt, const basic_json& val);
10
11// (3)
12iterator insert(const_iterator pos, const_iterator first, const_iterator last);
13
14// (4)
15iterator insert(const_iterator pos, initializer_list_t ilist);
16
17// (5)
18void insert(const_iterator first, const_iterator last);
19```
20
211. Inserts element `val` into array before iterator `pos`.
222. Inserts `cnt` copies of `val` into array before iterator `pos`.
233. Inserts elements from range `[first, last)` into array before iterator `pos`.
244. Inserts elements from initializer list `ilist` into array before iterator `pos`.
255. Inserts elements from range `[first, last)` into object.
26
27## Parameters
28
29`pos` (in)
30:   iterator before which the content will be inserted; may be the `end()` iterator
31
32`val` (in)
33:   value to insert
34
35`cnt` (in)
36:   number of copies of `val` to insert
37
38`first` (in)
39:   begin of the range of elements to insert
40
41`last` (in)
42:   end of the range of elements to insert
43
44`ilist` (in)
45:   initializer list to insert the values from
46
47## Return value
48
491. iterator pointing to the inserted `val`.
502. iterator pointing to the first element inserted, or `pos` if `#!cpp cnt==0`
513. iterator pointing to the first element inserted, or `pos` if `#!cpp first==last`
524. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
535. (none)
54
55## Exception safety
56
57Strong exception safety: if an exception occurs, the original value stays intact.
58
59## Exceptions
60
611. The function can throw the following exceptions:
62    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
63      arrays; example: `"cannot use insert() with string"`
64    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
65      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
662. The function can throw the following exceptions:
67    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
68      arrays; example: `"cannot use insert() with string"`
69    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
70      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
713. The function can throw the following exceptions:
72    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
73      arrays; example: `"cannot use insert() with string"`
74    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
75      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
76    - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
77      do not belong to the same JSON value; example: `"iterators do not fit"`
78    - Throws [`invalid_iterator.211`](../../home/exceptions.md#jsonexceptioninvalid_iterator211) if `first` or `last`
79      are iterators into container for which insert is called; example: `"passed iterators may not belong to container"`
804. The function can throw the following exceptions:
81    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
82      arrays; example: `"cannot use insert() with string"`
83    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
84      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
855. The function can throw the following exceptions:
86    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
87      objects; example: `"cannot use insert() with string"`
88    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
89      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
90    - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
91      do not belong to the same JSON value; example: `"iterators do not fit"`
92
93## Complexity
94
951. Constant plus linear in the distance between `pos` and end of the container.
962. Linear in `cnt` plus linear in the distance between `pos` and end of the container.
973. Linear in `#!cpp std::distance(first, last)` plus linear in the distance between `pos` and end of the container.
984. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container.
995. Logarithmic: `O(N*log(size() + N))`, where `N` is the number of elements to insert.
100
101## Examples
102
103??? example "Example (1): insert element into array"
104
105    The example shows how `insert()` is used.
106
107    ```cpp
108    --8<-- "examples/insert.cpp"
109    ```
110
111    Output:
112
113    ```json
114    --8<-- "examples/insert.output"
115    ```
116
117??? example "Example (2): insert copies of element into array"
118
119    The example shows how `insert()` is used.
120
121    ```cpp
122    --8<-- "examples/insert__count.cpp"
123    ```
124
125    Output:
126
127    ```json
128    --8<-- "examples/insert__count.output"
129    ```
130
131??? example "Example (3): insert range of elements into array"
132
133    The example shows how `insert()` is used.
134
135    ```cpp
136    --8<-- "examples/insert__range.cpp"
137    ```
138
139    Output:
140
141    ```json
142    --8<-- "examples/insert__range.output"
143    ```
144
145??? example "Example (4): insert elements from initializer list into array"
146
147    The example shows how `insert()` is used.
148
149    ```cpp
150    --8<-- "examples/insert__ilist.cpp"
151    ```
152
153    Output:
154
155    ```json
156    --8<-- "examples/insert__ilist.output"
157    ```
158
159??? example "Example (5): insert range of elements into object"
160
161    The example shows how `insert()` is used.
162
163    ```cpp
164    --8<-- "examples/insert__range_object.cpp"
165    ```
166
167    Output:
168
169    ```json
170    --8<-- "examples/insert__range_object.output"
171    ```
172
173## Version history
174
1751. Added in version 1.0.0.
1762. Added in version 1.0.0.
1773. Added in version 1.0.0.
1784. Added in version 1.0.0.
1795. Added in version 3.0.0.
180