mirror of
https://github.com/nlohmann/json.git
synced 2026-09-30 22:15:19 +00:00
5a936a2ef3
Add API pages for basic_json_document::save() and load(), including the image_check enumeration and its three levels. Add examples that show caching a parsed document as an image, loading it without parsing, the difference between a borrowed and an owned image, and a full check rejecting a damaged image that a bounds check still reads safely. Add an "Images" section to the json_view feature page, register the new pages in mkdocs.yml and docSet.sql, group basic_json_document's member list by parsing/access/images/edits, and document parse_error.116 and type_error.320 on the exceptions page, extending out_of_range.416 for images. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.5 KiB
3.5 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, and error handling.
- 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, and images load a parsed document 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.
- 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.
- Object order — keep insertion order with
ordered_json. - 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).