Document options to reduce compile times

Add an integration page that collects the ways to reduce compile times
with measurements: json_fwd.hpp in headers, JSON_NO_AUTOMATIC_UDLS,
explicit instantiation with extern template, modules, and precompiled
headers, and notes that JSON_NO_IO and JSON_USE_GLOBAL_UDLS have no
measurable effect.

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

.github/workflows/check_amalgamation.yml

@@ -67,6 +67,7 @@ jobs:
 
           python3 $TOOL_DIR/amalgamate.py -c $TOOL_DIR/config_json.json -s .
           python3 $TOOL_DIR/amalgamate.py -c $TOOL_DIR/config_json_fwd.json -s .
+          cp include/nlohmann/json_literals.hpp $INCLUDE_DIR/json_literals.hpp
 
           # the header list of the Bazel "json" target must match the files in include/
           cmake -P cmake/scripts/gen_bazel_build_file.cmake

BUILD.bazel

@@ -65,6 +65,7 @@ cc_library(
         "include/nlohmann/detail/value_t.hpp",
         "include/nlohmann/json.hpp",
         "include/nlohmann/json_fwd.hpp",
+        "include/nlohmann/json_literals.hpp",
         "include/nlohmann/ordered_map.hpp",
         "include/nlohmann/thirdparty/hedley/hedley.hpp",
         "include/nlohmann/thirdparty/hedley/hedley_undef.hpp",

Makefile

@@ -21,6 +21,8 @@ TESTS_SRCS=$(shell find tests -type f \( -name '*.hpp' -o -name '*.cpp' -o -name
 # the single headers (amalgamated from the source files)
 AMALGAMATED_FILE=single_include/nlohmann/json.hpp
 AMALGAMATED_FWD_FILE=single_include/nlohmann/json_fwd.hpp
+# json_literals.hpp only includes <nlohmann/json.hpp>, so it is copied verbatim
+AMALGAMATED_LITERALS_FILE=single_include/nlohmann/json_literals.hpp
 
 
 ##########################################################################
@@ -29,7 +31,7 @@ AMALGAMATED_FWD_FILE=single_include/nlohmann/json_fwd.hpp
 
 # main target
 all:
-	@echo "amalgamate - amalgamate files single_include/nlohmann/json{,_fwd}.hpp from the include/nlohmann sources"
+	@echo "amalgamate - amalgamate files single_include/nlohmann/json{,_fwd,_literals}.hpp from the include/nlohmann sources"
 	@echo "BUILD.bazel - regenerate the Bazel BUILD file from the include/nlohmann sources"
 	@echo "ChangeLog.md - generate ChangeLog file"
 	@echo "check-amalgamation - check whether sources have been amalgamated and BUILD.bazel is up to date"
@@ -154,14 +156,14 @@ install_astyle:
 
 # call the Artistic Style pretty printer on all source files
 pretty: install_astyle
-	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) docs/mkdocs/docs/examples/*.cpp
+	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) docs/mkdocs/docs/examples/*.cpp
 
 # call the Clang-Format on all source files
 pretty_format:
 	for FILE in $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) docs/mkdocs/docs/examples/*.cpp; do echo $$FILE; clang-format -i $$FILE; done
 
 # create single header files and pretty print
-amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE)
+amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE)
 	$(MAKE) pretty
 
 # call the amalgamation tool for json.hpp
@@ -172,16 +174,23 @@ $(AMALGAMATED_FILE): $(SRCS)
 $(AMALGAMATED_FWD_FILE): $(SRCS)
 	tools/amalgamate/amalgamate.py -c tools/amalgamate/config_json_fwd.json -s . --verbose=yes
 
+# copy json_literals.hpp
+$(AMALGAMATED_LITERALS_FILE): include/nlohmann/json_literals.hpp
+	cp include/nlohmann/json_literals.hpp $(AMALGAMATED_LITERALS_FILE)
+
 # check if file single_include/nlohmann/json.hpp has been amalgamated from the nlohmann sources
 # Note: this target is called by Travis
 check-amalgamation:
 	@mv $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~
 	@mv $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~
+	@mv $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_LITERALS_FILE)~
 	@$(MAKE) amalgamate
 	@diff $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_FILE)~ $(AMALGAMATED_FILE) ; false)
 	@diff $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_FWD_FILE)~ $(AMALGAMATED_FWD_FILE) ; false)
+	@diff $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_LITERALS_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_LITERALS_FILE)~ $(AMALGAMATED_LITERALS_FILE) ; false)
 	@mv $(AMALGAMATED_FILE)~ $(AMALGAMATED_FILE)
 	@mv $(AMALGAMATED_FWD_FILE)~ $(AMALGAMATED_FWD_FILE)
+	@mv $(AMALGAMATED_LITERALS_FILE)~ $(AMALGAMATED_LITERALS_FILE)
 	@mv BUILD.bazel BUILD.bazel~
 	@$(MAKE) BUILD.bazel
 	@diff BUILD.bazel BUILD.bazel~ || (echo "===================================================================\n  BUILD.bazel is out of date! Please run 'make BUILD.bazel'.\n===================================================================" ; mv BUILD.bazel~ BUILD.bazel ; false)
@@ -222,7 +231,7 @@ json.tar.xz:
 # We use `-X` to make the resulting ZIP file reproducible, see
 # <https://content.pivotal.io/blog/barriers-to-deterministic-reproducible-zip-files>.
 include.zip: BUILD.bazel
-	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
+	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
 
 # Create the files for a release and add signatures and hashes.
 release: include.zip json.tar.xz
@@ -231,10 +240,12 @@ release: include.zip json.tar.xz
 	gpg --armor --detach-sig include.zip
 	gpg --armor --detach-sig $(AMALGAMATED_FILE)
 	gpg --armor --detach-sig $(AMALGAMATED_FWD_FILE)
+	gpg --armor --detach-sig $(AMALGAMATED_LITERALS_FILE)
 	gpg --armor --detach-sig json.tar.xz
 	cp $(AMALGAMATED_FILE) release_files
 	cp $(AMALGAMATED_FWD_FILE) release_files
-	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
+	cp $(AMALGAMATED_LITERALS_FILE) release_files
+	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc $(AMALGAMATED_LITERALS_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
 	cd release_files ; shasum -a 256 json.hpp include.zip json.tar.xz > hashes.txt
 
 

cmake/ci.cmake

@@ -373,9 +373,10 @@ file(GLOB_RECURSE INDENT_FILES
 set(include_dir ${PROJECT_SOURCE_DIR}/single_include/nlohmann)
 set(tool_dir ${PROJECT_SOURCE_DIR}/tools/amalgamate)
 add_custom_target(ci_test_amalgamation
-    COMMAND rm -fr ${include_dir}/json.hpp~ ${include_dir}/json_fwd.hpp~
+    COMMAND rm -fr ${include_dir}/json.hpp~ ${include_dir}/json_fwd.hpp~ ${include_dir}/json_literals.hpp~
     COMMAND cp ${include_dir}/json.hpp ${include_dir}/json.hpp~
     COMMAND cp ${include_dir}/json_fwd.hpp ${include_dir}/json_fwd.hpp~
+    COMMAND cp ${include_dir}/json_literals.hpp ${include_dir}/json_literals.hpp~
 
     COMMAND ${Python3_EXECUTABLE} -mvenv venv_astyle
     COMMAND venv_astyle/bin/pip3 --quiet install -r ${CMAKE_SOURCE_DIR}/tools/astyle/requirements.txt
@@ -383,10 +384,12 @@ add_custom_target(ci_test_amalgamation
 
     COMMAND ${Python3_EXECUTABLE} ${tool_dir}/amalgamate.py -c ${tool_dir}/config_json.json -s .
     COMMAND ${Python3_EXECUTABLE} ${tool_dir}/amalgamate.py -c ${tool_dir}/config_json_fwd.json -s .
+    COMMAND cp ${PROJECT_SOURCE_DIR}/include/nlohmann/json_literals.hpp ${include_dir}/json_literals.hpp
     COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=none ${include_dir}/json.hpp ${include_dir}/json_fwd.hpp
 
     COMMAND diff ${include_dir}/json.hpp~ ${include_dir}/json.hpp
     COMMAND diff ${include_dir}/json_fwd.hpp~ ${include_dir}/json_fwd.hpp
+    COMMAND diff ${include_dir}/json_literals.hpp~ ${include_dir}/json_literals.hpp
 
     COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=orig ${INDENT_FILES}
     COMMAND for FILE in `find . -name '*.orig'`\; do false \; done

docs/mkdocs/docs/api/macros/index.md

@@ -28,6 +28,7 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support
 - [**JSON_HAS_STD_FORMAT**](json_has_std_format.md) - control `std::format`/`std::formatter` support
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
+- [**JSON_NO_AUTOMATIC_UDLS**](json_no_automatic_udls.md) - do not include the user-defined string literals (UDLs) automatically
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_NO_THREAD_LOCAL**](json_no_thread_local.md) - switch off the use of `thread_local` storage
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers

docs/mkdocs/docs/api/macros/json_no_automatic_udls.md

@@ -0,0 +1,69 @@
+# JSON_NO_AUTOMATIC_UDLS
+
+```cpp
+#define JSON_NO_AUTOMATIC_UDLS
+```
+
+When defined, `<nlohmann/json.hpp>` does not include `<nlohmann/json_literals.hpp>`, so the user-defined string
+literals [`operator""_json`](../operator_literal_json.md) and
+[`operator""_json_pointer`](../operator_literal_json_pointer.md) are not declared. Include
+`<nlohmann/json_literals.hpp>` in the files that use them.
+
+The literals are ordinary inline functions whose bodies call the parser, so every translation unit that includes them
+instantiates the parser — even if it never parses anything itself. Defining `JSON_NO_AUTOMATIC_UDLS` for a whole project
+avoids this cost in translation units that do not parse (e.g., ones that only define types and conversions or pass
+`json` values around) and reduces their compile time.
+
+## Default definition
+
+By default, `#!cpp JSON_NO_AUTOMATIC_UDLS` is not defined, and `<nlohmann/json.hpp>` includes
+`<nlohmann/json_literals.hpp>`.
+
+```cpp
+#undef JSON_NO_AUTOMATIC_UDLS
+```
+
+## Notes
+
+!!! info "Header `<nlohmann/json_literals.hpp>`"
+
+    The header includes `<nlohmann/json.hpp>` itself and places the literals according to
+    [`JSON_USE_GLOBAL_UDLS`](json_use_global_udls.md). It is part of the multi-header sources (`include/nlohmann`)
+    and of the single-header sources (`single_include/nlohmann`), next to `json.hpp`.
+
+!!! info "C++ modules"
+
+    The `nlohmann.json` [module](../../features/modules.md) always exports the literals, regardless of this macro.
+
+## Examples
+
+??? example
+
+    The code below includes the library without the literals and adds them in a single translation unit.
+
+    ```cpp
+    // compiled with -DJSON_NO_AUTOMATIC_UDLS for the whole project
+    #include <nlohmann/json.hpp>
+
+    // this file uses the literals, so it includes them explicitly
+    #include <nlohmann/json_literals.hpp>
+
+    int main()
+    {
+        auto j = R"({"foo": 42})"_json;
+        return j.at("/foo"_json_pointer) == 42 ? 0 : 1;
+    }
+    ```
+
+    Without the include of `<nlohmann/json_literals.hpp>`, the code would fail to compile.
+
+## See also
+
+- [`operator""_json`](../operator_literal_json.md)
+- [`operator""_json_pointer`](../operator_literal_json_pointer.md)
+- [`JSON_USE_GLOBAL_UDLS`](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
+- [Compile times](../../integration/compile_times.md) - options to reduce compile times
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/macros/json_use_global_udls.md

@@ -15,7 +15,7 @@ The default value is `1`.
 #define JSON_USE_GLOBAL_UDLS 1
 ```
 
-When the macro is not defined, the library will define it to its default value.
+When the macro is not defined, the library behaves as if it were defined to its default value.
 
 ## Notes
 
@@ -32,6 +32,11 @@ When the macro is not defined, the library will define it to its default value.
     [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`ON` by default) which defines
     `JSON_USE_GLOBAL_UDLS` accordingly.
 
+!!! info "Leaving out the literals"
+
+    If [`JSON_NO_AUTOMATIC_UDLS`](json_no_automatic_udls.md) is defined, the literals are only declared where
+    `<nlohmann/json_literals.hpp>` is included; this macro then applies to that header.
+
 ## Examples
 
 ??? example "Example 1: Default behavior"
@@ -92,6 +97,7 @@ When the macro is not defined, the library will define it to its default value.
 
 - [`operator""_json`](../operator_literal_json.md)
 - [`operator""_json_pointer`](../operator_literal_json_pointer.md)
+- [`JSON_NO_AUTOMATIC_UDLS`](json_no_automatic_udls.md) - do not include the user-defined string literals automatically
 - [:simple-cmake: JSON_GlobalUDLs](../../integration/cmake.md#json_globaludls) - CMake option to control the macro
 
 ## Version history

docs/mkdocs/docs/api/operator_literal_json.md

@@ -18,7 +18,9 @@ using namespace nlohmann;
 ```
 
 This is suggested to ease migration to the next major version release of the library. See
-[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
+[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. The operator is declared in header
+`<nlohmann/json_literals.hpp>`, which `<nlohmann/json.hpp>` includes unless
+[`JSON_NO_AUTOMATIC_UDLS`](macros/json_no_automatic_udls.md) is defined.
 
 ## Parameters
 
@@ -59,6 +61,8 @@ Linear.
 ## See also
 
 - [Creating JSON values](../features/creating_values.md) - the article on creating JSON values
+- [JSON_NO_AUTOMATIC_UDLS](macros/json_no_automatic_udls.md) - do not include the user-defined string literals
+  automatically
 
 ## Version history
 

docs/mkdocs/docs/api/operator_literal_json_pointer.md

@@ -17,7 +17,9 @@ using namespace nlohmann::literals::json_literals;
 using namespace nlohmann;
 ```
 This is suggested to ease migration to the next major version release of the library. See
-[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
+[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. The operator is declared in header
+`<nlohmann/json_literals.hpp>`, which `<nlohmann/json.hpp>` includes unless
+[`JSON_NO_AUTOMATIC_UDLS`](macros/json_no_automatic_udls.md) is defined.
 
 ## Parameters
 
@@ -58,6 +60,8 @@ Linear.
 ## See also
 
 - [json_pointer](json_pointer/index.md) - type to represent JSON Pointers
+- [JSON_NO_AUTOMATIC_UDLS](macros/json_no_automatic_udls.md) - do not include the user-defined string literals
+  automatically
 
 ## Version history
 

docs/mkdocs/docs/features/macros.md

@@ -83,6 +83,15 @@ When defined, default parse and serialize functions for enums are excluded and h
 
 See [full documentation of `JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).
 
+## `JSON_NO_AUTOMATIC_UDLS`
+
+When defined, `<nlohmann/json.hpp>` does not include `<nlohmann/json_literals.hpp>` with the user-defined string literals
+`operator""_json` and `operator""_json_pointer`. This reduces the compile time of translation units that do not use
+them, because the literals instantiate the parser in every translation unit that includes them. Include
+`<nlohmann/json_literals.hpp>` where the literals are needed.
+
+See [full documentation of `JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md).
+
 ## `JSON_NO_IO`
 
 When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions

docs/mkdocs/docs/features/modules.md

@@ -40,6 +40,9 @@ Only the following symbols are exported from `nlohmann.json`:
 - `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`](../api/macros/json_no_automatic_udls.md) is defined when building it.
+
 Additionally, the following `nlohmann::detail` symbols are exported, solely to work around an MSVC compilation issue
 ([#3970](https://github.com/nlohmann/json/issues/3970)). They are implementation details, not part of the public API,
 and should not be used directly:

docs/mkdocs/docs/integration/compile_times.md

@@ -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>` only in the files that use the literals:
+
+```cmake
+target_compile_definitions(my_target PRIVATE JSON_NO_AUTOMATIC_UDLS)
+```
+
+```cpp
+#include <nlohmann/json.hpp>
+#include <nlohmann/json_literals.hpp> // only where "..."_json is used
+```
+
+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

docs/mkdocs/docs/integration/index.md

@@ -15,4 +15,7 @@ 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.
+for forward declarations (see [Compile times](compile_times.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`](../api/macros/json_no_automatic_udls.md).

docs/mkdocs/mkdocs.yml

@@ -106,6 +106,7 @@ nav:
       - integration/cmake.md
       - integration/package_managers.md
       - integration/pkg-config.md
+      - integration/compile_times.md
   - API Documentation:
       - basic_json:
           - 'Overview': api/basic_json/index.md
@@ -293,6 +294,7 @@ nav:
           - 'JSON_HAS_STATIC_RTTI': api/macros/json_has_static_rtti.md
           - 'JSON_HAS_STD_FORMAT': api/macros/json_has_std_format.md
           - 'JSON_HAS_THREE_WAY_COMPARISON': api/macros/json_has_three_way_comparison.md
+          - 'JSON_NO_AUTOMATIC_UDLS': api/macros/json_no_automatic_udls.md
           - 'JSON_NOEXCEPTION': api/macros/json_noexception.md
           - 'JSON_NO_IO': api/macros/json_no_io.md
           - 'JSON_NO_THREAD_LOCAL': api/macros/json_no_thread_local.md

include/nlohmann/detail/input/binary_reader.hpp

@@ -3344,8 +3344,8 @@ class binary_reader
         return enter_object(detail::unknown_size());
     }
 
-    // Note, UBJSON has no binary type of its own; BJData, which shares this
-    // reader, decodes optimized 'B' arrays as binary in get_ubjson_array().
+    // Note, no reader for UBJSON binary types is implemented because they do
+    // not exist
 
     bool get_ubjson_high_precision_number()
     {
@@ -4052,7 +4052,7 @@ class binary_reader
 #endif
     }
 
-    /*!
+    /*
     @brief read a number from the input
 
     @tparam NumberType the type of the number
@@ -4062,10 +4062,10 @@ class binary_reader
     @return whether conversion completed
 
     @note This function needs to respect the system's endianness, because
-          bytes in CBOR, MessagePack, UBJSON, and BON8 are stored in network
-          order (big endian) and therefore need reordering on little endian
-          systems. On the other hand, BSON and BJData use little endian and
-          should reorder on big endian systems.
+          bytes in CBOR, MessagePack, and UBJSON are stored in network order
+          (big endian) and therefore need reordering on little endian systems.
+          On the other hand, BSON and BJData use little endian and should reorder
+          on big endian systems.
     */
     template<typename NumberType, bool InputIsLittleEndian = false>
     bool get_number(const input_format_t format, NumberType& result)

include/nlohmann/detail/input/input_adapters.hpp

@@ -8,11 +8,12 @@
 
 #pragma once
 
-#include <algorithm> // min
 #include <array> // array
 #include <cstddef> // size_t
 #include <cstring> // strlen
 #include <iterator> // begin, end, iterator_traits, random_access_iterator_tag, distance, next
+#include <memory> // shared_ptr, make_shared, addressof
+#include <numeric> // accumulate
 #include <streambuf> // streambuf
 #include <string> // string, char_traits
 #include <type_traits> // enable_if, is_base_of, is_pointer, is_integral, remove_pointer
@@ -81,9 +82,8 @@ class file_input_adapter
 };
 
 /*!
-Input adapter for a (caching) istream. Does not skip a UTF Byte Order Mark
-itself; that is done by the lexer's skip_bom(). Does not support changing
-the underlying std::streambuf
+Input adapter for a (caching) istream. Ignores a UFT Byte Order Mark at
+beginning of input. Does not support changing the underlying std::streambuf
 in mid-input. Maintains underlying std::istream and std::streambuf to support
 subsequent use of standard std::istream operations to process any input
 characters following those used in parsing the JSON input.  Clears the
@@ -862,9 +862,9 @@ auto input_adapter(T (&array)[N]) -> decltype(input_adapter(array, array + N)) /
     return input_adapter(array, array + N);
 }
 
-// This class only handles inputs that construct a contiguous_bytes_input_adapter
-// (e.g. span_input_adapter). It's required so that expressions like {ptr, len}
-// can be implicitly cast to the correct adapter.
+// This class only handles inputs of input_buffer_adapter type.
+// It's required so that expressions like {ptr, len} can be implicitly cast
+// to the correct adapter.
 class span_input_adapter
 {
   public:

include/nlohmann/detail/input/json_sax.hpp

@@ -10,7 +10,6 @@
 
 #include <algorithm> // find_if, min
 #include <cstddef>
-#include <limits> // numeric_limits
 #include <string> // string
 #include <type_traits> // enable_if_t
 #include <utility> // move, pair
@@ -176,88 +175,6 @@ template<typename ArrayType>
 inline void reserve_array(ArrayType& /*arr*/, std::size_t /*len*/, priority_tag<0> /*unused*/)
 {}
 
