1# <small>nlohmann::</small>basic_json 2 3<small>Defined in header `<nlohmann/json.hpp>`</small> 4 5```cpp 6template< 7 template<typename U, typename V, typename... Args> class ObjectType = std::map, 8 template<typename U, typename... Args> class ArrayType = std::vector, 9 class StringType = std::string, 10 class BooleanType = bool, 11 class NumberIntegerType = std::int64_t, 12 class NumberUnsignedType = std::uint64_t, 13 class NumberFloatType = double, 14 template<typename U> class AllocatorType = std::allocator, 15 template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer, 16 class BinaryType = std::vector<std::uint8_t>, 17 class CustomBaseClass = void 18> 19class basic_json; 20``` 21 22## Template parameters 23 24| Template parameter | Description | Derived type | 25|----------------------|---------------------------------------------------------------------------|---------------------------------------------| 26| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) | 27| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) | 28| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) | 29| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) | 30| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) | 31| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) | 32| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) | 33| `AllocatorType` | type of the allocator to use | | 34| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) | 35| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) | 36| `CustomBaseClass` | extension point for user code | [`json_base_class_t`](json_base_class_t.md) | 37 38## Specializations 39 40- [**json**](../json.md) - default specialization 41- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys 42 43## Iterator invalidation 44 45Todo 46 47## Requirements 48 49The class satisfies the following concept requirements: 50 51### Basic 52 53- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default 54 constructed. The result will be a JSON null value. 55- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed 56 from an rvalue argument. 57- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be 58 copy-constructed from an lvalue expression. 59- [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): A JSON value can be assigned from an 60 rvalue argument. 61- [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): A JSON value can be copy-assigned from 62 an lvalue expression. 63- [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): JSON values can be destructed. 64 65### Layout 66 67- [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): JSON values have 68 [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): All non-static data 69 members are private and standard layout types, the class has no virtual functions or (virtual) base classes. 70 71### Library-wide 72 73- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with 74 `==`, see [`operator==`](operator_eq.md). 75- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with 76 `<`, see [`operator<`](operator_le.md). 77- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with 78 any lvalue or rvalue of other compatible types, using unqualified function `swap`. 79- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against 80 `std::nullptr_t` objects which are used to model the `null` value. 81 82### Container 83 84- [Container](https://en.cppreference.com/w/cpp/named_req/Container): JSON values can be used like STL containers and 85 provide iterator access. 86- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer): JSON values can be used like 87 STL containers and provide reverse iterator access. 88 89## Member types 90 91- [**adl_serializer**](../adl_serializer/index.md) - the default serializer 92- [**value_t**](value_t.md) - the JSON type enumeration 93- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation 94- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON 95- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors 96- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags 97- **initializer_list_t** - type for initializer lists of `basic_json` values 98- [**input_format_t**](input_format_t.md) - type to choose the format to parse 99- [**json_sax_t**](../json_sax/index.md) - type for SAX events 100 101### Exceptions 102 103- [**exception**](exception.md) - general exception of the `basic_json` class 104 - [**parse_error**](parse_error.md) - exception indicating a parse error 105 - [**invalid_iterator**](invalid_iterator.md) - exception indicating errors with iterators 106 - [**type_error**](type_error.md) - exception indicating executing a member function with a wrong type 107 - [**out_of_range**](out_of_range.md) - exception indicating access out of the defined range 108 - [**other_error**](other_error.md) - exception indicating other library errors 109 110### Container types 111 112| Type | Definition | 113|--------------------------|-----------------------------------------------------------------------------------------------------------| 114| `value_type` | `#!cpp basic_json` | 115| `reference` | `#!cpp value_type&` | 116| `const_reference` | `#!cpp const value_type&` | 117| `difference_type` | `#!cpp std::ptrdiff_t` | 118| `size_type` | `#!cpp std::size_t` | 119| `allocator_type` | `#!cpp AllocatorType<basic_json>` | 120| `pointer` | `#!cpp std::allocator_traits<allocator_type>::pointer` | 121| `const_pointer` | `#!cpp std::allocator_traits<allocator_type>::const_pointer` | 122| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) | 123| `const_iterator` | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) | 124| `reverse_iterator` | reverse iterator, derived from `iterator` | 125| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` | 126| `iteration_proxy` | helper type for [`items`](items.md) function | 127 128### JSON value data types 129 130- [**array_t**](array_t.md) - type for arrays 131- [**binary_t**](binary_t.md) - type for binary arrays 132- [**boolean_t**](boolean_t.md) - type for booleans 133- [**default_object_comparator_t**](default_object_comparator_t.md) - default comparator for objects 134- [**number_float_t**](number_float_t.md) - type for numbers (floating-point) 135- [**number_integer_t**](number_integer_t.md) - type for numbers (integer) 136- [**number_unsigned_t**](number_unsigned_t.md) - type for numbers (unsigned) 137- [**object_comparator_t**](object_comparator_t.md) - comparator for objects 138- [**object_t**](object_t.md) - type for objects 139- [**string_t**](string_t.md) - type for strings 140 141### Parser callback 142 143- [**parse_event_t**](parse_event_t.md) - parser event types 144- [**parser_callback_t**](parser_callback_t.md) - per-element parser callback type 145 146## Member functions 147 148- [(constructor)](basic_json.md) 149- [(destructor)](~basic_json.md) 150- [**operator=**](operator=.md) - copy assignment 151- [**array**](array_t.md) (_static_) - explicitly create an array 152- [**binary**](binary.md) (_static_) - explicitly create a binary array 153- [**object**](object_t.md) (_static_) - explicitly create an object 154 155### Object inspection 156 157Functions to inspect the type of a JSON value. 158 159- [**type**](type.md) - return the type of the JSON value 160- [**operator value_t**](operator_value_t.md) - return the type of the JSON value 161- [**type_name**](type_name.md) - return the type as string 162- [**is_primitive**](is_primitive.md) - return whether type is primitive 163- [**is_structured**](is_structured.md) - return whether type is structured 164- [**is_null**](is_null.md) - return whether value is null 165- [**is_boolean**](is_boolean.md) - return whether value is a boolean 166- [**is_number**](is_number.md) - return whether value is a number 167- [**is_number_integer**](is_number_integer.md) - return whether value is an integer number 168- [**is_number_unsigned**](is_number_unsigned.md) - return whether value is an unsigned integer number 169- [**is_number_float**](is_number_float.md) - return whether value is a floating-point number 170- [**is_object**](is_object.md) - return whether value is an object 171- [**is_array**](is_array.md) - return whether value is an array 172- [**is_string**](is_string.md) - return whether value is a string 173- [**is_binary**](is_binary.md) - return whether value is a binary array 174- [**is_discarded**](is_discarded.md) - return whether value is discarded 175 176### Value access 177 178Direct access to the stored value of a JSON value. 179 180- [**get**](get.md) - get a value 181- [**get_to**](get_to.md) - get a value and write it to a destination 182- [**get_ptr**](get_ptr.md) - get a pointer value 183- [**get_ref**](get_ref.md) - get a reference value 184- [**operator ValueType**](operator_ValueType.md) - get a value 185- [**get_binary**](get_binary.md) - get a binary value 186 187### Element access 188 189Access to the JSON value 190 191- [**at**](at.md) - access specified element with bounds checking 192- [**operator[]**](operator[].md) - access specified element 193- [**value**](value.md) - access specified object element with default value 194- [**front**](front.md) - access the first element 195- [**back**](back.md) - access the last element 196 197### Lookup 198 199- [**find**](find.md) - find an element in a JSON object 200- [**count**](count.md) - returns the number of occurrences of a key in a JSON object 201- [**contains**](contains.md) - check the existence of an element in a JSON object 202 203### Iterators 204 205- [**begin**](begin.md) - returns an iterator to the first element 206- [**cbegin**](cbegin.md) - returns a const iterator to the first element 207- [**end**](end.md) - returns an iterator to one past the last element 208- [**cend**](cend.md) - returns a const iterator to one past the last element 209- [**rbegin**](rbegin.md) - returns an iterator to the reverse-beginning 210- [**rend**](rend.md) - returns an iterator to the reverse-end 211- [**crbegin**](crbegin.md) - returns a const iterator to the reverse-beginning 212- [**crend**](crend.md) - returns a const iterator to the reverse-end 213- [**items**](items.md) - wrapper to access iterator member functions in range-based for 214 215### Capacity 216 217- [**empty**](empty.md) - checks whether the container is empty 218- [**size**](size.md) - returns the number of elements 219- [**max_size**](max_size.md) - returns the maximum possible number of elements 220 221### Modifiers 222 223- [**clear**](clear.md) - clears the contents 224- [**push_back**](push_back.md) - add a value to an array/object 225- [**operator+=**](operator+=.md) - add a value to an array/object 226- [**emplace_back**](emplace_back.md) - add a value to an array 227- [**emplace**](emplace.md) - add a value to an object if key does not exist 228- [**erase**](erase.md) - remove elements 229- [**insert**](insert.md) - inserts elements 230- [**update**](update.md) - updates a JSON object from another object, overwriting existing keys 231- [**swap**](swap.md) - exchanges the values 232 233### Lexicographical comparison operators 234 235- [**operator==**](operator_eq.md) - comparison: equal 236- [**operator!=**](operator_ne.md) - comparison: not equal 237- [**operator<**](operator_lt.md) - comparison: less than 238- [**operator>**](operator_gt.md) - comparison: greater than 239- [**operator<=**](operator_le.md) - comparison: less than or equal 240- [**operator>=**](operator_ge.md) - comparison: greater than or equal 241- [**operator<=>**](operator_spaceship.md) - comparison: 3-way 242 243### Serialization / Dumping 244 245- [**dump**](dump.md) - serialization 246 247### Deserialization / Parsing 248 249- [**parse**](parse.md) (_static_) - deserialize from a compatible input 250- [**accept**](accept.md) (_static_) - check if the input is valid JSON 251- [**sax_parse**](sax_parse.md) (_static_) - generate SAX events 252 253### JSON Pointer functions 254 255- [**flatten**](flatten.md) - return flattened JSON value 256- [**unflatten**](unflatten.md) - unflatten a previously flattened JSON value 257 258### JSON Patch functions 259 260- [**patch**](patch.md) - applies a JSON patch 261- [**patch_inplace**](patch_inplace.md) - applies a JSON patch in place 262- [**diff**](diff.md) (_static_) - creates a diff as a JSON patch 263 264### JSON Merge Patch functions 265 266- [**merge_patch**](merge_patch.md) - applies a JSON Merge Patch 267 268## Static functions 269 270- [**meta**](meta.md) - returns version information on the library 271- [**get_allocator**](get_allocator.md) - returns the allocator associated with the container 272 273### Binary formats 274 275- [**from_bjdata**](from_bjdata.md) (_static_) - create a JSON value from an input in BJData format 276- [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format 277- [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format 278- [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format 279- [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format 280- [**to_bjdata**](to_bjdata.md) (_static_) - create a BJData serialization of a given JSON value 281- [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value 282- [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value 283- [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value 284- [**to_ubjson**](to_ubjson.md) (_static_) - create a UBJSON serialization of a given JSON value 285 286## Non-member functions 287 288- [**operator<<(std::ostream&)**](../operator_ltlt.md) - serialize to stream 289- [**operator>>(std::istream&)**](../operator_gtgt.md) - deserialize from stream 290- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values 291 292## Literals 293 294- [**operator""_json**](../operator_literal_json.md) - user-defined string literal for JSON values 295 296## Helper classes 297 298- [**std::hash<basic_json>**](std_hash.md) - return a hash value for a JSON object 299- [**std::swap<basic_json>**](std_swap.md) - exchanges the values of two JSON objects 300 301## Examples 302 303??? example 304 305 The example shows how the library is used. 306 307 ```cpp 308 --8<-- "examples/README.cpp" 309 ``` 310 311 Output: 312 313 ```json 314 --8<-- "examples/README.output" 315 ``` 316 317## See also 318 319- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259) 320 321## Version history 322 323- Added in version 1.0.0. 324