JSON for Modern C++  3.7.0
index.md
1 # JSON for Modern C++
2 
3 These pages contain the API documentation of JSON for Modern C++, a C++11 header-only JSON class.
4 
5 # Contents
6 
7 - Classes
8  - @link nlohmann::basic_json `basic_json`@endlink -- class template for JSON values
9  - @link nlohmann::json `json`@endlink -- the default specialization of `basic_json`, defined as `basic_json<>`
10 - [Functions](functions_func.html)
11  - object inspection
12  - @link nlohmann::basic_json::dump dump @endlink -- value serialization
13  - @link nlohmann::basic_json::type type @endlink -- type of the value
14  - @link nlohmann::basic_json::is_primitive is_primitive @endlink,
15  @link nlohmann::basic_json::is_structured is_structured @endlink,
16  @link nlohmann::basic_json::is_null is_null @endlink,
17  @link nlohmann::basic_json::is_boolean is_boolean @endlink,
18  @link nlohmann::basic_json::is_number is_number @endlink,
19  @link nlohmann::basic_json::is_number_integer is_number_integer @endlink,
20  @link nlohmann::basic_json::is_number_unsigned is_number_unsigned @endlink,
21  @link nlohmann::basic_json::is_number_float is_number_float @endlink,
22  @link nlohmann::basic_json::is_object is_object @endlink,
23  @link nlohmann::basic_json::is_array is_array @endlink,
24  @link nlohmann::basic_json::is_string is_string @endlink,
25  @link nlohmann::basic_json::is_discarded is_discarded @endlink -- check for value type
26  - @link nlohmann::basic_json::operator value_t() const operator value_t @endlink -- type of the value (implicit conversion)
27  - value access
28  - @link nlohmann::basic_json::get get @endlink -- get a value
29  - @link nlohmann::basic_json::get_ptr get_ptr @endlink -- get a value pointer
30  - @link nlohmann::basic_json::get_ref get_ref @endlink -- get a value reference
31  - @link nlohmann::basic_json::operator ValueType() const operator ValueType @endlink -- get a value (implicit conversion)
32  - @link nlohmann::basic_json::value value @endlink -- get a value from an object and return default value if key is not present
33  - exceptions
34  - @link nlohmann::basic_json::parse_error parse_error @endlink for exceptions indicating a parse error
35  - @link nlohmann::basic_json::invalid_iterator invalid_iterator @endlink for exceptions indicating errors with iterators
36  - @link nlohmann::basic_json::type_error type_error @endlink for exceptions indicating executing a member function with a wrong type
37  - @link nlohmann::basic_json::out_of_range out_of_range @endlink for exceptions indicating access out of the defined range
38  - @link nlohmann::basic_json::other_error other_error @endlink for exceptions indicating other library errors
39  - lexicographical comparison operators
40  - @link nlohmann::basic_json::operator== operator== @endlink
41  - @link nlohmann::basic_json::operator!= operator!= @endlink
42  - @link nlohmann::basic_json::operator< operator<= @endlink
43  - @link nlohmann::basic_json::operator<= operator< @endlink
44  - @link nlohmann::basic_json::operator> operator> @endlink
45  - @link nlohmann::basic_json::operator>= operator>= @endlink
46  - serialization
47  - @link nlohmann::basic_json::dump dump @endlink serialize to string
48  - @link nlohmann::basic_json::operator<<(std::ostream&, const basic_json &) operator<< @endlink serialize to stream
49  - deserialization / parsing
50  - @link nlohmann::basic_json::parse parse @endlink parse from input (string, file, etc.) and return JSON value
51  - @link nlohmann::basic_json::sax_parse sax_parse @endlink parse from input (string, file, etc.) and generate SAX events
52  - @link nlohmann::basic_json::operator>>(std::istream&, basic_json&) operator>> @endlink parse from stream
53  - @link nlohmann::basic_json::accept accept @endlink check for syntax errors without parsing
54  - @link nlohmann::json_sax SAX interface @endlink define a user-defined SAX event consumer
55  - @link nlohmann::basic_json::parser_callback_t callback interface @endlink register a callback to the parse function
56  - [binary formats](binary_formats.md):
57  - CBOR: @link nlohmann::basic_json::from_cbor from_cbor @endlink / @link nlohmann::basic_json::to_cbor to_cbor @endlink
58  - MessagePack: @link nlohmann::basic_json::from_msgpack from_msgpack @endlink / @link nlohmann::basic_json::to_msgpack to_msgpack @endlink
59  - UBJSON: @link nlohmann::basic_json::from_ubjson from_ubjson @endlink / @link nlohmann::basic_json::to_ubjson to_ubjson @endlink
60  - BSON: @link nlohmann::basic_json::from_bson from_bson @endlink / @link nlohmann::basic_json::to_bson to_bson @endlink
61 - Types
62  - @link nlohmann::basic_json::array_t arrays @endlink
63  - @link nlohmann::basic_json::object_t objects @endlink
64  - @link nlohmann::basic_json::string_t strings @endlink
65  - @link nlohmann::basic_json::boolean_t booleans @endlink
66  - numbers
67  - @link nlohmann::basic_json::number_integer_t signed integers @endlink
68  - @link nlohmann::basic_json::number_unsigned_t unsigned integers @endlink
69  - @link nlohmann::basic_json::number_float_t floating-point @endlink
70 - further JSON standards
71  - @link nlohmann::json_pointer JSON Pointer @endlink (REF 6901)
72  - @link nlohmann::basic_json::patch JSON Patch @endlink (RFC 6902)
73  - @link nlohmann::basic_json::merge_patch JSON Merge Patch @endlink (RFC 7396)
74 
75 # Container function overview
76 
77 The container functions known from STL have been extended to support the different value types from JSON. However, not all functions can be applied to all value types. Note that the signature of some functions differ between the types; for instance, `at` may be called with either a string to address a key in an object or with an integer to address a value in an array.
78 
79 Note that this table only lists those exceptions thrown due to the type. For instance, the @link nlohmann::basic_json::at(const typename object_t::key_type & key) `at` @endlink function will always throw a @link nlohmann::basic_json::type_error `json::type_error` @endlink exception when called for a string type. When called for an array, it *may* throw an @link nlohmann::basic_json::out_of_range `json::out_of_range` @endlink exception if the passed index is invalid.
80 
81 <table>
82  <tr>
83  <th rowspan="2">group</td>
84  <th rowspan="2">function</td>
85  <th colspan="6">JSON value type</th>
86  </tr>
87  <tr>
88  <th>object</th>
89  <th>array</th>
90  <th>string</th>
91  <th>number</th>
92  <th>boolean</th>
93  <th>null</th>
94  </tr>
95  <tr>
96  <td rowspan="8">iterators</td>
97  <td>`begin`</td>
98  <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
99  <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
100  <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
101  <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
102  <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td>
103  <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink (returns `end()`)</td>
104  </tr>
105  <tr>
106  <td>`cbegin`</td>
107  <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
108  <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
109  <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
110  <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
111  <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td>
112  <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink (returns `cend()`)</td>
113  </tr>
114  <tr>
115  <td>`end`</td>
116  <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
117  <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
118  <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
119  <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
120  <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
121  <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td>
122  </tr>
123  <tr>
124  <td>`cend`</td>
125  <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
126  <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
127  <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
128  <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
129  <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
130  <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td>
131  </tr>
132  <tr>
133  <td>`rbegin`</td>
134  <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
135  <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
136  <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
137  <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
138  <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
139  <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td>
140  </tr>
141  <tr>
142  <td>`crbegin`</td>
143  <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
144  <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
145  <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
146  <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
147  <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
148  <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td>
149  </tr>
150  <tr>
151  <td>`rend`</td>
152  <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
153  <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
154  <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
155  <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
156  <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
157  <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td>
158  </tr>
159  <tr>
160  <td>`crend`</td>
161  <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
162  <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
163  <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
164  <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
165  <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
166  <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td>
167  </tr>
168  <tr>
169  <td rowspan="4">element<br>access</td>
170  <td>`at`</td>
171  <td class="ok_green">@link nlohmann::basic_json::at(const typename object_t::key_type & key) `at` @endlink</td>
172  <td class="ok_green">@link nlohmann::basic_json::at(size_type) `at` @endlink</td>
173  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td>
174  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td>
175  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td>
176  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td>
177  </tr>
178  <tr>
179  <td>`operator[]`</td>
180  <td class="ok_green">@link nlohmann::basic_json::operator[](const typename object_t::key_type &key) `operator[]` @endlink</td>
181  <td class="ok_green">@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlink</td>
182  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (305)</td>
183  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (305)</td>
184  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (305)</td>
185  <td class="ok_green">@link nlohmann::basic_json::operator[](const typename object_t::key_type & key) `operator[]` @endlink (creates object)<br>@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlink (creates array)</td>
186  </tr>
187  <tr>
188  <td>`front`</td>
189  <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
190  <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
191  <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
192  <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
193  <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td>
194  <td class="nok_throws">throws @link nlohmann::basic_json::invalid_iterator `json::invalid_iterator` @endlink (214)</td>
195  </tr>
196  <tr>
197  <td>`back`</td>
198  <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
199  <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
200  <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
201  <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
202  <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td>
203  <td class="nok_throws">throws @link nlohmann::basic_json::invalid_iterator `json::invalid_iterator` @endlink (214)</td>
204  </tr>
205  <tr>
206  <td rowspan="3">capacity</td>
207  <td>`empty`</td>
208  <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink</td>
209  <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink</td>
210  <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td>
211  <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td>
212  <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td>
213  <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `true`)</td>
214  </tr>
215  <tr>
216  <td>`size`</td>
217  <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink</td>
218  <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink</td>
219  <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td>
220  <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td>
221  <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td>
222  <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `0`)</td>
223  </tr>
224  <tr>
225  <td>`max_size_`</td>
226  <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink</td>
227  <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink</td>
228  <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td>
229  <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td>
230  <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td>
231  <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `0`)</td>
232  </tr>
233  <tr>
234  <td rowspan="7">modifiers</td>
235  <td>`clear`</td>
236  <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
237  <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
238  <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
239  <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
240  <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
241  <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td>
242  </tr>
243  <tr>
244  <td>`insert`</td>
245  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td>
246  <td class="ok_green">@link nlohmann::basic_json::insert `insert` @endlink</td>
247  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td>
248  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td>
249  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td>
250  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td>
251  </tr>
252  <tr>
253  <td>`erase`</td>
254  <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink</td>
255  <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink</td>
256  <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td>
257  <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td>
258  <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td>
259  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (307)</td>
260  </tr>
261  <tr>
262  <td>`push_back`</td>
263  <td class="ok_green">@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink</td>
264  <td class="ok_green">@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlink</td>
265  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (308)</td>
266  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (308)</td>
267  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (308)</td>
268  <td class="ok_green">@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink (creates object)<br>@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlink (creates array)</td>
269  </tr>
270  <tr>
271  <td>`emplace` / `emplace_back`</td>
272  <td class="ok_green">@link nlohmann::basic_json::emplace() `emplace` @endlink</td>
273  <td class="ok_green">@link nlohmann::basic_json::emplace_back() `emplace_back` @endlink</td>
274  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (311)</td>
275  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (311)</td>
276  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (311)</td>
277  <td class="ok_green">@link nlohmann::basic_json::emplace() `emplace` @endlink (creates object)<br>@link nlohmann::basic_json::emplace_back() `emplace_back` @endlink (creates array)</td>
278  </tr>
279  <tr>
280  <td>`update`</td>
281  <td class="ok_green">@link nlohmann::basic_json::update() `update` @endlink</td>
282  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td>
283  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td>
284  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td>
285  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td>
286  <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td>
287  </tr>
288  <tr>
289  <td>`swap`</td>
290  <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
291  <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
292  <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
293  <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
294  <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
295  <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td>
296  </tr>
297  <tr>
298  <td rowspan="3">lookup</td>
299  <td>`find`</td>
300  <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink</td>
301  <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
302  <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
303  <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
304  <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
305  <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td>
306  </tr>
307  <tr>
308  <td>`count`</td>
309  <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink</td>
310  <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
311  <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
312  <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
313  <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
314  <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td>
315  </tr>
316  <tr>
317  <td>`contains`</td>
318  <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink</td>
319  <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td>
320  <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td>
321  <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td>
322  <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td>
323  <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td>
324  </tr>
325 </table>
326 
327 @copyright Copyright &copy; 2013-2019 Niels Lohmann. The code is licensed under the [MIT License](http://opensource.org/licenses/MIT).
328 
329 @author [Niels Lohmann](http://nlohmann.me)
330 @see https://github.com/nlohmann/json to download the source code
331 
332 @version 3.7.0