-#if JSON_DIAGNOSTIC_POSITIONS
-/*!
-@brief set the diagnostic positions of a value the DOM SAX parsers just stored
-
-Shared by json_sax_dom_parser and json_sax_dom_callback_parser. basic_json
-befriends this struct, as the position members are private.
-*/
-struct diagnostic_positions
-{
-    /*!
-    @param[in,out] v  the value that was just parsed
-    @param[in] lexer  the lexer that read it, or nullptr to leave @a v alone
-    */
-    template<typename BasicJsonType, typename LexerType>
-    static void set_from_lexer(BasicJsonType& v, LexerType* lexer)
-    {
-        if (lexer)
-        {
-            // Lexer has read past the current field value, so set the end position to the current position.
-            // The start position will be set below based on the length of the string representation
-            // of the value.
-            v.end_position = lexer->get_position();
-
-            switch (v.type())
-            {
-                case value_t::boolean:
-                {
-                    // 4 and 5 are the string length of "true" and "false"
-                    v.start_position = v.end_position - (v.m_data.m_value.boolean ? 4 : 5);
-                    break;
-                }
-
-                case value_t::null:
-                {
-                    // 4 is the string length of "null"
-                    v.start_position = v.end_position - 4;
-                    break;
-                }
-
-                case value_t::string:
-                {
-                    // escape sequences make the token longer than the value it
-                    // parses to, so the start position cannot be derived from
-                    // the value; use the offset the lexer recorded instead
-                    v.start_position = lexer->get_token_start_position();
-                    break;
-                }
-
-                case value_t::discarded:
-                {
-                    // an object or array the callback of
-                    // json_sax_dom_callback_parser rejected has no position
-                    v.end_position = std::string::npos;
-                    v.start_position = v.end_position;
-                    break;
-                }
-
-                case value_t::binary:
-                case value_t::number_integer:
-                case value_t::number_unsigned:
-                case value_t::number_float:
-                {
-                    v.start_position = v.end_position - lexer->get_string().size();
-                    break;
-                }
-
-                case value_t::object:
-                case value_t::array:
-                {
-                    // object and array are handled in start_object() and start_array() handlers
-                    // skip setting the values here.
-                    break;
-                }
-                default: // LCOV_EXCL_LINE
-                    // Handle all possible types discretely, default handler should never be reached.
-                    JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert) LCOV_EXCL_LINE
-            }
-        }
-    }
-};
-#endif
-
 /*!
 @brief SAX implementation to create a JSON value from SAX events
 
@@ -459,6 +376,76 @@ class json_sax_dom_parser
 
   private:
 
+#if JSON_DIAGNOSTIC_POSITIONS
+    void handle_diagnostic_positions_for_json_value(BasicJsonType& v)
+    {
+        if (m_lexer_ref)
+        {
+            // Lexer has read past the current field value, so set the end position to the current position.
+            // The start position will be set below based on the length of the string representation
+            // of the value.
+            v.end_position = m_lexer_ref->get_position();
+
+            switch (v.type())
+            {
+                case value_t::boolean:
+                {
+                    // 4 and 5 are the string length of "true" and "false"
+                    v.start_position = v.end_position - (v.m_data.m_value.boolean ? 4 : 5);
+                    break;
+                }
+
+                case value_t::null:
+                {
+                    // 4 is the string length of "null"
+                    v.start_position = v.end_position - 4;
+                    break;
+                }
+
+                case value_t::string:
+                {
+                    // escape sequences make the token longer than the value it
+                    // parses to, so the start position cannot be derived from
+                    // the value; use the offset the lexer recorded instead
+                    v.start_position = m_lexer_ref->get_token_start_position();
+                    break;
+                }
+
+                // As we handle the start and end positions for values created during parsing,
+                // we do not expect the following value type to be called. Regardless, set the positions
+                // in case this is created manually or through a different constructor. Exclude from lcov
+                // since the exact condition of this switch is esoteric.
+                // LCOV_EXCL_START
+                case value_t::discarded:
+                {
+                    v.end_position = std::string::npos;
+                    v.start_position = v.end_position;
+                    break;
+                }
+                // LCOV_EXCL_STOP
+                case value_t::binary:
+                case value_t::number_integer:
+                case value_t::number_unsigned:
+                case value_t::number_float:
+                {
+                    v.start_position = v.end_position - m_lexer_ref->get_string().size();
+                    break;
+                }
+                case value_t::object:
+                case value_t::array:
+                {
+                    // object and array are handled in start_object() and start_array() handlers
+                    // skip setting the values here.
+                    break;
+                }
+                default: // LCOV_EXCL_LINE
+                    // Handle all possible types discretely, default handler should never be reached.
+                    JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert,-warnings-as-errors) LCOV_EXCL_LINE
+            }
+        }
+    }
+#endif
+
     /*!
     @invariant If the ref stack is empty, then the passed value will be the new
                root.
@@ -474,7 +461,7 @@ class json_sax_dom_parser
             root = BasicJsonType(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-            diagnostic_positions::set_from_lexer(root, m_lexer_ref);
+            handle_diagnostic_positions_for_json_value(root);
 #endif
 
             return &root;
@@ -487,7 +474,7 @@ class json_sax_dom_parser
             ref_stack.back()->m_data.m_value.array->emplace_back(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-            diagnostic_positions::set_from_lexer(ref_stack.back()->m_data.m_value.array->back(), m_lexer_ref);
+            handle_diagnostic_positions_for_json_value(ref_stack.back()->m_data.m_value.array->back());
 #endif
 
             return &(ref_stack.back()->m_data.m_value.array->back());
@@ -498,7 +485,7 @@ class json_sax_dom_parser
         *object_element = BasicJsonType(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-        diagnostic_positions::set_from_lexer(*object_element, m_lexer_ref);
+        handle_diagnostic_positions_for_json_value(*object_element);
 #endif
 
         return object_element;
@@ -675,7 +662,7 @@ class json_sax_dom_callback_parser
 
 #if JSON_DIAGNOSTIC_POSITIONS
                     // Set start/end positions for discarded object.
-                    diagnostic_positions::set_from_lexer(*ref_stack.back(), m_lexer_ref);
+                    handle_diagnostic_positions_for_json_value(*ref_stack.back());
 #endif
                 }
             }
@@ -791,7 +778,7 @@ class json_sax_dom_callback_parser
 
 #if JSON_DIAGNOSTIC_POSITIONS
                     // Set start/end positions for discarded array.
-                    diagnostic_positions::set_from_lexer(*ref_stack.back(), m_lexer_ref);
+                    handle_diagnostic_positions_for_json_value(*ref_stack.back());
 #endif
                 }
             }
@@ -844,6 +831,72 @@ class json_sax_dom_callback_parser
 
   private:
 
+#if JSON_DIAGNOSTIC_POSITIONS
+    void handle_diagnostic_positions_for_json_value(BasicJsonType& v)
+    {
+        if (m_lexer_ref)
+        {
+            // Lexer has read past the current field value, so set the end position to the current position.
+            // The start position will be set below based on the length of the string representation
+            // of the value.
+            v.end_position = m_lexer_ref->get_position();
+
+            switch (v.type())
+            {
+                case value_t::boolean:
+                {
+                    // 4 and 5 are the string length of "true" and "false"
+                    v.start_position = v.end_position - (v.m_data.m_value.boolean ? 4 : 5);
+                    break;
+                }
+
+                case value_t::null:
+                {
+                    // 4 is the string length of "null"
+                    v.start_position = v.end_position - 4;
+                    break;
+                }
+
+                case value_t::string:
+                {
+                    // escape sequences make the token longer than the value it
+                    // parses to, so the start position cannot be derived from
+                    // the value; use the offset the lexer recorded instead
+                    v.start_position = m_lexer_ref->get_token_start_position();
+                    break;
+                }
+
+                case value_t::discarded:
+                {
+                    v.end_position = std::string::npos;
+                    v.start_position = v.end_position;
+                    break;
+                }
+
+                case value_t::binary:
+                case value_t::number_integer:
+                case value_t::number_unsigned:
+                case value_t::number_float:
+                {
+                    v.start_position = v.end_position - m_lexer_ref->get_string().size();
+                    break;
+                }
+
+                case value_t::object:
+                case value_t::array:
+                {
+                    // object and array are handled in start_object() and start_array() handlers
+                    // skip setting the values here.
+                    break;
+                }
+                default: // LCOV_EXCL_LINE
+                    // Handle all possible types discretely, default handler should never be reached.
+                    JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert,-warnings-as-errors) LCOV_EXCL_LINE
+            }
+        }
+    }
+#endif
+
     /// if there is a pending duplicate-key stash entry for this exact slot,
     /// remove it from the stash; if restore_value is true, the stashed
     /// previous value is moved back into the slot first (use this when the
@@ -965,7 +1018,7 @@ class json_sax_dom_callback_parser
         auto value = BasicJsonType(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-        diagnostic_positions::set_from_lexer(value, m_lexer_ref);
+        handle_diagnostic_positions_for_json_value(value);
 #endif
 
         // check callback

include/nlohmann/detail/input/lexer.hpp

@@ -1494,30 +1494,45 @@ scan_number_done:
     */
     token_type convert_number(token_type number_type, std::size_t mantissa_end)
     {
-        // accept() only needs to know whether the input is valid, so it sets
-        // discard_number_values (see json.hpp), and an integer token whose
-        // digit count shows that it fits is reported without calling
-        // convert_integer(). A number with up to 18 digits always fits into
-        // both std::uint64_t and std::int64_t (18 nines is about 1e18, below
-        // INT64_MAX, which is about 9.2e18). Longer tokens take the exact path
-        // below, including the fallback to floating point when the value does
-        // not fit.
+        // If the caller does not need the converted value (only whether the
+        // input is syntactically valid; see json_sax_acceptor/accept()), an
+        // unsigned/integer token can be reported without calling
+        // strtoull()/strtoll() at all, *provided* we can already tell from
+        // the digit count alone that the conversion cannot overflow 64 bits.
+        // Such tokens are always finite and are accepted unconditionally by
+        // the parser regardless of their actual value (parser::sax_parse_internal()
+        // never checks finiteness for value_unsigned/value_integer), so the
+        // classification below is all that is needed.
         //
-        // With a narrower number_unsigned_t/number_integer_t (e.g.
-        // std::uint32_t), the exact path would reclassify some of these tokens
-        // as (finite) floats, while this check reports integers. That does not
-        // change the result of accept(): it always parses through
-        // json_sax_acceptor, whose number callbacks discard their argument and
-        // return true, and the parser rejects neither integers nor finite
-        // floats. value_unsigned/value_integer are left unset here, so a caller
-        // that reads the converted value must not set discard_number_values.
+        // A decimal number with up to 18 digits is always representable in
+        // both std::uint64_t and std::int64_t (18 nines is ~1e18, well below
+        // both UINT64_MAX ~1.8e19 and INT64_MAX ~9.2e18), so strtoull()/strtoll()
+        // could not have set errno to ERANGE for it. Numbers with more digits
+        // (rare in practice) fall through to the exact code below, unchanged,
+        // so their handling -- including reclassification to value_float when
+        // the value overflows 64 bits, and rejection when it is not even
+        // finite as a double -- is bit-for-bit identical to before this
+        // optimization.
         //
-        // On contiguous input, scan_number_bulk_contiguous() converts integer
-        // tokens itself and does not pass them to this function, unless
-        // JSON_DIAGNOSTIC_POSITIONS is enabled. This check is therefore only
-        // reached for input without bulk access (e.g. streams), with
-        // JSON_DIAGNOSTIC_POSITIONS, or when scan_number_bulk_contiguous()
-        // falls back to scan_number().
+        // Note this reasons about std::uint64_t/std::int64_t, not about
+        // number_unsigned_t/number_integer_t (BasicJsonType's own, possibly
+        // narrower, template parameters -- e.g. std::uint32_t). That is fine
+        // *only* because discard_number_values is exclusively set by
+        // accept() (see json.hpp), and accept() always parses through the
+        // library's own json_sax_acceptor -- never a user-supplied SAX
+        // consumer -- whose number_unsigned()/number_integer()/number_float()
+        // callbacks unconditionally discard their argument and return true.
+        // So for every caller that can reach this branch, neither the token
+        // classification below nor the eventual (possibly narrowed, and on
+        // this fast path left stale/unset) value_unsigned/value_integer is
+        // ever consulted -- an unsigned/integer token is accepted outright,
+        // and even a >18-digit token that this fast path deliberately falls
+        // through for is, once reclassified to value_float, still finite
+        // (and thus accepted) for any digit count that fits in number_unsigned_t
+        // or number_integer_t regardless of that type's width. If this
+        // function is ever taught to run with discard_number_values true for
+        // a caller that *does* read the converted value, this reasoning (and
+        // the fast path below) would need to be revisited.
         if (discard_number_values)
         {
             constexpr std::size_t safe_digit_count = 18;
@@ -2008,7 +2023,7 @@ scan_number_done:
         return value_float;
     }
 
-    /// return current string value
+    /// return current string value (implicitly resets the token; useful only once)
     string_t& get_string()
     {
         // a number token holds '.' regardless of the locale (#4084)
@@ -2310,11 +2325,11 @@ scan_number_done:
     /// the position of the decimal point in token_buffer
     std::size_t decimal_point_position = std::string::npos;
 
-    /// whether the caller only needs the token types and never looks at the
-    /// converted numeric values; set only by accept(), which parses through
-    /// json_sax_acceptor. When set, convert_number() skips converting integer
-    /// tokens whose digit count guarantees that they fit into 64 bits (see
-    /// there)
+    /// whether the caller (e.g. accept()/json_sax_acceptor) only needs the
+    /// token classification and never looks at the converted numeric value;
+    /// when set, scan_number() may skip strtoull()/strtoll() for
+    /// value_unsigned/value_integer tokens whose digit count guarantees they
+    /// fit into 64 bits (see scan_number())
     const bool discard_number_values = false;
 };
 

include/nlohmann/detail/input/parser.hpp

@@ -54,8 +54,7 @@ using parser_callback_t =
 /*!
 @brief syntax analysis
 
-This class implements an iterative parser that keeps the open containers on
-an explicit stack and reports what it reads as SAX events.
+This class implements a recursive descent parser.
 */
 template<typename BasicJsonType, typename InputAdapterType>
 class parser
@@ -440,9 +439,8 @@ class parser
 
                     // We are done with this array. Before we can parse a
                     // new value, we need to evaluate the new state first.
-                    // By setting skip_to_state_evaluation to true, the next
-                    // iteration skips parsing a value and evaluates the
-                    // enclosing state directly.
+                    // By setting skip_to_state_evaluation to false, we
+                    // are effectively jumping to the beginning of this if.
                     JSON_ASSERT(!states.empty());
                     states.pop_back();
                     skip_to_state_evaluation = true;
@@ -502,9 +500,8 @@ class parser
 
                 // We are done with this object. Before we can parse a
                 // new value, we need to evaluate the new state first.
-                // By setting skip_to_state_evaluation to true, the next
-                // iteration skips parsing a value and evaluates the
-                // enclosing state directly.
+                // By setting skip_to_state_evaluation to false, we
+                // are effectively jumping to the beginning of this if.
                 JSON_ASSERT(!states.empty());
                 states.pop_back();
                 skip_to_state_evaluation = true;

include/nlohmann/detail/macro_scope.hpp

@@ -915,7 +915,3 @@ void templated_json_throw(ExceptionType exception)
 #ifndef JSON_DISABLE_ENUM_SERIALIZATION
     #define JSON_DISABLE_ENUM_SERIALIZATION 0
 #endif
-
-#ifndef JSON_USE_GLOBAL_UDLS
-    #define JSON_USE_GLOBAL_UDLS 1
-#endif

include/nlohmann/detail/macro_unscope.hpp

@@ -25,7 +25,6 @@
 #undef JSON_INLINE_VARIABLE
 #undef JSON_NO_UNIQUE_ADDRESS
 #undef JSON_DISABLE_ENUM_SERIALIZATION
-#undef JSON_USE_GLOBAL_UDLS
 
 #ifndef JSON_TEST_KEEP_MACROS
     #undef JSON_CATCH

include/nlohmann/detail/string_utils.hpp

@@ -51,23 +51,11 @@ This is a single-byte step of a "shift-based" UTF-8 decoder originally
 written by Björn Hoehrmann. See
 http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.
 
-The library checks UTF-8 well-formedness (RFC 3629, section 4) in four
-places, which differ in speed, diagnostics, and how they read the input:
-
-- decode() and @ref is_valid_utf8 below: the serializer (to escape and, in
-  strict mode, reject ill-formed UTF-8 when dumping a string) and the CBOR,
-  MessagePack, BSON, UBJSON and BJData readers (to reject ill-formed UTF-8 in
-  text strings at decode time).
-- the per-lead-byte switch in lexer::scan_string(): JSON text, with a
-  diagnostic for each kind of error.
-- validate_one_utf8() and valid_utf8_prefix() in string_scan.hpp: the lexer's
-  bulk string scan, the bulk path of the BON8 reader, and the BON8 writer.
-  They must accept exactly what the lexer's switch accepts.
-- the byte path of binary_reader::get_bon8_string(): BON8 input without bulk
-  access, and the bytes the bulk path leaves to it.
-
-All four must accept the same set of sequences, so a change to one needs a
-matching change to the others.
+This decoder is the single source of truth for UTF-8 validation in this
+library: it is used both by the serializer (to escape and, in strict mode,
+reject ill-formed UTF-8 when dumping a string) and by the binary readers
+(to reject ill-formed UTF-8 in CBOR/MessagePack/BSON/UBJSON text strings at
+decode time; see @ref is_valid_utf8 below).
 
 @param[in,out] state  the current decoder state
 @param[in,out] codep  codepoint (valid only if resulting state is UTF8_ACCEPT)

include/nlohmann/json.hpp

@@ -149,9 +149,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     friend class ::nlohmann::detail::json_sax_dom_parser;
     template<typename BasicJsonType, typename InputAdapterType>
     friend class ::nlohmann::detail::json_sax_dom_callback_parser;
-#if JSON_DIAGNOSTIC_POSITIONS
-    friend struct ::nlohmann::detail::diagnostic_positions;
-#endif
     friend class ::nlohmann::detail::exception;
 
     /// workaround type for MSVC
@@ -6426,55 +6423,6 @@ std::string format_as(const NLOHMANN_BASIC_JSON_TPL& j)
     return j.dump();
 }
 
