1# JSON for Modern C++ 2 3These 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, 26 @link nlohmann::basic_json::is_binary is_binary @endlink -- check for value type 27 - @link nlohmann::basic_json::operator value_t() const operator value_t @endlink -- type of the value (implicit conversion) 28 - value access 29 - @link nlohmann::basic_json::get get @endlink -- get a value 30 - @link nlohmann::basic_json::get_ptr get_ptr @endlink -- get a value pointer 31 - @link nlohmann::basic_json::get_ref get_ref @endlink -- get a value reference 32 - @link nlohmann::basic_json::get_binary get_binary @endlink -- get a binary value 33 - @link nlohmann::basic_json::operator ValueType() const operator ValueType @endlink -- get a value (implicit conversion) 34 - @link nlohmann::basic_json::value value @endlink -- get a value from an object and return default value if key is not present 35 - exceptions 36 - @link nlohmann::basic_json::parse_error parse_error @endlink for exceptions indicating a parse error 37 - @link nlohmann::basic_json::invalid_iterator invalid_iterator @endlink for exceptions indicating errors with iterators 38 - @link nlohmann::basic_json::type_error type_error @endlink for exceptions indicating executing a member function with a wrong type 39 - @link nlohmann::basic_json::out_of_range out_of_range @endlink for exceptions indicating access out of the defined range 40 - @link nlohmann::basic_json::other_error other_error @endlink for exceptions indicating other library errors 41 - lexicographical comparison operators 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 - @link nlohmann::basic_json::operator> operator> @endlink 47 - @link nlohmann::basic_json::operator>= operator>= @endlink 48 - serialization 49 - @link nlohmann::basic_json::dump dump @endlink serialize to string 50 - @link nlohmann::basic_json::operator<<(std::ostream&, const basic_json &) operator<< @endlink serialize to stream 51 - deserialization / parsing 52 - @link nlohmann::basic_json::parse parse @endlink parse from input (string, file, etc.) and return JSON value 53 - @link nlohmann::basic_json::sax_parse sax_parse @endlink parse from input (string, file, etc.) and generate SAX events 54 - @link nlohmann::basic_json::operator>>(std::istream&, basic_json&) operator>> @endlink parse from stream 55 - @link nlohmann::basic_json::accept accept @endlink check for syntax errors without parsing 56 - @link nlohmann::json_sax SAX interface @endlink define a user-defined SAX event consumer 57 - @link nlohmann::basic_json::parser_callback_t callback interface @endlink register a callback to the parse function 58 - [binary formats](binary_formats.md): 59 - CBOR: @link nlohmann::basic_json::from_cbor from_cbor @endlink / @link nlohmann::basic_json::to_cbor to_cbor @endlink 60 - MessagePack: @link nlohmann::basic_json::from_msgpack from_msgpack @endlink / @link nlohmann::basic_json::to_msgpack to_msgpack @endlink 61 - UBJSON: @link nlohmann::basic_json::from_ubjson from_ubjson @endlink / @link nlohmann::basic_json::to_ubjson to_ubjson @endlink 62 - BSON: @link nlohmann::basic_json::from_bson from_bson @endlink / @link nlohmann::basic_json::to_bson to_bson @endlink 63- Types 64 - @link nlohmann::basic_json::array_t arrays @endlink 65 - @link nlohmann::basic_json::object_t objects @endlink 66 - @link nlohmann::basic_json::string_t strings @endlink 67 - @link nlohmann::basic_json::boolean_t booleans @endlink 68 - numbers 69 - @link nlohmann::basic_json::number_integer_t signed integers @endlink 70 - @link nlohmann::basic_json::number_unsigned_t unsigned integers @endlink 71 - @link nlohmann::basic_json::number_float_t floating-point @endlink 72 - @link nlohmann::basic_json::binary_t binary values @endlink 73- further JSON standards 74 - @link nlohmann::json_pointer JSON Pointer @endlink (RFC 6901) 75 - @link nlohmann::basic_json::patch JSON Patch @endlink (RFC 6902) 76 - @link nlohmann::basic_json::merge_patch JSON Merge Patch @endlink (RFC 7396) 77 78# Container function overview 79 80The 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. 81 82Note 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. 83 84<table> 85 <tr> 86 <th rowspan="2">group</th> 87 <th rowspan="2">function</th> 88 <th colspan="6">JSON value type</th> 89 </tr> 90 <tr> 91 <th>object</th> 92 <th>array</th> 93 <th>string</th> 94 <th>number</th> 95 <th>boolean</th> 96 <th>null</th> 97 </tr> 98 <tr> 99 <td rowspan="8">iterators</td> 100 <td>`begin`</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</td> 104 <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td> 105 <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink</td> 106 <td class="ok_green">@link nlohmann::basic_json::begin `begin` @endlink (returns `end()`)</td> 107 </tr> 108 <tr> 109 <td>`cbegin`</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</td> 113 <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td> 114 <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink</td> 115 <td class="ok_green">@link nlohmann::basic_json::cbegin `cbegin` @endlink (returns `cend()`)</td> 116 </tr> 117 <tr> 118 <td>`end`</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 <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td> 123 <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td> 124 <td class="ok_green">@link nlohmann::basic_json::end `end` @endlink</td> 125 </tr> 126 <tr> 127 <td>`cend`</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 <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td> 132 <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td> 133 <td class="ok_green">@link nlohmann::basic_json::cend `cend` @endlink</td> 134 </tr> 135 <tr> 136 <td>`rbegin`</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 <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td> 141 <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td> 142 <td class="ok_green">@link nlohmann::basic_json::rbegin `rbegin` @endlink</td> 143 </tr> 144 <tr> 145 <td>`crbegin`</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 <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td> 150 <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td> 151 <td class="ok_green">@link nlohmann::basic_json::crbegin `crbegin` @endlink</td> 152 </tr> 153 <tr> 154 <td>`rend`</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 <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td> 159 <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td> 160 <td class="ok_green">@link nlohmann::basic_json::rend `rend` @endlink</td> 161 </tr> 162 <tr> 163 <td>`crend`</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 <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td> 168 <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td> 169 <td class="ok_green">@link nlohmann::basic_json::crend `crend` @endlink</td> 170 </tr> 171 <tr> 172 <td rowspan="4">element<br>access</td> 173 <td>`at`</td> 174 <td class="ok_green">@link nlohmann::basic_json::at(const typename object_t::key_type & key) `at` @endlink</td> 175 <td class="ok_green">@link nlohmann::basic_json::at(size_type) `at` @endlink</td> 176 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td> 177 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td> 178 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td> 179 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (304)</td> 180 </tr> 181 <tr> 182 <td>`operator[]`</td> 183 <td class="ok_green">@link nlohmann::basic_json::operator[](const typename object_t::key_type &key) `operator[]` @endlink</td> 184 <td class="ok_green">@link nlohmann::basic_json::operator[](size_type) `operator[]` @endlink</td> 185 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (305)</td> 186 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (305)</td> 187 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (305)</td> 188 <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> 189 </tr> 190 <tr> 191 <td>`front`</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="ok_green">@link nlohmann::basic_json::front `front` @endlink</td> 195 <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td> 196 <td class="ok_green">@link nlohmann::basic_json::front `front` @endlink</td> 197 <td class="nok_throws">throws @link nlohmann::basic_json::invalid_iterator `json::invalid_iterator` @endlink (214)</td> 198 </tr> 199 <tr> 200 <td>`back`</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="ok_green">@link nlohmann::basic_json::back `back` @endlink</td> 204 <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td> 205 <td class="ok_green">@link nlohmann::basic_json::back `back` @endlink</td> 206 <td class="nok_throws">throws @link nlohmann::basic_json::invalid_iterator `json::invalid_iterator` @endlink (214)</td> 207 </tr> 208 <tr> 209 <td rowspan="3">capacity</td> 210 <td>`empty`</td> 211 <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink</td> 212 <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink</td> 213 <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td> 214 <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td> 215 <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `false`)</td> 216 <td class="ok_green">@link nlohmann::basic_json::empty `empty` @endlink (returns `true`)</td> 217 </tr> 218 <tr> 219 <td>`size`</td> 220 <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink</td> 221 <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink</td> 222 <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td> 223 <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td> 224 <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `1`)</td> 225 <td class="ok_green">@link nlohmann::basic_json::size `size` @endlink (returns `0`)</td> 226 </tr> 227 <tr> 228 <td>`max_size_`</td> 229 <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink</td> 230 <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink</td> 231 <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td> 232 <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td> 233 <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `1`)</td> 234 <td class="ok_green">@link nlohmann::basic_json::max_size `max_size` @endlink (returns `0`)</td> 235 </tr> 236 <tr> 237 <td rowspan="7">modifiers</td> 238 <td>`clear`</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 <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td> 243 <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td> 244 <td class="ok_green">@link nlohmann::basic_json::clear `clear` @endlink</td> 245 </tr> 246 <tr> 247 <td>`insert`</td> 248 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td> 249 <td class="ok_green">@link nlohmann::basic_json::insert `insert` @endlink</td> 250 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td> 251 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td> 252 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td> 253 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (309)</td> 254 </tr> 255 <tr> 256 <td>`erase`</td> 257 <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink</td> 258 <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink</td> 259 <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td> 260 <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td> 261 <td class="ok_green">@link nlohmann::basic_json::erase `erase` @endlink (converts to null)</td> 262 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (307)</td> 263 </tr> 264 <tr> 265 <td>`push_back`</td> 266 <td class="ok_green">@link nlohmann::basic_json::push_back(const typename object_t::value_type & val) `push_back` @endlink</td> 267 <td class="ok_green">@link nlohmann::basic_json::push_back(const nlohmann::basic_json &) `push_back` @endlink</td> 268 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (308)</td> 269 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (308)</td> 270 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (308)</td> 271 <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> 272 </tr> 273 <tr> 274 <td>`emplace` / `emplace_back`</td> 275 <td class="ok_green">@link nlohmann::basic_json::emplace() `emplace` @endlink</td> 276 <td class="ok_green">@link nlohmann::basic_json::emplace_back() `emplace_back` @endlink</td> 277 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (311)</td> 278 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (311)</td> 279 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (311)</td> 280 <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> 281 </tr> 282 <tr> 283 <td>`update`</td> 284 <td class="ok_green">@link nlohmann::basic_json::update() `update` @endlink</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 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td> 288 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td> 289 <td class="nok_throws">throws @link nlohmann::basic_json::type_error `json::type_error` @endlink (312)</td> 290 </tr> 291 <tr> 292 <td>`swap`</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 <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td> 297 <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td> 298 <td class="ok_green">@link nlohmann::basic_json::swap `swap` @endlink</td> 299 </tr> 300 <tr> 301 <td rowspan="3">lookup</td> 302 <td>`find`</td> 303 <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink</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 <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td> 307 <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td> 308 <td class="ok_green">@link nlohmann::basic_json::find `find` @endlink (returns `end()`)</td> 309 </tr> 310 <tr> 311 <td>`count`</td> 312 <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink</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 <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td> 316 <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td> 317 <td class="ok_green">@link nlohmann::basic_json::count `count` @endlink (returns `0`)</td> 318 </tr> 319 <tr> 320 <td>`contains`</td> 321 <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink</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 <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td> 325 <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td> 326 <td class="ok_green">@link nlohmann::basic_json::contains `contains` @endlink (returns `false`)</td> 327 </tr> 328</table> 329 330@copyright Copyright © 2013-2020 Niels Lohmann. The code is licensed under the [MIT License](http://opensource.org/licenses/MIT). 331 332@author [Niels Lohmann](http://nlohmann.me) 333@see https://github.com/nlohmann/json to download the source code 334 335@version 3.9.1 336