mirror of
https://github.com/nlohmann/json.git
synced 2026-10-06 14:40:32 +00:00
Niels Lohmann
a0b98325cf
basic_json_document gets a second template parameter, Editable (false by default), plus the aliases json_editable_document, json_editable_view, ordered_json_editable_document and ordered_json_editable_view. Editable documents can change values and structure without rewriting the source text: set()/push_back() on values, keys, array indices and JSON pointers; insert() before an array element; erase() of an object key, array index or JSON pointer. New values and element sequences go into edit storage that the document owns and never moves, so views keep referring to their value across edits and a parsed node never moves. Read-only documents walk the plain node array and are unaffected. Strings are checked for UTF-8 on entry, so dump() of an editable document never throws type_error.316. Binary values cannot be stored (type_error.319). A seeded differential test applies random edits to an editable document and to the equivalent ordered_json and compares both after every step. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.8 KiB
3.8 KiB
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, and parsing untrusted input.
- Zero-copy JSON views — read a JSON text through a flat index instead of building a
jsontree; strings and numbers stay in the input and are only decoded when needed. Editable documents can also be modified. - 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.
- 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.
- Runtime assertions, supported macros, the
nlohmannnamespace, 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).