-inline namespace literals
-{
-inline namespace json_literals
-{
-
-/// @brief user-defined string literal for JSON values
-/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json/
-JSON_HEDLEY_NON_NULL(1)
-#if !defined(JSON_HEDLEY_GCC_VERSION) || JSON_HEDLEY_GCC_VERSION_CHECK(4,9,0)
-    inline nlohmann::json operator""_json(const char* s, std::size_t n)
-#else
-    // GCC 4.8 requires a space between "" and suffix
-    inline nlohmann::json operator"" _json(const char* s, std::size_t n)
-#endif
-{
-    return nlohmann::json::parse(s, s + n);
-}
-
-#if defined(__cpp_char8_t)
-JSON_HEDLEY_NON_NULL(1)
-inline nlohmann::json operator""_json(const char8_t* s, std::size_t n)
-{
-    return nlohmann::json::parse(reinterpret_cast<const char*>(s),
-                                 reinterpret_cast<const char*>(s) + n);
-}
-#endif
-
-/// @brief user-defined string literal for JSON pointer
-/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json_pointer/
-JSON_HEDLEY_NON_NULL(1)
-#if !defined(JSON_HEDLEY_GCC_VERSION) || JSON_HEDLEY_GCC_VERSION_CHECK(4,9,0)
-    inline nlohmann::json::json_pointer operator""_json_pointer(const char* s, std::size_t n)
-#else
-    // GCC 4.8 requires a space between "" and suffix
-    inline nlohmann::json::json_pointer operator"" _json_pointer(const char* s, std::size_t n)
-#endif
-{
-    return nlohmann::json::json_pointer(std::string(s, n));
-}
-
-#if defined(__cpp_char8_t)
-inline nlohmann::json::json_pointer operator""_json_pointer(const char8_t* s, std::size_t n)
-{
-    return nlohmann::json::json_pointer(std::string(reinterpret_cast<const char*>(s), n));
-}
-#endif
-
-}  // namespace json_literals
-}  // namespace literals
 NLOHMANN_JSON_NAMESPACE_END
 
 ///////////////////////
