Make JSON_STRICT_NUL_HANDLING part of the ABI tag (#5560)

* Make JSON_STRICT_NUL_HANDLING part of the ABI tag JSON_STRICT_NUL_HANDLING (#5534) changes the bodies of inline functions: the lexer's handling of '\0' and input_adapter() for char arrays. So translation units compiled with and without it define the same functions differently, an ODR violation - the case the ABI tag exists for, as with JSON_BRACE_INIT_COPY_SEMANTICS (_bics). It now appends _snul to the inline namespace. The macro is new in 3.13.0, so no existing namespace changes. Its default moves to abi_macros.hpp, and it is only #undef'd without JSON_TEST_KEEP_MACROS, as for the other ABI macros. The ABI config tests, the namespace docs, the macro's docs and the Natvis file cover the new tag. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Amalgamate Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-09-26 03:55:48 +00:00 · 2026-09-25 21:54:11 +02:00
parent c60a0bc336
commit 1e44262091
12 changed files with 1998 additions and 24 deletions
--- a/docs/mkdocs/docs/api/macros/json_strict_nul_handling.md
+++ b/docs/mkdocs/docs/api/macros/json_strict_nul_handling.md
@@ -65,6 +65,12 @@ The default value is `0` (disabled — existing behavior is preserved).
    for CBOR or MessagePack, are never affected by this trimming; their full extent - including a genuine trailing
    `0x00` - is always preserved, in both states of this macro.

+!!! note "ABI compatibility"
+
+    The value of this macro is encoded in the [namespace](../../features/namespace.md) (tag `_snul`), resulting in
+    distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program
+    without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
+
 !!! tip "Workaround without the macro"

    To reject a NUL byte without enabling this macro, trim your input yourself before calling `parse()`:
--- a/docs/mkdocs/docs/features/namespace.md
+++ b/docs/mkdocs/docs/features/namespace.md
@@ -19,6 +19,7 @@ The complete default namespace name is derived as follows:
    - [`JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md) defined non-zero appends
      `_bics`.
    - [`JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md) defined non-zero appends `_psp`.
+    - [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md) defined non-zero appends `_snul`.
 - The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by
  underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component)
  below.
--- a/include/nlohmann/detail/abi_macros.hpp
+++ b/include/nlohmann/detail/abi_macros.hpp
@@ -42,6 +42,10 @@
    #define JSON_PRECISE_STREAM_POSITION 0
 #endif

+#ifndef JSON_STRICT_NUL_HANDLING
+    #define JSON_STRICT_NUL_HANDLING 0
+#endif
+
 #if JSON_DIAGNOSTICS
    #define NLOHMANN_JSON_ABI_TAG_DIAGNOSTICS _diag
 #else
@@ -72,14 +76,20 @@
    #define NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION
 #endif

+#if JSON_STRICT_NUL_HANDLING
+    #define NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING _snul
+#else
+    #define NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING
+#endif
+
 #ifndef NLOHMANN_JSON_NAMESPACE_NO_VERSION
    #define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
 #endif

 // Construct the namespace ABI tags component
-#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e) json_abi ## a ## b ## c ## d ## e
-#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b, c, d, e) \
-    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e)
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e, f) json_abi ## a ## b ## c ## d ## e ## f
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b, c, d, e, f) \
+    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e, f)

 #define NLOHMANN_JSON_ABI_TAGS                                       \
    NLOHMANN_JSON_ABI_TAGS_CONCAT(                                   \
@@ -87,7 +97,8 @@
            NLOHMANN_JSON_ABI_TAG_LEGACY_DISCARDED_VALUE_COMPARISON, \
            NLOHMANN_JSON_ABI_TAG_DIAGNOSTIC_POSITIONS,              \
            NLOHMANN_JSON_ABI_TAG_BRACE_INIT_COPY_SEMANTICS,         \
-            NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION)
+            NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION,           \
+            NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING)

 // Construct the namespace version component
 #define NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT_EX(major, minor, patch) \
--- a/include/nlohmann/detail/macro_scope.hpp
+++ b/include/nlohmann/detail/macro_scope.hpp
@@ -919,7 +919,3 @@ void templated_json_throw(ExceptionType exception)
 #ifndef JSON_USE_GLOBAL_UDLS
    #define JSON_USE_GLOBAL_UDLS 1
 #endif
-
-#ifndef JSON_STRICT_NUL_HANDLING
-    #define JSON_STRICT_NUL_HANDLING 0
-#endif
--- a/include/nlohmann/detail/macro_unscope.hpp
+++ b/include/nlohmann/detail/macro_unscope.hpp
@@ -26,7 +26,6 @@
 #undef JSON_NO_UNIQUE_ADDRESS
 #undef JSON_DISABLE_ENUM_SERIALIZATION
 #undef JSON_USE_GLOBAL_UDLS
