mirror of https://github.com/nlohmann/json.git synced 2026-07-11 21:15:10 +00:00

Files

T

Niels Lohmann 521a084827 Documentation review (#5257 )

* 📡 Fix documentation gaps for 3.13.0 release (todos 138-142)

- Todo 138: Add "Known issues" section to modules.md with compiler-specific troubleshooting (GCC redefinition, MSVC symbol export). Add pointer note to quality_assurance.md.
- Todo 139: Document CBOR/MessagePack half-precision float encoding for NaN/Infinity (0xF9/0xCA with exact byte sequences). Explain pre-3.13.0 double-precision bug mechanism without issue citations.
- Todo 140: Document CBOR negative-integer-overflow rejection (parse_error.112) for magnitudes exceeding int64_t range (already implemented in rev 1).
- Todo 141: Update version history in value.md and operator[].md with behavior-change details, removing issue citations per citation policy (prose is self-contained).
- Todo 142: Global sed replace of 3.12.x → 3.13.0 placeholder across all 20 documentation files.

Revision 2 incorporates feedback to reduce changelog-like issue citations. Only citations that add unique troubleshooting value are retained (#5103 for GCC workaround, #3970 for MSVC symbol export). "Known issues" section follows PR #5252's visual pattern (info admonition with bold-bullet format).

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

* 📡 Document integer type selection, type_name() invalid value, and std::optional get() fix

- number_handling.md: clarify that positive/negative integers select
  unsigned/signed storage based on the leading minus sign (todo 143).
- type_name.md: document the new "invalid" return value for corrupted
  JSON values (todo 145).
- get.md: note that get<std::optional<T>>() was unreachable in every
  configuration prior to 3.13.0 due to an internal macro-guard bug,
  unrelated to JSON_USE_IMPLICIT_CONVERSIONS's actual effect (todo 144).

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

---------

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

2026-07-09 17:24:19 +02:00

3.0 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::json
nlohmann::json_pointer
nlohmann::ordered_json
nlohmann::ordered_map
nlohmann::to_string
nlohmann::literals::json_literals::operator""_json
nlohmann::literals::json_literals::operator""_json_pointer

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.0 KiB Raw Blame History