@@ -6609,17 +6557,6 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
 
 }  // namespace std
 
-#if JSON_USE_GLOBAL_UDLS
-    #if !defined(JSON_HEDLEY_GCC_VERSION) || JSON_HEDLEY_GCC_VERSION_CHECK(4,9,0)
-        using nlohmann::literals::json_literals::operator""_json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-        using nlohmann::literals::json_literals::operator""_json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-    #else
-        // GCC 4.8 requires a space between "" and suffix
-        using nlohmann::literals::json_literals::operator"" _json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-        using nlohmann::literals::json_literals::operator"" _json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-    #endif
-#endif
-
 #include <nlohmann/detail/macro_unscope.hpp>
 
 // End of GCC diagnostic pragmas for C++ modules support
@@ -6627,4 +6564,13 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
     #pragma GCC diagnostic pop
 #endif
 
+// The user-defined string literals are in a separate header, because their
+// bodies instantiate the parser in every translation unit that includes them.
+// Define JSON_NO_AUTOMATIC_UDLS to include <nlohmann/json_literals.hpp> only
+// where needed.
+#ifndef JSON_NO_AUTOMATIC_UDLS
+    // NOLINTNEXTLINE(misc-header-include-cycle): json_literals.hpp includes this header
+    #include <nlohmann/json_literals.hpp>
+#endif
+
 #endif  // INCLUDE_NLOHMANN_JSON_HPP_

