amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-10-10 08:27:13 +00:00

Files

T

Niels Lohmann 759dd2e1b1 Add json_document and json_view: node index, parser, and document

Add json_document and json_view, a read-only, zero-copy index of a
JSON text, as the first public slice of the zero-copy view (#5295).

A parse produces a flat array of 16-byte nodes in document order,
one per value and one per object key. Strings stay in the source
text; escaped strings are decoded into an arena. Integers are
converted while their digits are in the cache; floats keep only
their digit layout and are converted on read. Containers store the
size of their subtree, so a reader can step over one in constant
time. A document makes a handful of allocations, however many
values it has.

The parser accepts exactly what json::parse accepts, with every
combination of ignore_comments and ignore_trailing_commas, with and
without a trailing NUL, and under JSON_STRICT_NUL_HANDLING. It is
portable C++11 and does not depend on byte order.

basic_json_document adds parse, parse_copy, accept, read (reuses a
document's memory), root, is_discarded, source, owns_source,
node_count, memory_usage, and shrink_to_fit. basic_json_view adds
type, the is_* queries, operator bool, size, empty, materialize,
and source_offset. A parse error throws the same exception
basic_json::parse would throw for the same input, message and
position included.

detail::abi_config keeps JSON_STRICT_NUL_HANDLING and
JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON readable after json.hpp
undefines them, in the ABI namespace so they always match the
basic_json in use.

A NUL byte that ends a // comment is the end of the input, as in
parse() since #5696.

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

2026-10-07 16:42:22 +02:00

3.3 KiB

Raw Blame History

Modules

This library has experimental support for C++ modules, introduced in C++20. The library can be imported by writing import nlohmann.json; instead of #include <nlohmann/json.hpp>.

Please be aware that the module is experimental and a full test is outstanding, and the exported symbols are subject to change.

Requirements

The nlohmann.json module requires that the build system is configured to build and resolve modules when imported. Obviously, as modules were introduced in C++20, this feature can only be used in C++20 and subsequent versions.

To enable building the nlohmann.json module (which is not done by default), the macro NLOHMANN_JSON_BUILD_MODULES must be passed to the build system.

Example

When using modules rather than headers, the previous example for creating a json object through a JSON file, would instead be:

import std;
import nlohmann.json;

using json = nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

Modules do not export macros

It should be noted that as modules do not export macros, the nlohmann.json module will not export any macros.

Exported symbols

Only the following symbols are exported from nlohmann.json:

nlohmann::adl_serializer
nlohmann::basic_json
nlohmann::basic_json_document
nlohmann::basic_json_view
nlohmann::json
nlohmann::json_document
nlohmann::json_pointer
nlohmann::json_view
nlohmann::ordered_json
nlohmann::ordered_json_document
nlohmann::ordered_json_view
nlohmann::ordered_map
nlohmann::to_string
nlohmann::literals::json_literals::operator""_json
nlohmann::literals::json_literals::operator""_json_pointer

The module always exports the two user-defined string literals, even if JSON_NO_AUTOMATIC_UDLS is defined when building it.

Additionally, the following nlohmann::detail symbols are exported, solely to work around an MSVC compilation issue (#3970). They are implementation details, not part of the public API, and should not be used directly:

nlohmann::detail::json_sax_dom_callback_parser
nlohmann::detail::unknown_size

Known issues

C++20 modules support is exercised in CI against current GCC and Clang on Ubuntu, and the default MSVC toolset on Windows Server 2022 — there is no documented minimum compiler version, unlike feature-test-macro-gated features such as JSON_HAS_RANGES.

!!! info "Known compiler issues"

- **GCC** may emit "redefinition" errors when `#include <nlohmann/json.hpp>` appears in a module preamble together with other imports. This is an upstream GCC bug, not yet resolved as of GCC 16. Workarounds: include `nlohmann/json.hpp` before other `#include`s, use `import nlohmann.json;` instead, or upgrade GCC. ([issue #5103](https://github.com/nlohmann/json/issues/5103))
- **MSVC** could fail with `C2039: 'json_sax_dom_callback_parser' is not a member of ... detail`; fixed by exporting the required internal symbols from `json.cppm` (see [Exported symbols](#exported-symbols) above). ([issue #3970](https://github.com/nlohmann/json/issues/3970))

If you hit a different module-related build failure, search [existing issues](https://github.com/nlohmann/json/issues?q=is%3Aissue+modules) before filing a new one.

3.3 KiB Raw Blame History