deploy: d8d47be4a5

2026-10-05 14:10:31 +00:00 · 2026-10-04 15:46:44 +00:00
parent 19f538472d
commit c51ca275d0
374 changed files with 1998 additions and 551 deletions
@@ -212,6 +212,11 @@ Use the non-amalgamated version of the library. This option is `ON` by default.

 Treat the library headers like system headers (i.e., adding `SYSTEM` to the [`target_include_directories`](https://cmake.org/cmake/help/latest/command/target_include_directories.html) call) to check for this library by tools like Clang-Tidy. This option is `OFF` by default.

+### `JSON_StrictBinaryUTF8`
+
+Check string values and object keys for valid UTF-8 in the CBOR, UBJSON, BJData, and BSON writers, by defining the
+macro [`JSON_STRICT_BINARY_UTF8`](../api/macros/json_strict_binary_utf8.md). This option is `OFF` by default.
+
 ### `JSON_StrictNulHandling`

 Reject a `'\0'` (NUL) byte in the input instead of treating it as end of input, by defining the macro
@@ -186,6 +186,10 @@ Use the non-amalgamated version of the library. This option is `ON` by default.

 Treat the library headers like system headers (i.e., adding `SYSTEM` to the [`target_include_directories`](https://cmake.org/cmake/help/latest/command/target_include_directories.html) call) to check for this library by tools like Clang-Tidy. This option is `OFF` by default.

+### `JSON_StrictBinaryUTF8`
+
+Check string values and object keys for valid UTF-8 in the CBOR, UBJSON, BJData, and BSON writers, by defining the macro [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md). This option is `OFF` by default.
+
 ### `JSON_StrictNulHandling`

 Reject a `'\0'` (NUL) byte in the input instead of treating it as end of input, by defining the macro [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md). This option is `OFF` by default.
@@ -0,0 +1,149 @@
+# Compile times
+
+The library is header-only and makes heavy use of templates, so every translation unit that includes
+`<nlohmann/json.hpp>` pays for parsing the header and instantiating what it uses. This page lists the options to reduce
+that cost, ordered by how much they typically save.
+
+!!! info "Measurements"
+
+    The numbers below are medians of nine runs compiling a single translation unit with `-std=c++17 -c` against the
+    single-header version, with Apple clang and GCC 16 on macOS (Apple silicon). They show the order of magnitude to
+    expect; measure your own code before and after a change.
+
+## Include `json_fwd.hpp` in headers
+
+Header files that only need to *name* the `json` type — for function declarations, members held by pointer or
+reference, or friend declarations — can include `<nlohmann/json_fwd.hpp>` instead of `<nlohmann/json.hpp>`. It only
+forward-declares `basic_json`, `json`, `ordered_json`, `json_pointer`, and `adl_serializer`. The translation units that
+actually use the values then include `<nlohmann/json.hpp>`.
+
+```cpp title="person.hpp"
+#pragma once
+#include <nlohmann/json_fwd.hpp>
+
+struct person;
+void to_json(nlohmann::json& j, const person& p);
+void from_json(const nlohmann::json& j, person& p);
+```
+
+```cpp title="person.cpp"
+#include "person.hpp"
+#include <nlohmann/json.hpp>
+
+void to_json(nlohmann::json& j, const person& p) { /* ... */ }
+void from_json(const nlohmann::json& j, person& p) { /* ... */ }
+```
+
+| Compiler    | `json.hpp` (`-O0`) | `json_fwd.hpp` (`-O0`) | Change |
+|-------------|-------------------:|-----------------------:|-------:|
+| Apple clang |             704 ms |                 329 ms |   −53% |
+| GCC 16      |             779 ms |                 242 ms |   −69% |
+
+This is the most effective option, because it avoids the full header in every translation unit that includes
+*your* headers.
+
+## Opt out of the automatic user-defined string literals
+
+The user-defined string literals [`operator""_json`](../api/operator_literal_json.md) and
+[`operator""_json_pointer`](../api/operator_literal_json_pointer.md) are ordinary inline functions whose bodies call the
+parser. As `<nlohmann/json.hpp>` includes them by default, every translation unit instantiates the parser, even if it
+never parses anything itself.
+
+Define [`JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md) for the whole project and include
+`<nlohmann/json_literals.hpp>` instead of `<nlohmann/json.hpp>` in the files that use the literals (it includes
+`<nlohmann/json.hpp>` itself):
+
+```cmake
+target_compile_definitions(my_target PRIVATE JSON_NO_AUTOMATIC_UDLS)
+```
+
+```cpp
+#include <nlohmann/json_literals.hpp> // only where "..."_json is used; includes <nlohmann/json.hpp>
+```
+
+The saving applies to translation units that do not parse JSON, for example ones that define types and their
+conversions or only pass `json` values around:
+
+| Compiler    | Translation unit | Default (`-O0` / `-O2`) | `JSON_NO_AUTOMATIC_UDLS` (`-O0` / `-O2`) | Change      |
+|-------------|------------------|------------------------:|-----------------------------------------:|------------:|
+| Apple clang | model            |         776 ms / 846 ms |                          629 ms / 692 ms | −19% / −18% |
+| GCC 16      | model            |       1022 ms / 1120 ms |                          882 ms / 965 ms | −14% / −14% |
+| Apple clang | parsing          |       992 ms / 1815 ms |                        1006 ms / 1823 ms |   +1% / 0% |
+| GCC 16      | parsing          |      2018 ms / 3420 ms |                        1990 ms / 3454 ms |   −1% / +1% |
+
+Translation units that include only the header save up to a third. Translation units that parse anyway instantiate
+the parser regardless and see no difference.
+
+## Instantiate `basic_json` once
+
+Each translation unit instantiates the member functions of `nlohmann::json` it uses. An explicit instantiation
+declaration tells the compiler that the non-template members are instantiated elsewhere, so it can skip them:
+
+```cpp title="json_instance.hpp"
+#pragma once
+#include <nlohmann/json.hpp>
+
+extern template class nlohmann::basic_json<>;
+```
+
+```cpp title="json_instance.cpp"
+#include "json_instance.hpp"
+
+template class nlohmann::basic_json<>;
+```
+
+Include `json_instance.hpp` instead of `<nlohmann/json.hpp>` and compile and link `json_instance.cpp` once.
+
+| Compiler    | Translation unit    | Default (`-O0` / `-O2`) | `extern template` (`-O0` / `-O2`) | Change      |
+|-------------|---------------------|------------------------:|----------------------------------:|------------:|
+| Apple clang | parsing             |        992 ms / 1815 ms |                  953 ms / 1625 ms |  −4% / −10% |
+| GCC 16      | parsing             |       2018 ms / 3420 ms |                 1522 ms / 2728 ms | −25% / −20% |
+| Apple clang | `json_instance.cpp` |                       — |                 2166 ms / 4660 ms |           — |
+| GCC 16      | `json_instance.cpp` |                       — |                5085 ms / 10616 ms |           — |
+
+Notes:
+
+- The saving grows with the number of translation units that use `json`, while the instantiation translation unit is
+  compiled only once (and is rarely recompiled, as it does not depend on your code).
+- Member function templates (such as `get<T>()`, `parse(InputType&&)`, or `value(key, default)`) are not covered by
+  the explicit instantiation and are still instantiated where they are used.
+- The declaration covers exactly `nlohmann::json`. Add the same lines for `nlohmann::ordered_json`
+  (`nlohmann::basic_json<nlohmann::ordered_map>`) or your own `basic_json` specializations if you use them.
+
+## Use C++20 modules
+
+With a toolchain that supports named modules, `import nlohmann.json;` compiles the library once into a module and
+avoids parsing the header in every translation unit. See [Modules](../features/modules.md) for requirements and known
+issues. Module support is experimental and currently depends heavily on the compiler version.
+
+## Use precompiled headers
+
+Build systems can precompile `<nlohmann/json.hpp>` together with other stable headers, for example with CMake's
+[`target_precompile_headers`](https://cmake.org/cmake/help/latest/command/target_precompile_headers.html):
+
+```cmake
+target_precompile_headers(my_target PRIVATE <nlohmann/json.hpp>)
+```
+
+This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it
+combines well with the options above.
+
+## Options without effect on compile times
+
+Some configuration macros change what the library declares, but do not measurably change compile times:
+
+| Macro                                                                  | Apple clang, model (`-O0` / `-O2`) | GCC 16, model (`-O0` / `-O2`) |
+|------------------------------------------------------------------------|-----------------------------------:|------------------------------:|
+| default                                                                |                    776 ms / 846 ms |             1022 ms / 1120 ms |
+| [`JSON_NO_IO`](../api/macros/json_no_io.md)                            |                    764 ms / 836 ms |             1022 ms / 1117 ms |
+| [`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md)`=0`    |                    763 ms / 852 ms |             1019 ms / 1106 ms |
+
+`JSON_USE_GLOBAL_UDLS` only controls *where* the literals are declared; to avoid their cost, use
+`JSON_NO_AUTOMATIC_UDLS` instead.
+
+## See also
+
+- [`JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md) - do not include the user-defined string
+  literals automatically
+- [Modules](../features/modules.md) - C++20 module support
+- [Header only](index.md) - including the library
@@ -0,0 +1,132 @@
+# Compile times
+
+The library is header-only and makes heavy use of templates, so every translation unit that includes `<nlohmann/json.hpp>` pays for parsing the header and instantiating what it uses. This page lists the options to reduce that cost, ordered by how much they typically save.
+
+Measurements
+
+The numbers below are medians of nine runs compiling a single translation unit with `-std=c++17 -c` against the single-header version, with Apple clang and GCC 16 on macOS (Apple silicon). They show the order of magnitude to expect; measure your own code before and after a change.
+
+## Include `json_fwd.hpp` in headers
+
+Header files that only need to *name* the `json` type — for function declarations, members held by pointer or reference, or friend declarations — can include `<nlohmann/json_fwd.hpp>` instead of `<nlohmann/json.hpp>`. It only forward-declares `basic_json`, `json`, `ordered_json`, `json_pointer`, and `adl_serializer`. The translation units that actually use the values then include `<nlohmann/json.hpp>`.
+
+person.hpp
+
+```
+#pragma once
+#include <nlohmann/json_fwd.hpp>
+
+struct person;
+void to_json(nlohmann::json& j, const person& p);
+void from_json(const nlohmann::json& j, person& p);
+```
+
+person.cpp
+
+```
+#include "person.hpp"
+#include <nlohmann/json.hpp>
+
+void to_json(nlohmann::json& j, const person& p) { /* ... */ }
+void from_json(const nlohmann::json& j, person& p) { /* ... */ }
+```
+
+| Compiler    | `json.hpp` (`-O0`) | `json_fwd.hpp` (`-O0`) | Change |
+| ----------- | ------------------ | ---------------------- | ------ |
+| Apple clang | 704 ms             | 329 ms                 | −53%   |
+| GCC 16      | 779 ms             | 242 ms                 | −69%   |
+
+This is the most effective option, because it avoids the full header in every translation unit that includes *your* headers.
+
+## Opt out of the automatic user-defined string literals
+
+The user-defined string literals [`operator""_json`](https://json.nlohmann.me/api/operator_literal_json/index.md) and [`operator""_json_pointer`](https://json.nlohmann.me/api/operator_literal_json_pointer/index.md) are ordinary inline functions whose bodies call the parser. As `<nlohmann/json.hpp>` includes them by default, every translation unit instantiates the parser, even if it never parses anything itself.
+
+Define [`JSON_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md) for the whole project and include `<nlohmann/json_literals.hpp>` instead of `<nlohmann/json.hpp>` in the files that use the literals (it includes `<nlohmann/json.hpp>` itself):
+
+```
+target_compile_definitions(my_target PRIVATE JSON_NO_AUTOMATIC_UDLS)
+```
+
+```
+#include <nlohmann/json_literals.hpp> // only where "..."_json is used; includes <nlohmann/json.hpp>
+```
+
+The saving applies to translation units that do not parse JSON, for example ones that define types and their conversions or only pass `json` values around:
+
+| Compiler    | Translation unit | Default (`-O0` / `-O2`) | `JSON_NO_AUTOMATIC_UDLS` (`-O0` / `-O2`) | Change      |
+| ----------- | ---------------- | ----------------------- | ---------------------------------------- | ----------- |
+| Apple clang | model            | 776 ms / 846 ms         | 629 ms / 692 ms                          | −19% / −18% |
+| GCC 16      | model            | 1022 ms / 1120 ms       | 882 ms / 965 ms                          | −14% / −14% |
+| Apple clang | parsing          | 992 ms / 1815 ms        | 1006 ms / 1823 ms                        | +1% / 0%    |
+| GCC 16      | parsing          | 2018 ms / 3420 ms       | 1990 ms / 3454 ms                        | −1% / +1%   |
+
+Translation units that include only the header save up to a third. Translation units that parse anyway instantiate the parser regardless and see no difference.
+
+## Instantiate `basic_json` once
+
+Each translation unit instantiates the member functions of `nlohmann::json` it uses. An explicit instantiation declaration tells the compiler that the non-template members are instantiated elsewhere, so it can skip them:
+
+json_instance.hpp
+
+```
+#pragma once
+#include <nlohmann/json.hpp>
+
+extern template class nlohmann::basic_json<>;
+```
+
+json_instance.cpp
+
+```
+#include "json_instance.hpp"
+
+template class nlohmann::basic_json<>;
+```
+
+Include `json_instance.hpp` instead of `<nlohmann/json.hpp>` and compile and link `json_instance.cpp` once.
+
+| Compiler    | Translation unit    | Default (`-O0` / `-O2`) | `extern template` (`-O0` / `-O2`) | Change      |
+| ----------- | ------------------- | ----------------------- | --------------------------------- | ----------- |
+| Apple clang | parsing             | 992 ms / 1815 ms        | 953 ms / 1625 ms                  | −4% / −10%  |
+| GCC 16      | parsing             | 2018 ms / 3420 ms       | 1522 ms / 2728 ms                 | −25% / −20% |
+| Apple clang | `json_instance.cpp` | —                       | 2166 ms / 4660 ms                 | —           |
+| GCC 16      | `json_instance.cpp` | —                       | 5085 ms / 10616 ms                | —           |
+
+Notes:
+
+- The saving grows with the number of translation units that use `json`, while the instantiation translation unit is compiled only once (and is rarely recompiled, as it does not depend on your code).
+- Member function templates (such as `get<T>()`, `parse(InputType&&)`, or `value(key, default)`) are not covered by the explicit instantiation and are still instantiated where they are used.
+- The declaration covers exactly `nlohmann::json`. Add the same lines for `nlohmann::ordered_json` (`nlohmann::basic_json<nlohmann::ordered_map>`) or your own `basic_json` specializations if you use them.
+
+## Use C++20 modules
+
+With a toolchain that supports named modules, `import nlohmann.json;` compiles the library once into a module and avoids parsing the header in every translation unit. See [Modules](https://json.nlohmann.me/features/modules/index.md) for requirements and known issues. Module support is experimental and currently depends heavily on the compiler version.
+
+## Use precompiled headers
+
+Build systems can precompile `<nlohmann/json.hpp>` together with other stable headers, for example with CMake's [`target_precompile_headers`](https://cmake.org/cmake/help/latest/command/target_precompile_headers.html):
+
+```
+target_precompile_headers(my_target PRIVATE <nlohmann/json.hpp>)
+```
+
+This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it combines well with the options above.
+
+## Options without effect on compile times
+
+Some configuration macros change what the library declares, but do not measurably change compile times:
+
+| Macro                                                                                           | Apple clang, model (`-O0` / `-O2`) | GCC 16, model (`-O0` / `-O2`) |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------- |
+| default                                                                                         | 776 ms / 846 ms                    | 1022 ms / 1120 ms             |
+| [`JSON_NO_IO`](https://json.nlohmann.me/api/macros/json_no_io/index.md)                         | 764 ms / 836 ms                    | 1022 ms / 1117 ms             |
+| [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md)`=0` | 763 ms / 852 ms                    | 1019 ms / 1106 ms             |
+
+`JSON_USE_GLOBAL_UDLS` only controls *where* the literals are declared; to avoid their cost, use `JSON_NO_AUTOMATIC_UDLS` instead.
+
+## See also
+
+- [`JSON_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md) - do not include the user-defined string literals automatically
+- [Modules](https://json.nlohmann.me/features/modules/index.md) - C++20 module support
+- [Header only](https://json.nlohmann.me/integration/index.md) - including the library
@@ -35,4 +35,4 @@ using json = nlohmann::json;

 to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and Clang).

-You can further use file [`single_include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp) for forward declarations, and file [`single_include/nlohmann/json_literals.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_literals.hpp) for the user-defined string literals if you define [`JSON_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md).
+You can further use file [`single_include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp) for forward declarations (see [Compile times](https://json.nlohmann.me/integration/compile_times/index.md)), and file [`single_include/nlohmann/json_literals.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_literals.hpp) for the user-defined string literals if you define [`JSON_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md).
@@ -2,11 +2,14 @@

 This page collects some guidelines on how to future-proof your code for future versions of this library. For how to
 add the library to your project in the first place, see [Integration](index.md), [CMake](cmake.md), or
-[Package Managers](package_managers.md).
+[Package Managers](package_managers.md). The [roadmap](../community/roadmap.md#version-40) lists what will change in
+version 4.0, including the macros that let you try its behavior with a 3.x release; this page describes how to adjust
+your code.

 ## Replace deprecated functions

-The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). All
+The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0), see the
+[roadmap](../community/roadmap.md#removal-of-deprecated-functions) for an overview. All
 deprecations are annotated with
 [`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which
 function to use instead.
@@ -1,10 +1,10 @@
 # Migration Guide

-This page collects some guidelines on how to future-proof your code for future versions of this library. For how to add the library to your project in the first place, see [Integration](https://json.nlohmann.me/integration/index.md), [CMake](https://json.nlohmann.me/integration/cmake/index.md), or [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md).
+This page collects some guidelines on how to future-proof your code for future versions of this library. For how to add the library to your project in the first place, see [Integration](https://json.nlohmann.me/integration/index.md), [CMake](https://json.nlohmann.me/integration/cmake/index.md), or [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md). The [roadmap](https://json.nlohmann.me/community/roadmap/#version-40) lists what will change in version 4.0, including the macros that let you try its behavior with a 3.x release; this page describes how to adjust your code.

 ## Replace deprecated functions

-The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). All deprecations are annotated with [`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which function to use instead.
+The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0), see the [roadmap](https://json.nlohmann.me/community/roadmap/#removal-of-deprecated-functions) for an overview. All deprecations are annotated with [`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which function to use instead.

 ### Parsing