include/nlohmann/json_literals.hpp

@@ -0,0 +1,84 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#ifndef INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+#define INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+
+#include <cstddef> // size_t
+#include <string> // string
+
+// NOLINTNEXTLINE(misc-header-include-cycle): json.hpp includes this header at its end
+#include <nlohmann/json.hpp>
+
+// This header is included at the end of <nlohmann/json.hpp> unless
+// JSON_NO_AUTOMATIC_UDLS is defined, and can be included on its own after that.
+// Either way, the library's internal macros are no longer defined here (and the
+// amalgamation inlines macro_scope.hpp only once), so only standard and public
+// macros may be used below.
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+inline namespace literals
+{
+inline namespace json_literals
+{
+
+/// @brief user-defined string literal for JSON values
+/// @sa https://json.nlohmann.me/api/operator_literal_json/
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    inline nlohmann::json operator""_json(const char* s, std::size_t n)
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    inline nlohmann::json operator"" _json(const char* s, std::size_t n)
+#endif
+{
+    return nlohmann::json::parse(s, s + n);
+}
+
+#if defined(__cpp_char8_t)
+inline nlohmann::json operator""_json(const char8_t* s, std::size_t n)
+{
+    return nlohmann::json::parse(reinterpret_cast<const char*>(s),
+                                 reinterpret_cast<const char*>(s) + n);
+}
+#endif
+
+/// @brief user-defined string literal for JSON pointer
+/// @sa https://json.nlohmann.me/api/operator_literal_json_pointer/
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    inline nlohmann::json::json_pointer operator""_json_pointer(const char* s, std::size_t n)
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    inline nlohmann::json::json_pointer operator"" _json_pointer(const char* s, std::size_t n)
+#endif
+{
+    return nlohmann::json::json_pointer(std::string(s, n));
+}
+
+#if defined(__cpp_char8_t)
+inline nlohmann::json::json_pointer operator""_json_pointer(const char8_t* s, std::size_t n)
+{
+    return nlohmann::json::json_pointer(std::string(reinterpret_cast<const char*>(s), n));
+}
+#endif
+
+}  // namespace json_literals
+}  // namespace literals
+NLOHMANN_JSON_NAMESPACE_END
+
+#if !defined(JSON_USE_GLOBAL_UDLS) || JSON_USE_GLOBAL_UDLS
+    #if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+        using nlohmann::literals::json_literals::operator""_json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+        using nlohmann::literals::json_literals::operator""_json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+    #else
+        // GCC 4.8 requires a space between "" and suffix
+        using nlohmann::literals::json_literals::operator"" _json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+        using nlohmann::literals::json_literals::operator"" _json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+    #endif
+#endif
+
+#endif  // INCLUDE_NLOHMANN_JSON_LITERALS_HPP_

meson.build

