json/docs/mkdocs/docs/features/index.md

Features

This section describes the features of the library in detail. If you are new to the library, the pages below are roughly ordered along a typical workflow: create or parse a value, access and modify it, convert it to and from your own C++ types, and finally serialize it again.

Creating and reading values

• Creating JSON values — build values from literals, initializer lists, and STL containers, and understand the #!cpp {} vs. #!cpp [] ambiguity.
• Parsing — read a JSON value from a string, file, or stream, including JSON Lines, callbacks, the SAX interface, error handling, large and partial input, and parsing untrusted input.
• Zero-copy JSON views — read a JSON text through a flat index instead of building a json tree; strings and numbers stay in the input and are only decoded when needed.
• Editable documents — modify a parsed document without building a json tree.
• Images — save a parsed document and load it again without parsing it.
• Comments and trailing commas — opt-in relaxations of the JSON grammar.

Accessing and modifying values

• Element access — unchecked (operator[]), checked (at), and access with a default value.
• JSON Pointer — address values deep inside a document with RFC 6901 pointers.
• Iterators — traverse arrays and objects.
• Modifying values — add, update, merge, and remove elements.
• JSON Patch and Diff and JSON Merge Patch — apply and compute structured changes.

Converting to and from C++ types

• Converting values — get values out with get/get_to, and understand implicit conversions.
• Arbitrary types conversions — teach the library about your own structs and classes.
• Recipes for common types — convert smart pointers, std::variant, std::chrono types, and class hierarchies, which the library deliberately leaves to you.
• Specializing enum conversion — map enums to strings instead of integers.

Serializing values

• Serialization — turn a value back into JSON text with dump, including pretty-printing and handling of non-ASCII and invalid UTF-8.
• Binary formats — encode values more compactly as BJData, BON8, BSON, CBOR, MessagePack, or UBJSON.
• Binary values — store and exchange raw byte sequences.

How values are stored and configured

• Types and number handling — how JSON types map to C++ types and how numbers are treated.
• Template parameter requirements — what a type passed as one of basic_json's template parameters has to provide.
• Object order — keep insertion order with ordered_json.
• Performance — practical advice on parsing, memory use, serialization, and compile times.
• Working without exceptions — what to use when exceptions are unwanted or unavailable.
• Runtime assertions, supported macros, the nlohmann namespace, and C++ modules — build-time and runtime configuration.

!!! tip "Looking for a specific function?"

This section gives conceptual overviews. For the precise signature, parameters, and return value of a function, see
the [API Documentation](../api/basic_json/index.md).

See also

• API documentation - reference of all classes and functions
• FAQ - answers to common questions
• Exceptions - all exceptions and their error codes
• Design goals - the goals behind the library
• Integration - how to add the library to a project
• Macros - reference of all macros
• json_pointer - the JSON Pointer class
• adl_serializer - customization point for type conversions
• json_sax - interface of the SAX parser events
• json_document - an immutable document with a flat index
• json_view - a non-owning view of a value in a document
• byte_container_with_subtype - binary values with a subtype
• ordered_json - a JSON type preserving insertion order
• Supported Macros - all supported macros
• nlohmann Namespace - the library namespace