-#undef JSON_STRICT_NUL_HANDLING

 #ifndef JSON_TEST_KEEP_MACROS
    #undef JSON_CATCH
@@ -46,6 +45,7 @@
    #undef JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON
    #undef JSON_BRACE_INIT_COPY_SEMANTICS
    #undef JSON_PRECISE_STREAM_POSITION
+    #undef JSON_STRICT_NUL_HANDLING
 #endif

 #include <nlohmann/thirdparty/hedley/hedley_undef.hpp>
--- a/nlohmann_json.natvis
+++ b/nlohmann_json.natvis
--- a/single_include/nlohmann/json.hpp
+++ b/single_include/nlohmann/json.hpp
@@ -99,6 +99,10 @@
    #define JSON_PRECISE_STREAM_POSITION 0
 #endif

+#ifndef JSON_STRICT_NUL_HANDLING
+    #define JSON_STRICT_NUL_HANDLING 0
+#endif
+
 #if JSON_DIAGNOSTICS
    #define NLOHMANN_JSON_ABI_TAG_DIAGNOSTICS _diag
 #else
@@ -129,14 +133,20 @@
    #define NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION
 #endif

+#if JSON_STRICT_NUL_HANDLING
+    #define NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING _snul
+#else
+    #define NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING
+#endif
+
 #ifndef NLOHMANN_JSON_NAMESPACE_NO_VERSION
    #define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
 #endif

 // Construct the namespace ABI tags component
-#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e) json_abi ## a ## b ## c ## d ## e
-#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b, c, d, e) \
-    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e)
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e, f) json_abi ## a ## b ## c ## d ## e ## f
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b, c, d, e, f) \
+    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e, f)

 #define NLOHMANN_JSON_ABI_TAGS                                       \
    NLOHMANN_JSON_ABI_TAGS_CONCAT(                                   \
@@ -144,7 +154,8 @@
            NLOHMANN_JSON_ABI_TAG_LEGACY_DISCARDED_VALUE_COMPARISON, \
            NLOHMANN_JSON_ABI_TAG_DIAGNOSTIC_POSITIONS,              \
            NLOHMANN_JSON_ABI_TAG_BRACE_INIT_COPY_SEMANTICS,         \
-            NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION)
+            NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION,           \
+            NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING)

 // Construct the namespace version component
 #define NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT_EX(major, minor, patch) \
@@ -3320,10 +3331,6 @@ void templated_json_throw(ExceptionType exception)
    #define JSON_USE_GLOBAL_UDLS 1
 #endif

-#ifndef JSON_STRICT_NUL_HANDLING
-    #define JSON_STRICT_NUL_HANDLING 0
-#endif
-
 #if JSON_HAS_THREE_WAY_COMPARISON
    #include <compare> // partial_ordering
 #endif
@@ -31413,7 +31420,6 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
 #undef JSON_NO_UNIQUE_ADDRESS
 #undef JSON_DISABLE_ENUM_SERIALIZATION
 #undef JSON_USE_GLOBAL_UDLS
-#undef JSON_STRICT_NUL_HANDLING

 #ifndef JSON_TEST_KEEP_MACROS
    #undef JSON_CATCH
@@ -31433,6 +31439,7 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
    #undef JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON
    #undef JSON_BRACE_INIT_COPY_SEMANTICS
    #undef JSON_PRECISE_STREAM_POSITION
+    #undef JSON_STRICT_NUL_HANDLING
 #endif

 // #include <nlohmann/thirdparty/hedley/hedley_undef.hpp>
--- a/single_include/nlohmann/json_fwd.hpp
+++ b/single_include/nlohmann/json_fwd.hpp
@@ -60,6 +60,10 @@
    #define JSON_PRECISE_STREAM_POSITION 0
 #endif

+#ifndef JSON_STRICT_NUL_HANDLING
+    #define JSON_STRICT_NUL_HANDLING 0
+#endif
+
 #if JSON_DIAGNOSTICS
    #define NLOHMANN_JSON_ABI_TAG_DIAGNOSTICS _diag
 #else
@@ -90,14 +94,20 @@
    #define NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION
 #endif

+#if JSON_STRICT_NUL_HANDLING
+    #define NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING _snul
+#else
+    #define NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING
+#endif
+
 #ifndef NLOHMANN_JSON_NAMESPACE_NO_VERSION
    #define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
 #endif

 // Construct the namespace ABI tags component