@@ -15,6 +15,7 @@ nlohmann_json_multiple_headers = declare_dependency(
 if not meson.is_subproject()
 install_headers('single_include/nlohmann/json.hpp', subdir: 'nlohmann')
 install_headers('single_include/nlohmann/json_fwd.hpp', subdir: 'nlohmann')
+install_headers('single_include/nlohmann/json_literals.hpp', subdir: 'nlohmann')
 
 pkgc = import('pkgconfig')
 pkgc.generate(name: 'nlohmann_json',

single_include/nlohmann/json.hpp

@@ -3327,10 +3327,6 @@ void templated_json_throw(ExceptionType exception)
     #define JSON_DISABLE_ENUM_SERIALIZATION 0
 #endif
 
-#ifndef JSON_USE_GLOBAL_UDLS
-    #define JSON_USE_GLOBAL_UDLS 1
-#endif
-
 #if JSON_HAS_THREE_WAY_COMPARISON
     #include <compare> // partial_ordering
 #endif
@@ -6249,23 +6245,11 @@ This is a single-byte step of a "shift-based" UTF-8 decoder originally
 written by Björn Hoehrmann. See
 http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.
 
-The library checks UTF-8 well-formedness (RFC 3629, section 4) in four
-places, which differ in speed, diagnostics, and how they read the input:
-
-- decode() and @ref is_valid_utf8 below: the serializer (to escape and, in
-  strict mode, reject ill-formed UTF-8 when dumping a string) and the CBOR,
-  MessagePack, BSON, UBJSON and BJData readers (to reject ill-formed UTF-8 in
-  text strings at decode time).
-- the per-lead-byte switch in lexer::scan_string(): JSON text, with a
-  diagnostic for each kind of error.
-- validate_one_utf8() and valid_utf8_prefix() in string_scan.hpp: the lexer's
-  bulk string scan, the bulk path of the BON8 reader, and the BON8 writer.
-  They must accept exactly what the lexer's switch accepts.
-- the byte path of binary_reader::get_bon8_string(): BON8 input without bulk
-  access, and the bytes the bulk path leaves to it.
-
-All four must accept the same set of sequences, so a change to one needs a
-matching change to the others.
+This decoder is the single source of truth for UTF-8 validation in this
+library: it is used both by the serializer (to escape and, in strict mode,
+reject ill-formed UTF-8 when dumping a string) and by the binary readers
+(to reject ill-formed UTF-8 in CBOR/MessagePack/BSON/UBJSON text strings at
+decode time; see @ref is_valid_utf8 below).
 
 @param[in,out] state  the current decoder state
 @param[in,out] codep  codepoint (valid only if resulting state is UTF8_ACCEPT)
@@ -7560,11 +7544,12 @@ NLOHMANN_JSON_NAMESPACE_END
 
 
 
-#include <algorithm> // min
 #include <array> // array
 #include <cstddef> // size_t
 #include <cstring> // strlen
 #include <iterator> // begin, end, iterator_traits, random_access_iterator_tag, distance, next
+#include <memory> // shared_ptr, make_shared, addressof
+#include <numeric> // accumulate
 #include <streambuf> // streambuf
 #include <string> // string, char_traits
 #include <type_traits> // enable_if, is_base_of, is_pointer, is_integral, remove_pointer
@@ -7637,9 +7622,8 @@ class file_input_adapter
 };
 
 /*!
-Input adapter for a (caching) istream. Does not skip a UTF Byte Order Mark
-itself; that is done by the lexer's skip_bom(). Does not support changing
-the underlying std::streambuf
+Input adapter for a (caching) istream. Ignores a UFT Byte Order Mark at
+beginning of input. Does not support changing the underlying std::streambuf
 in mid-input. Maintains underlying std::istream and std::streambuf to support
 subsequent use of standard std::istream operations to process any input
 characters following those used in parsing the JSON input.  Clears the
@@ -8418,9 +8402,9 @@ auto input_adapter(T (&array)[N]) -> decltype(input_adapter(array, array + N)) /
     return input_adapter(array, array + N);
 }
 
-// This class only handles inputs that construct a contiguous_bytes_input_adapter
-// (e.g. span_input_adapter). It's required so that expressions like {ptr, len}
-// can be implicitly cast to the correct adapter.
+// This class only handles inputs of input_buffer_adapter type.
+// It's required so that expressions like {ptr, len} can be implicitly cast
+// to the correct adapter.
 class span_input_adapter
 {
   public:
@@ -8465,7 +8449,6 @@ NLOHMANN_JSON_NAMESPACE_END
 
 #include <algorithm> // find_if, min
 #include <cstddef>
-#include <limits> // numeric_limits
 #include <string> // string
 #include <type_traits> // enable_if_t
 #include <utility> // move, pair
@@ -10599,30 +10582,45 @@ scan_number_done:
     */
     token_type convert_number(token_type number_type, std::size_t mantissa_end)
     {
-        // accept() only needs to know whether the input is valid, so it sets
-        // discard_number_values (see json.hpp), and an integer token whose
-        // digit count shows that it fits is reported without calling
-        // convert_integer(). A number with up to 18 digits always fits into
-        // both std::uint64_t and std::int64_t (18 nines is about 1e18, below
-        // INT64_MAX, which is about 9.2e18). Longer tokens take the exact path
-        // below, including the fallback to floating point when the value does
-        // not fit.
+        // If the caller does not need the converted value (only whether the
+        // input is syntactically valid; see json_sax_acceptor/accept()), an
+        // unsigned/integer token can be reported without calling
+        // strtoull()/strtoll() at all, *provided* we can already tell from
+        // the digit count alone that the conversion cannot overflow 64 bits.
+        // Such tokens are always finite and are accepted unconditionally by
+        // the parser regardless of their actual value (parser::sax_parse_internal()
+        // never checks finiteness for value_unsigned/value_integer), so the
+        // classification below is all that is needed.
         //
-        // With a narrower number_unsigned_t/number_integer_t (e.g.
-        // std::uint32_t), the exact path would reclassify some of these tokens
-        // as (finite) floats, while this check reports integers. That does not
-        // change the result of accept(): it always parses through
-        // json_sax_acceptor, whose number callbacks discard their argument and
-        // return true, and the parser rejects neither integers nor finite
-        // floats. value_unsigned/value_integer are left unset here, so a caller
-        // that reads the converted value must not set discard_number_values.
+        // A decimal number with up to 18 digits is always representable in
+        // both std::uint64_t and std::int64_t (18 nines is ~1e18, well below
+        // both UINT64_MAX ~1.8e19 and INT64_MAX ~9.2e18), so strtoull()/strtoll()
+        // could not have set errno to ERANGE for it. Numbers with more digits
+        // (rare in practice) fall through to the exact code below, unchanged,
+        // so their handling -- including reclassification to value_float when
+        // the value overflows 64 bits, and rejection when it is not even
+        // finite as a double -- is bit-for-bit identical to before this
+        // optimization.
         //
-        // On contiguous input, scan_number_bulk_contiguous() converts integer
-        // tokens itself and does not pass them to this function, unless
-        // JSON_DIAGNOSTIC_POSITIONS is enabled. This check is therefore only
-        // reached for input without bulk access (e.g. streams), with
-        // JSON_DIAGNOSTIC_POSITIONS, or when scan_number_bulk_contiguous()
-        // falls back to scan_number().
+        // Note this reasons about std::uint64_t/std::int64_t, not about
+        // number_unsigned_t/number_integer_t (BasicJsonType's own, possibly
+        // narrower, template parameters -- e.g. std::uint32_t). That is fine
+        // *only* because discard_number_values is exclusively set by
+        // accept() (see json.hpp), and accept() always parses through the
+        // library's own json_sax_acceptor -- never a user-supplied SAX
+        // consumer -- whose number_unsigned()/number_integer()/number_float()
+        // callbacks unconditionally discard their argument and return true.
+        // So for every caller that can reach this branch, neither the token
+        // classification below nor the eventual (possibly narrowed, and on
+        // this fast path left stale/unset) value_unsigned/value_integer is
+        // ever consulted -- an unsigned/integer token is accepted outright,
+        // and even a >18-digit token that this fast path deliberately falls
+        // through for is, once reclassified to value_float, still finite
+        // (and thus accepted) for any digit count that fits in number_unsigned_t
+        // or number_integer_t regardless of that type's width. If this
+        // function is ever taught to run with discard_number_values true for
+        // a caller that *does* read the converted value, this reasoning (and
+        // the fast path below) would need to be revisited.
         if (discard_number_values)
         {
             constexpr std::size_t safe_digit_count = 18;
@@ -11113,7 +11111,7 @@ scan_number_done:
         return value_float;
     }
 
-    /// return current string value
+    /// return current string value (implicitly resets the token; useful only once)
     string_t& get_string()
     {
         // a number token holds '.' regardless of the locale (#4084)
@@ -11415,11 +11413,11 @@ scan_number_done:
     /// the position of the decimal point in token_buffer
     std::size_t decimal_point_position = std::string::npos;
 
-    /// whether the caller only needs the token types and never looks at the
-    /// converted numeric values; set only by accept(), which parses through
-    /// json_sax_acceptor. When set, convert_number() skips converting integer
-    /// tokens whose digit count guarantees that they fit into 64 bits (see
-    /// there)
+    /// whether the caller (e.g. accept()/json_sax_acceptor) only needs the
+    /// token classification and never looks at the converted numeric value;
+    /// when set, scan_number() may skip strtoull()/strtoll() for
+    /// value_unsigned/value_integer tokens whose digit count guarantees they
+    /// fit into 64 bits (see scan_number())
     const bool discard_number_values = false;
 };
 
@@ -11587,88 +11585,6 @@ template<typename ArrayType>
 inline void reserve_array(ArrayType& /*arr*/, std::size_t /*len*/, priority_tag<0> /*unused*/)
 {}
 
-#if JSON_DIAGNOSTIC_POSITIONS
-/*!
-@brief set the diagnostic positions of a value the DOM SAX parsers just stored
-
-Shared by json_sax_dom_parser and json_sax_dom_callback_parser. basic_json
-befriends this struct, as the position members are private.
-*/
-struct diagnostic_positions
-{
-    /*!
-    @param[in,out] v  the value that was just parsed
-    @param[in] lexer  the lexer that read it, or nullptr to leave @a v alone
-    */
-    template<typename BasicJsonType, typename LexerType>
-    static void set_from_lexer(BasicJsonType& v, LexerType* lexer)
-    {
-        if (lexer)
-        {
-            // Lexer has read past the current field value, so set the end position to the current position.
-            // The start position will be set below based on the length of the string representation
-            // of the value.
-            v.end_position = lexer->get_position();
-
-            switch (v.type())
-            {
-                case value_t::boolean:
-                {
-                    // 4 and 5 are the string length of "true" and "false"
-                    v.start_position = v.end_position - (v.m_data.m_value.boolean ? 4 : 5);
-                    break;
-                }
-
-                case value_t::null:
-                {
-                    // 4 is the string length of "null"
-                    v.start_position = v.end_position - 4;
-                    break;
-                }
-
-                case value_t::string:
-                {
-                    // escape sequences make the token longer than the value it
-                    // parses to, so the start position cannot be derived from
-                    // the value; use the offset the lexer recorded instead
-                    v.start_position = lexer->get_token_start_position();
-                    break;
-                }
-
-                case value_t::discarded:
-                {
-                    // an object or array the callback of
-                    // json_sax_dom_callback_parser rejected has no position
-                    v.end_position = std::string::npos;
-                    v.start_position = v.end_position;
-                    break;
-                }
-
-                case value_t::binary:
-                case value_t::number_integer:
-                case value_t::number_unsigned:
-                case value_t::number_float:
-                {
-                    v.start_position = v.end_position - lexer->get_string().size();
-                    break;
-                }
-
-                case value_t::object:
-                case value_t::array:
-                {
-                    // object and array are handled in start_object() and start_array() handlers
-                    // skip setting the values here.
-                    break;
-                }
-                default: // LCOV_EXCL_LINE
-                    // Handle all possible types discretely, default handler should never be reached.
-                    JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert) LCOV_EXCL_LINE
-            }
-        }
-    }
-};
-#endif
-
 /*!
 @brief SAX implementation to create a JSON value from SAX events
 
@@ -11870,6 +11786,76 @@ class json_sax_dom_parser
 
   private:
 
+#if JSON_DIAGNOSTIC_POSITIONS
+    void handle_diagnostic_positions_for_json_value(BasicJsonType& v)
+    {
+        if (m_lexer_ref)
+        {
+            // Lexer has read past the current field value, so set the end position to the current position.
+            // The start position will be set below based on the length of the string representation
+            // of the value.
+            v.end_position = m_lexer_ref->get_position();
+
+            switch (v.type())
+            {
+                case value_t::boolean:
+                {
+                    // 4 and 5 are the string length of "true" and "false"
+                    v.start_position = v.end_position - (v.m_data.m_value.boolean ? 4 : 5);
+                    break;
+                }
+
+                case value_t::null:
+                {
+                    // 4 is the string length of "null"
+                    v.start_position = v.end_position - 4;
+                    break;
+                }
+
+                case value_t::string:
+                {
+                    // escape sequences make the token longer than the value it
+                    // parses to, so the start position cannot be derived from
+                    // the value; use the offset the lexer recorded instead
+                    v.start_position = m_lexer_ref->get_token_start_position();
+                    break;
+                }
+
+                // As we handle the start and end positions for values created during parsing,
+                // we do not expect the following value type to be called. Regardless, set the positions
+                // in case this is created manually or through a different constructor. Exclude from lcov
+                // since the exact condition of this switch is esoteric.
+                // LCOV_EXCL_START
+                case value_t::discarded:
+                {
+                    v.end_position = std::string::npos;
+                    v.start_position = v.end_position;
+                    break;
+                }
+                // LCOV_EXCL_STOP
+                case value_t::binary:
+                case value_t::number_integer:
+                case value_t::number_unsigned:
+                case value_t::number_float:
+                {
+                    v.start_position = v.end_position - m_lexer_ref->get_string().size();
+                    break;
+                }
+                case value_t::object:
+                case value_t::array:
+                {
+                    // object and array are handled in start_object() and start_array() handlers
+                    // skip setting the values here.
+                    break;
+                }
+                default: // LCOV_EXCL_LINE
+                    // Handle all possible types discretely, default handler should never be reached.
+                    JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert,-warnings-as-errors) LCOV_EXCL_LINE
+            }
+        }
+    }
+#endif
+
     /*!
     @invariant If the ref stack is empty, then the passed value will be the new
                root.
@@ -11885,7 +11871,7 @@ class json_sax_dom_parser
             root = BasicJsonType(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-            diagnostic_positions::set_from_lexer(root, m_lexer_ref);
+            handle_diagnostic_positions_for_json_value(root);
 #endif
 
             return &root;
@@ -11898,7 +11884,7 @@ class json_sax_dom_parser
             ref_stack.back()->m_data.m_value.array->emplace_back(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-            diagnostic_positions::set_from_lexer(ref_stack.back()->m_data.m_value.array->back(), m_lexer_ref);
+            handle_diagnostic_positions_for_json_value(ref_stack.back()->m_data.m_value.array->back());
 #endif
 
             return &(ref_stack.back()->m_data.m_value.array->back());
@@ -11909,7 +11895,7 @@ class json_sax_dom_parser
         *object_element = BasicJsonType(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-        diagnostic_positions::set_from_lexer(*object_element, m_lexer_ref);
+        handle_diagnostic_positions_for_json_value(*object_element);
 #endif
 
         return object_element;
@@ -12086,7 +12072,7 @@ class json_sax_dom_callback_parser
 
 #if JSON_DIAGNOSTIC_POSITIONS
                     // Set start/end positions for discarded object.
-                    diagnostic_positions::set_from_lexer(*ref_stack.back(), m_lexer_ref);
+                    handle_diagnostic_positions_for_json_value(*ref_stack.back());
 #endif
                 }
             }
@@ -12202,7 +12188,7 @@ class json_sax_dom_callback_parser
 
 #if JSON_DIAGNOSTIC_POSITIONS
                     // Set start/end positions for discarded array.
-                    diagnostic_positions::set_from_lexer(*ref_stack.back(), m_lexer_ref);
+                    handle_diagnostic_positions_for_json_value(*ref_stack.back());
 #endif
                 }
             }
@@ -12255,6 +12241,72 @@ class json_sax_dom_callback_parser
 
   private:
 
+#if JSON_DIAGNOSTIC_POSITIONS
+    void handle_diagnostic_positions_for_json_value(BasicJsonType& v)
+    {
+        if (m_lexer_ref)
+        {
+            // Lexer has read past the current field value, so set the end position to the current position.
+            // The start position will be set below based on the length of the string representation
+            // of the value.
+            v.end_position = m_lexer_ref->get_position();
+
+            switch (v.type())
+            {
+                case value_t::boolean:
+                {
+                    // 4 and 5 are the string length of "true" and "false"
+                    v.start_position = v.end_position - (v.m_data.m_value.boolean ? 4 : 5);
+                    break;
+                }
+
+                case value_t::null:
+                {
+                    // 4 is the string length of "null"
+                    v.start_position = v.end_position - 4;
+                    break;
+                }
+
+                case value_t::string:
+                {
+                    // escape sequences make the token longer than the value it
+                    // parses to, so the start position cannot be derived from
+                    // the value; use the offset the lexer recorded instead
+                    v.start_position = m_lexer_ref->get_token_start_position();
+                    break;
+                }
+
+                case value_t::discarded:
+                {
+                    v.end_position = std::string::npos;
+                    v.start_position = v.end_position;
+                    break;
+                }
+
+                case value_t::binary:
+                case value_t::number_integer:
+                case value_t::number_unsigned:
+                case value_t::number_float:
+                {
+                    v.start_position = v.end_position - m_lexer_ref->get_string().size();
+                    break;
+                }
+
+                case value_t::object:
+                case value_t::array:
+                {
+                    // object and array are handled in start_object() and start_array() handlers
+                    // skip setting the values here.
+                    break;
+                }
+                default: // LCOV_EXCL_LINE
+                    // Handle all possible types discretely, default handler should never be reached.
+                    JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert,-warnings-as-errors) LCOV_EXCL_LINE
+            }
+        }
+    }
+#endif
+
     /// if there is a pending duplicate-key stash entry for this exact slot,
     /// remove it from the stash; if restore_value is true, the stashed
     /// previous value is moved back into the slot first (use this when the
@@ -12376,7 +12428,7 @@ class json_sax_dom_callback_parser
         auto value = BasicJsonType(std::forward<Value>(v));
 
 #if JSON_DIAGNOSTIC_POSITIONS
-        diagnostic_positions::set_from_lexer(value, m_lexer_ref);
+        handle_diagnostic_positions_for_json_value(value);
 #endif
 
         // check callback
@@ -16055,8 +16107,8 @@ class binary_reader
         return enter_object(detail::unknown_size());
     }
 
-    // Note, UBJSON has no binary type of its own; BJData, which shares this
-    // reader, decodes optimized 'B' arrays as binary in get_ubjson_array().
+    // Note, no reader for UBJSON binary types is implemented because they do
+    // not exist
 
     bool get_ubjson_high_precision_number()
     {
@@ -16763,7 +16815,7 @@ class binary_reader
 #endif
     }
 
-    /*!
+    /*
     @brief read a number from the input
 
     @tparam NumberType the type of the number
@@ -16773,10 +16825,10 @@ class binary_reader
     @return whether conversion completed
 
     @note This function needs to respect the system's endianness, because
-          bytes in CBOR, MessagePack, UBJSON, and BON8 are stored in network
-          order (big endian) and therefore need reordering on little endian
-          systems. On the other hand, BSON and BJData use little endian and
-          should reorder on big endian systems.
+          bytes in CBOR, MessagePack, and UBJSON are stored in network order
+          (big endian) and therefore need reordering on little endian systems.
+          On the other hand, BSON and BJData use little endian and should reorder
+          on big endian systems.
     */
     template<typename NumberType, bool InputIsLittleEndian = false>
     bool get_number(const input_format_t format, NumberType& result)
@@ -17130,8 +17182,7 @@ using parser_callback_t =
 /*!
 @brief syntax analysis
 
-This class implements an iterative parser that keeps the open containers on
-an explicit stack and reports what it reads as SAX events.
+This class implements a recursive descent parser.
 */
 template<typename BasicJsonType, typename InputAdapterType>
 class parser
@@ -17516,9 +17567,8 @@ class parser
 
                     // We are done with this array. Before we can parse a
                     // new value, we need to evaluate the new state first.
-                    // By setting skip_to_state_evaluation to true, the next
-                    // iteration skips parsing a value and evaluates the
-                    // enclosing state directly.
+                    // By setting skip_to_state_evaluation to false, we
+                    // are effectively jumping to the beginning of this if.
                     JSON_ASSERT(!states.empty());
                     states.pop_back();
                     skip_to_state_evaluation = true;
@@ -17578,9 +17628,8 @@ class parser
 
                 // We are done with this object. Before we can parse a
                 // new value, we need to evaluate the new state first.
-                // By setting skip_to_state_evaluation to true, the next
-                // iteration skips parsing a value and evaluates the
-                // enclosing state directly.
+                // By setting skip_to_state_evaluation to false, we
+                // are effectively jumping to the beginning of this if.
                 JSON_ASSERT(!states.empty());
                 states.pop_back();
                 skip_to_state_evaluation = true;
@@ -26177,9 +26226,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     friend class ::nlohmann::detail::json_sax_dom_parser;
     template<typename BasicJsonType, typename InputAdapterType>
     friend class ::nlohmann::detail::json_sax_dom_callback_parser;
-#if JSON_DIAGNOSTIC_POSITIONS
-    friend struct ::nlohmann::detail::diagnostic_positions;
-#endif
     friend class ::nlohmann::detail::exception;
 
     /// workaround type for MSVC
@@ -32454,55 +32500,6 @@ std::string format_as(const NLOHMANN_BASIC_JSON_TPL& j)
     return j.dump();
 }
 
