JSON for Modern C++ 3.8.0

JSON for Modern C++

These pages contain the API documentation of JSON for Modern C++, a C++11 header-only JSON class.

# Contents

- Classes
  - `basic_json` – class template for JSON values
  - `json` – the default specialization of `basic_json`, defined as `basic_json<>`
- Functions
  - object inspection
    - dump – value serialization
    - type – type of the value
    - is_primitive , is_structured , is_null , is_boolean , is_number , is_number_integer , is_number_unsigned , is_number_float , is_object , is_array , is_string , is_discarded , is_binary – check for value type
    - operator value_t – type of the value (implicit conversion)
  - value access
    - get – get a value
    - get_ptr – get a value pointer
    - get_ref – get a value reference
    - get_binary – get a binary value
    - operator ValueType – get a value (implicit conversion)
    - value – get a value from an object and return default value if key is not present
  - exceptions
    - parse_error for exceptions indicating a parse error
    - invalid_iterator for exceptions indicating errors with iterators
    - type_error for exceptions indicating executing a member function with a wrong type
    - out_of_range for exceptions indicating access out of the defined range
    - other_error for exceptions indicating other library errors
  - lexicographical comparison operators
    - operator==
    - operator!=
    - operator<=
    - operator<
    - operator>
    - operator>=
  - serialization
    - dump serialize to string
    - operator<< serialize to stream
  - deserialization / parsing
    - parse parse from input (string, file, etc.) and return JSON value
    - sax_parse parse from input (string, file, etc.) and generate SAX events
    - operator>> parse from stream
    - accept check for syntax errors without parsing
    - SAX interface define a user-defined SAX event consumer
    - callback interface register a callback to the parse function
  - binary formats:
    - CBOR: from_cbor / to_cbor
    - MessagePack: from_msgpack / to_msgpack
    - UBJSON: from_ubjson / to_ubjson
    - BSON: from_bson / to_bson
- Types
  - arrays
  - objects
  - strings
  - booleans
  - numbers
    - signed integers
    - unsigned integers
    - floating-point
  - binary values
- further JSON standards
  - JSON Pointer (RFC 6901)
  - JSON Patch (RFC 6902)
  - JSON Merge Patch (RFC 7396)

# Container function overview

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.

Note that this table only lists those exceptions thrown due to the type. For instance, the `at` function will always throw a `json::type_error` exception when called for a string type. When called for an array, it may throw an `json::out_of_range` exception if the passed index is invalid.

group | function | JSON value type
--- | --- | ---
object | array | string | number | boolean | null
iterators | `begin` | `begin` | `begin` | `begin` | `begin` | `begin` | `begin` (returns `end()`)
`cbegin` | `cbegin` | `cbegin` | `cbegin` | `cbegin` | `cbegin` | `cbegin` (returns `cend()`)
`end` | `end` | `end` | `end` | `end` | `end` | `end`
`cend` | `cend` | `cend` | `cend` | `cend` | `cend` | `cend`
`rbegin` | `rbegin` | `rbegin` | `rbegin` | `rbegin` | `rbegin` | `rbegin`
`crbegin` | `crbegin` | `crbegin` | `crbegin` | `crbegin` | `crbegin` | `crbegin`
`rend` | `rend` | `rend` | `rend` | `rend` | `rend` | `rend`
`crend` | `crend` | `crend` | `crend` | `crend` | `crend` | `crend`
element access | `at` | `at` | `at` | throws `json::type_error` (304) | throws `json::type_error` (304) | throws `json::type_error` (304) | throws `json::type_error` (304)
`operator[]` | `operator[]` | `operator[]` | throws `json::type_error` (305) | throws `json::type_error` (305) | throws `json::type_error` (305) | `operator[]` (creates object) `operator[]` (creates array)
`front` | `front` | `front` | `front` | `front` | `front` | throws `json::invalid_iterator` (214)
`back` | `back` | `back` | `back` | `back` | `back` | throws `json::invalid_iterator` (214)
capacity | `empty` | `empty` | `empty` | `empty` (returns `false`) | `empty` (returns `false`) | `empty` (returns `false`) | `empty` (returns `true`)
`size` | `size` | `size` | `size` (returns `1`) | `size` (returns `1`) | `size` (returns `1`) | `size` (returns `0`)
`max_size_` | `max_size` | `max_size` | `max_size` (returns `1`) | `max_size` (returns `1`) | `max_size` (returns `1`) | `max_size` (returns `0`)
modifiers | `clear` | `clear` | `clear` | `clear` | `clear` | `clear` | `clear`
`insert` | throws `json::type_error` (309) | `insert` | throws `json::type_error` (309) | throws `json::type_error` (309) | throws `json::type_error` (309) | throws `json::type_error` (309)
`erase` | `erase` | `erase` | `erase` (converts to null) | `erase` (converts to null) | `erase` (converts to null) | throws `json::type_error` (307)
`push_back` | `push_back` | `push_back` | throws `json::type_error` (308) | throws `json::type_error` (308) | throws `json::type_error` (308) | `push_back` (creates object) `push_back` (creates array)
`emplace` / `emplace_back` | `emplace` | `emplace_back` | throws `json::type_error` (311) | throws `json::type_error` (311) | throws `json::type_error` (311) | `emplace` (creates object) `emplace_back` (creates array)
`update` | `update` | throws `json::type_error` (312) | throws `json::type_error` (312) | throws `json::type_error` (312) | throws `json::type_error` (312) | throws `json::type_error` (312)
`swap` | `swap` | `swap` | `swap` | `swap` | `swap` | `swap`
lookup | `find` | `find` | `find` (returns `end()`) | `find` (returns `end()`) | `find` (returns `end()`) | `find` (returns `end()`) | `find` (returns `end()`)
`count` | `count` | `count` (returns `0`) | `count` (returns `0`) | `count` (returns `0`) | `count` (returns `0`) | `count` (returns `0`)
`contains` | `contains` | `contains` (returns `false`) | `contains` (returns `false`) | `contains` (returns `false`) | `contains` (returns `false`) | `contains` (returns `false`)

Copyright
  Copyright © 2013-2020 Niels Lohmann. The code is licensed under the MIT License.

Author
  Niels Lohmann

See also
  https://github.com/nlohmann/json to download the source code

Version
  3.8.0