-#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e) json_abi ## a ## b ## c ## d ## e
-#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b, c, d, e) \
-    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e)
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e, f) json_abi ## a ## b ## c ## d ## e ## f
+#define NLOHMANN_JSON_ABI_TAGS_CONCAT(a, b, c, d, e, f) \
+    NLOHMANN_JSON_ABI_TAGS_CONCAT_EX(a, b, c, d, e, f)

 #define NLOHMANN_JSON_ABI_TAGS                                       \
    NLOHMANN_JSON_ABI_TAGS_CONCAT(                                   \
@@ -105,7 +115,8 @@
            NLOHMANN_JSON_ABI_TAG_LEGACY_DISCARDED_VALUE_COMPARISON, \
            NLOHMANN_JSON_ABI_TAG_DIAGNOSTIC_POSITIONS,              \
            NLOHMANN_JSON_ABI_TAG_BRACE_INIT_COPY_SEMANTICS,         \
-            NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION)
+            NLOHMANN_JSON_ABI_TAG_PRECISE_STREAM_POSITION,           \
+            NLOHMANN_JSON_ABI_TAG_STRICT_NUL_HANDLING)

 // Construct the namespace version component
 #define NLOHMANN_JSON_NAMESPACE_VERSION_CONCAT_EX(major, minor, patch) \
--- a/tests/abi/config/default.cpp
+++ b/tests/abi/config/default.cpp
@@ -40,6 +40,10 @@ TEST_CASE("default namespace")
        expected += "_psp";
 #endif

+#if JSON_STRICT_NUL_HANDLING
+        expected += "_snul";
+#endif
+
        expected += "_v" STRINGIZE(NLOHMANN_JSON_VERSION_MAJOR);
        expected += "_" STRINGIZE(NLOHMANN_JSON_VERSION_MINOR);
        expected += "_" STRINGIZE(NLOHMANN_JSON_VERSION_PATCH) "::basic_json";
--- a/tests/abi/config/noversion.cpp
+++ b/tests/abi/config/noversion.cpp
@@ -41,6 +41,10 @@ TEST_CASE("default namespace without version component")
        expected += "_psp";
 #endif

+#if JSON_STRICT_NUL_HANDLING
+        expected += "_snul";
+#endif
+
        expected += "::basic_json";

        // fallback for Clang
--- a/tests/src/unit-class_parser.cpp
+++ b/tests/src/unit-class_parser.cpp
@@ -11,11 +11,15 @@
 // capture whether JSON_STRICT_NUL_HANDLING was enabled on the command line
 // (e.g. -DJSON_STRICT_NUL_HANDLING=1) *before* including json.hpp, since the
 // library #undefs JSON_STRICT_NUL_HANDLING itself once the header has been
-// fully processed (see include/nlohmann/detail/macro_unscope.hpp)
+// fully processed unless JSON_TEST_KEEP_MACROS is defined (see
+// include/nlohmann/detail/macro_unscope.hpp)
 #if defined(JSON_STRICT_NUL_HANDLING) && (JSON_STRICT_NUL_HANDLING == 1)
    #define JSON_TEST_STRICT_NUL_HANDLING_ENABLED 1
 #endif

+#define JSON_TEST_STRINGIZE_EX(x) #x
+#define JSON_TEST_STRINGIZE(x) JSON_TEST_STRINGIZE_EX(x)
+
 #define JSON_TESTS_PRIVATE
 #include <nlohmann/json.hpp>
 using nlohmann::json;
@@ -566,6 +570,16 @@ TEST_CASE("parser class")
            // left at its default or forced to 1 (e.g. by the dedicated
            // ci_test_strict_nul_handling CI target), so only the section
            // matching the actual, compiled-in behavior can pass.
+            SECTION("the macro is part of the ABI tag")
+            {
+                const std::string ns = JSON_TEST_STRINGIZE(NLOHMANN_JSON_NAMESPACE);
+#if defined(JSON_TEST_STRICT_NUL_HANDLING_ENABLED)
+                CHECK(ns.find("_snul") != std::string::npos);
+#else
+                CHECK(ns.find("_snul") == std::string::npos);
+#endif
+            }
+
 #if !defined(JSON_TEST_STRICT_NUL_HANDLING_ENABLED)
            SECTION("default behavior (macro not enabled)")
            {
--- a/tools/generate_natvis/generate_natvis.py
+++ b/tools/generate_natvis/generate_natvis.py
@@ -20,7 +20,7 @@ if __name__ == '__main__':

    namespaces = ['nlohmann']
    abi_prefix = 'json_abi'
-    abi_tags = ['_diag', '_ldvcmp', '_dp', '_bics', '_psp']
+    abi_tags = ['_diag', '_ldvcmp', '_dp', '_bics', '_psp', '_snul']
    version = '_v' + args.version.replace('.', '_')
    inline_namespaces = []