-inline namespace literals
-{
-inline namespace json_literals
-{
-
-/// @brief user-defined string literal for JSON values
-/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json/
-JSON_HEDLEY_NON_NULL(1)
-#if !defined(JSON_HEDLEY_GCC_VERSION) || JSON_HEDLEY_GCC_VERSION_CHECK(4,9,0)
-    inline nlohmann::json operator""_json(const char* s, std::size_t n)
-#else
-    // GCC 4.8 requires a space between "" and suffix
-    inline nlohmann::json operator"" _json(const char* s, std::size_t n)
-#endif
-{
-    return nlohmann::json::parse(s, s + n);
-}
-
-#if defined(__cpp_char8_t)
-JSON_HEDLEY_NON_NULL(1)
-inline nlohmann::json operator""_json(const char8_t* s, std::size_t n)
-{
-    return nlohmann::json::parse(reinterpret_cast<const char*>(s),
-                                 reinterpret_cast<const char*>(s) + n);
-}
-#endif
-
-/// @brief user-defined string literal for JSON pointer
-/// @sa https://json.nlohmann.me/api/basic_json/operator_literal_json_pointer/
-JSON_HEDLEY_NON_NULL(1)
-#if !defined(JSON_HEDLEY_GCC_VERSION) || JSON_HEDLEY_GCC_VERSION_CHECK(4,9,0)
-    inline nlohmann::json::json_pointer operator""_json_pointer(const char* s, std::size_t n)
-#else
-    // GCC 4.8 requires a space between "" and suffix
-    inline nlohmann::json::json_pointer operator"" _json_pointer(const char* s, std::size_t n)
-#endif
-{
-    return nlohmann::json::json_pointer(std::string(s, n));
-}
-
-#if defined(__cpp_char8_t)
-inline nlohmann::json::json_pointer operator""_json_pointer(const char8_t* s, std::size_t n)
-{
-    return nlohmann::json::json_pointer(std::string(reinterpret_cast<const char*>(s), n));
-}
-#endif
-
-}  // namespace json_literals
-}  // namespace literals
 NLOHMANN_JSON_NAMESPACE_END
 
 ///////////////////////
@@ -32637,17 +32634,6 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
 
 }  // namespace std
 
-#if JSON_USE_GLOBAL_UDLS
-    #if !defined(JSON_HEDLEY_GCC_VERSION) || JSON_HEDLEY_GCC_VERSION_CHECK(4,9,0)
-        using nlohmann::literals::json_literals::operator""_json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-        using nlohmann::literals::json_literals::operator""_json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-    #else
-        // GCC 4.8 requires a space between "" and suffix
-        using nlohmann::literals::json_literals::operator"" _json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-        using nlohmann::literals::json_literals::operator"" _json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
-    #endif
-#endif
-
 // #include <nlohmann/detail/macro_unscope.hpp>
 //     __ _____ _____ _____
 //  __|  |   __|     |   | |  JSON for Modern C++
@@ -32676,7 +32662,6 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
 #undef JSON_INLINE_VARIABLE
 #undef JSON_NO_UNIQUE_ADDRESS
 #undef JSON_DISABLE_ENUM_SERIALIZATION
-#undef JSON_USE_GLOBAL_UDLS
 
 #ifndef JSON_TEST_KEEP_MACROS
     #undef JSON_CATCH
@@ -32869,4 +32854,99 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
     #pragma GCC diagnostic pop
 #endif
 
