Niels Lohmann
cc917d7123
* docs: cross-reference json_view and json_document for 3.13.0 Document the new zero-copy document/view API across the docs: add a "Documents and views" section to the basic_json API hub linking to all specializations, point parsing/conversion/modifying pages to the view-based alternatives, add document/view sections to feature pages, update the landing page to mention json_view.hpp/json_literals.hpp, and cross-link debugging/exceptions. Also document wide-string inputs (and ill-formed UTF-16/32 rejection), add parse/accept examples for wide strings, fix related doc gaps, and align features/parsing and FAQ with the added support. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: fix article before std::istream in FAQ Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: clarify document inputs, decoding, get<T>() and editing Address review comments: say which inputs are borrowed and that a wide string pointer is an extra input, which values are decoded during parsing, that get<T>() reads only built-in types directly, all forms of set() and that the document's insert() is array-only, and how to store wide strings. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: integers are converted while parsing a document Also say "They accept every input" in basic_json_document::parse. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.0 KiB
Debugging
This page collects the library's built-in debugger integrations and other debugging-related features. They are not covered by any single page elsewhere in the docs, so they are collected here.
Visual Studio (natvis)
The repository ships nlohmann_json.natvis
at its root, a Natvis
file that gives json/ordered_json values a friendly, key/value debugger view instead of showing raw internal
fields, when debugging with the MSVC debug engine (cppvsdbg) in Visual Studio or VS Code.
The checked-in visualizers cover namespace variants with zero, one, or two ABI tags. Configurations with three or more ABI tags are not covered and may show raw internal fields instead. To generate a Natvis file for such a configuration:
-
Check out the release tag of the library version you use.
-
List the ABI tags and the macros that enable them:
make natvis NATVIS_ARGS="--list-tags" -
Generate a Natvis file with the tags of your configuration, for example for
JSON_DIAGNOSTICS,JSON_DIAGNOSTIC_POSITIONS, andJSON_VIEW_NO_SIMD:make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_vns --output my_nlohmann_json.natvis" -
Use the generated file instead of
nlohmann_json.natvis.
--abi-tags can be repeated for several configurations, and --all generates every combination (about 60 MB for 12
ABI tags, doubling with each further tag). See
tools/generate_natvis for all options.
Debug engines that wrap LLDB instead of the MSVC debug engine (for example, codelldb in VS Code) only have
partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the
.natvis file present. Switching to cppvsdbg where available, or checking your debug extension's own Natvis
support/version, are the next things to try if this happens. There is currently no bundled LLDB-native
pretty-printer script in this repository.
GDB
The repository ships a GDB Python pretty printer
under tools/gdb_pretty_printer, with its own usage instructions in that directory's README.md.
Extended exception diagnostics
Defining JSON_DIAGNOSTICS before including the library augments
type_error/out_of_range-style exceptions with a JSON Pointer to the offending value, which can help pinpoint
where in a large document a runtime error occurred. This only applies to exceptions thrown after a value
exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not
covered by this mechanism -- see Parsing and exceptions for how parse
errors report their own location instead.