amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-11-09 14:01:47 +00:00

Files

T

Niels Lohmann 6a852ab96d Split the json_view feature page into sub-pages (#6018 )

* Split the json_view feature page into sub-pages

The single features/json_view.md page grew to ~600 lines covering eight
topics. Split it into features/json_view/ with an overview page and
pages for ownership and lifetime, differences from basic_json, reading
values, generic code, editing, and images.

The new differences page collects what was spread over several sections
("What is the same", "What is different", "Duplicate keys", and notes in
the conversion and serialization sections) under one summary table, and
adds the parts of the basic_json interface a view does not have. The
other pages now link to it instead of restating the rules.

Internal links across the documentation point to the new pages.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Docs: fix stale comments and trim repeated text in json_view pages

- fig-jsonview.js/.css: point the header comments at the new pages
- reading.md: views' strings are valid as long as the document (and a
  borrowed source text), as lifetime.md says
- reading.md, generic_code.md: link to differences.md instead of
  restating the member-order and repeated-key rules
- differences.md: drop the third mention of ordering comparisons, name
  rbegin()/rend() in the iterator row
- exceptions.md: link editable documents to editing.md

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-11-09 08:12:00 +01:00

5.5 KiB

Raw Blame History

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.
Reading and writing files — read and write files safely, including replacing a file without corrupting it.

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).

5.5 KiB Raw Blame History