+// The user-defined string literals are in a separate header, because their
+// bodies instantiate the parser in every translation unit that includes them.
+// Define JSON_NO_AUTOMATIC_UDLS to include <nlohmann/json_literals.hpp> only
+// where needed.
+#ifndef JSON_NO_AUTOMATIC_UDLS
+// NOLINTNEXTLINE(misc-header-include-cycle): json_literals.hpp includes this header
+// #include <nlohmann/json_literals.hpp>
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#ifndef INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+#define INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+
+#include <cstddef> // size_t
+#include <string> // string
+
+// NOLINTNEXTLINE(misc-header-include-cycle): json.hpp includes this header at its end
+// #include <nlohmann/json.hpp>
+
+
+// This header is included at the end of <nlohmann/json.hpp> unless
+// JSON_NO_AUTOMATIC_UDLS is defined, and can be included on its own after that.
+// Either way, the library's internal macros are no longer defined here (and the
+// amalgamation inlines macro_scope.hpp only once), so only standard and public
+// macros may be used below.
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+inline namespace literals
+{
+inline namespace json_literals
+{
+
+/// @brief user-defined string literal for JSON values
+/// @sa https://json.nlohmann.me/api/operator_literal_json/
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    inline nlohmann::json operator""_json(const char* s, std::size_t n)
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    inline nlohmann::json operator"" _json(const char* s, std::size_t n)
+#endif
+{
+    return nlohmann::json::parse(s, s + n);
+}
+
+#if defined(__cpp_char8_t)
+inline nlohmann::json operator""_json(const char8_t* s, std::size_t n)
+{
+    return nlohmann::json::parse(reinterpret_cast<const char*>(s),
+                                 reinterpret_cast<const char*>(s) + n);
+}
+#endif
+
+/// @brief user-defined string literal for JSON pointer
+/// @sa https://json.nlohmann.me/api/operator_literal_json_pointer/
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    inline nlohmann::json::json_pointer operator""_json_pointer(const char* s, std::size_t n)
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    inline nlohmann::json::json_pointer operator"" _json_pointer(const char* s, std::size_t n)
+#endif
+{
+    return nlohmann::json::json_pointer(std::string(s, n));
+}
+
+#if defined(__cpp_char8_t)
+inline nlohmann::json::json_pointer operator""_json_pointer(const char8_t* s, std::size_t n)
+{
+    return nlohmann::json::json_pointer(std::string(reinterpret_cast<const char*>(s), n));
+}
+#endif
+
+}  // namespace json_literals
+}  // namespace literals
+NLOHMANN_JSON_NAMESPACE_END
+
+#if !defined(JSON_USE_GLOBAL_UDLS) || JSON_USE_GLOBAL_UDLS
+    #if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+        using nlohmann::literals::json_literals::operator""_json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+        using nlohmann::literals::json_literals::operator""_json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+    #else
+        // GCC 4.8 requires a space between "" and suffix
+        using nlohmann::literals::json_literals::operator"" _json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+        using nlohmann::literals::json_literals::operator"" _json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+    #endif
+#endif
+
+#endif  // INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+
+#endif
+
 #endif  // INCLUDE_NLOHMANN_JSON_HPP_

single_include/nlohmann/json_literals.hpp

@@ -0,0 +1,84 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#ifndef INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+#define INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
+
+#include <cstddef> // size_t
+#include <string> // string
+
+// NOLINTNEXTLINE(misc-header-include-cycle): json.hpp includes this header at its end
+#include <nlohmann/json.hpp>
+
+// This header is included at the end of <nlohmann/json.hpp> unless
+// JSON_NO_AUTOMATIC_UDLS is defined, and can be included on its own after that.
+// Either way, the library's internal macros are no longer defined here (and the
+// amalgamation inlines macro_scope.hpp only once), so only standard and public
+// macros may be used below.
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+inline namespace literals
+{
+inline namespace json_literals
+{
+
+/// @brief user-defined string literal for JSON values
+/// @sa https://json.nlohmann.me/api/operator_literal_json/
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    inline nlohmann::json operator""_json(const char* s, std::size_t n)
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    inline nlohmann::json operator"" _json(const char* s, std::size_t n)
+#endif
+{
+    return nlohmann::json::parse(s, s + n);
+}
+
+#if defined(__cpp_char8_t)
+inline nlohmann::json operator""_json(const char8_t* s, std::size_t n)
+{
+    return nlohmann::json::parse(reinterpret_cast<const char*>(s),
+                                 reinterpret_cast<const char*>(s) + n);
+}
+#endif
+
+/// @brief user-defined string literal for JSON pointer
+/// @sa https://json.nlohmann.me/api/operator_literal_json_pointer/
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    inline nlohmann::json::json_pointer operator""_json_pointer(const char* s, std::size_t n)
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    inline nlohmann::json::json_pointer operator"" _json_pointer(const char* s, std::size_t n)
+#endif
+{
+    return nlohmann::json::json_pointer(std::string(s, n));
+}
+
+#if defined(__cpp_char8_t)
+inline nlohmann::json::json_pointer operator""_json_pointer(const char8_t* s, std::size_t n)
+{
+    return nlohmann::json::json_pointer(std::string(reinterpret_cast<const char*>(s), n));
+}
+#endif
+
+}  // namespace json_literals
+}  // namespace literals
+NLOHMANN_JSON_NAMESPACE_END
+
+#if !defined(JSON_USE_GLOBAL_UDLS) || JSON_USE_GLOBAL_UDLS
+    #if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+        using nlohmann::literals::json_literals::operator""_json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+        using nlohmann::literals::json_literals::operator""_json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+    #else
+        // GCC 4.8 requires a space between "" and suffix
+        using nlohmann::literals::json_literals::operator"" _json; // NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+        using nlohmann::literals::json_literals::operator"" _json_pointer; //NOLINT(misc-unused-using-decls,google-global-names-in-headers)
+    #endif
+#endif
+
+#endif  // INCLUDE_NLOHMANN_JSON_LITERALS_HPP_

src/modules/json.cppm

@@ -18,6 +18,7 @@ module;
 // See: https://github.com/nlohmann/json/issues/5103
 
 #include <nlohmann/json.hpp>
+#include <nlohmann/json_literals.hpp>
 
 export module nlohmann.json;
 

tests/src/unit-no_automatic_udls.cpp

@@ -0,0 +1,108 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+// This translation unit checks JSON_NO_AUTOMATIC_UDLS, which keeps
+// <nlohmann/json.hpp> from including <nlohmann/json_literals.hpp> and thereby
+// leaves out the user-defined string literals operator""_json and
+// operator""_json_pointer (see #5294), and that including
+// <nlohmann/json_literals.hpp> afterwards brings them back.
+#define JSON_NO_AUTOMATIC_UDLS 1
+
+#include "doctest_compatibility.h"
+
+#include <cstddef>
+#include <utility>
+
+#include <nlohmann/json.hpp>
+using json = nlohmann::json;
+
+// An argument type whose associated namespace is the library namespace, so
+// argument-dependent lookup of a literal operator called by its function name
+// also searches the inline namespaces nlohmann::literals::json_literals.
+NLOHMANN_JSON_NAMESPACE_BEGIN
+struct no_automatic_udls_probe
+{
+    operator const char* () const // NOLINT(google-explicit-constructor,hicpp-explicit-conversions)
+    {
+        return "";
+    }
+};
+NLOHMANN_JSON_NAMESPACE_END
+
+namespace
+{
+// The calls below use a dependent argument, so a literal operator that is not
+// declared at all is a substitution failure rather than a hard error: lookup is
+// deferred to the point of instantiation, where it considers the declarations
+// visible from here (the global using-declarations of JSON_USE_GLOBAL_UDLS) plus
+// argument-dependent lookup (the literals in the library namespace).
+#if !defined(__GNUC__) || defined(__clang__) || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)
+    template<typename T>
+    using json_udl_t = decltype(operator""_json(std::declval<T>(), std::size_t()));
+
+    template<typename T>
+    using json_pointer_udl_t = decltype(operator""_json_pointer(std::declval<T>(), std::size_t()));
+#else
+    // GCC 4.8 requires a space between "" and suffix
+    template<typename T>
+    using json_udl_t = decltype(operator"" _json(std::declval<T>(), std::size_t()));
+
+    template<typename T>
+    using json_pointer_udl_t = decltype(operator"" _json_pointer(std::declval<T>(), std::size_t()));
+#endif
+
+template<typename T>
+using has_json_udl = nlohmann::detail::is_detected<json_udl_t, T>;
+
+template<typename T>
+using has_json_pointer_udl = nlohmann::detail::is_detected<json_pointer_udl_t, T>;
+} // namespace
+
+TEST_CASE("JSON_NO_AUTOMATIC_UDLS")
+{
+    SECTION("literals are not declared")
+    {
+        // global namespace (JSON_USE_GLOBAL_UDLS defaults to 1)
+        CHECK_FALSE(has_json_udl<const char*>::value);
+        CHECK_FALSE(has_json_pointer_udl<const char*>::value);
+
+        // nlohmann::literals::json_literals
+        CHECK_FALSE(has_json_udl<nlohmann::no_automatic_udls_probe>::value);
+        CHECK_FALSE(has_json_pointer_udl<nlohmann::no_automatic_udls_probe>::value);
+    }
+
+    SECTION("the rest of the library keeps working")
+    {
+        const json j = json::parse(R"({"foo": {"bar": 42}})");
+        CHECK(j.dump() == R"({"foo":{"bar":42}})");
+
+        const json::json_pointer ptr("/foo/bar");
+        CHECK(j.at(ptr) == 42);
+        CHECK(j.contains(ptr));
+    }
+}
+
+// the literals can still be added where they are needed
+#include <nlohmann/json_literals.hpp>
+
+TEST_CASE("JSON_NO_AUTOMATIC_UDLS with <nlohmann/json_literals.hpp>")
+{
+#if !defined(JSON_USE_GLOBAL_UDLS) || JSON_USE_GLOBAL_UDLS
+    SECTION("global namespace")
+    {
+        CHECK("[1,2]"_json == json({1, 2}));
+        CHECK("/a/0"_json_pointer == json::json_pointer("/a/0"));
+    }
+#endif
+
+    SECTION("nlohmann::literals::json_literals")
+    {
+        using namespace nlohmann::literals::json_literals; // NOLINT(google-build-using-namespace)
+        CHECK(R"({"a":[42]})"_json.at("/a/0"_json_pointer) == 42);
+    }
+}