Pin Google Benchmark to release 1.9.5

The benchmarks fetched Google Benchmark's main branch, so two builds on different days could measure with different library code, and CMake 3.30 and later warn that the single-argument FetchContent_Populate() is deprecated. Fetch the 1.9.5 release archive, verified by its SHA-256, with FetchContent_MakeAvailable() instead. That needs CMake 3.14; Google Benchmark itself already needed 3.13. Its -Werror is switched off, so a newer compiler's new warnings cannot break the pinned release, and its install rules are no longer added. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Point ci_benchmarks at tests/benchmarks
2026-09-25 17:30:32 +00:00 · 2026-09-24 09:48:18 +02:00 · 2026-09-24 07:10:37 +02:00 · 2026-09-24 07:07:59 +02:00 · 2026-09-24 06:55:21 +02:00 · 2026-09-23 20:43:40 +02:00
56 changed files with 3824 additions and 538 deletions
@@ -38,14 +38,14 @@ jobs:

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
-      uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+      uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
      with:
        languages: c-cpp

    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
    # If this step fails, then you should remove it and run the build manually (see below)
    - name: Autobuild
-      uses: github/codeql-action/autobuild@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+      uses: github/codeql-action/autobuild@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0

    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+      uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
@@ -43,6 +43,6 @@ jobs:
          output: 'flawfinder_results.sarif'

      - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
        with:
          sarif_file: ${{github.workspace}}/flawfinder_results.sarif
@@ -76,6 +76,6 @@ jobs:

      # Upload the results to GitHub's code scanning dashboard.
      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
        with:
          sarif_file: results.sarif
@@ -61,7 +61,7 @@ jobs:

      # Upload SARIF file generated in previous step
      - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
        with:
          sarif_file: semgrep.sarif
        if: always()
@@ -100,7 +100,7 @@ jobs:
    container: ubuntu:focal
    strategy:
      matrix:
-        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_simdutf]
+        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_disableenumserialization, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling]
    steps:
      - name: Install build-essential
        run: apt-get update ; apt-get install -y build-essential unzip wget git libssl-dev
@@ -59,6 +59,7 @@ option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value compar
 option(JSON_Install                        "Install CMake targets during install step." ${MAIN_PROJECT})
 option(JSON_MultipleHeaders                "Use non-amalgamated version of the library." ON)
 option(JSON_SystemInclude                  "Include as system headers (skip for clang-tidy)." OFF)
+option(JSON_StrictNulHandling              "Build with strict NUL-byte handling enabled." OFF)

 if (JSON_CI)
    include(ci)
@@ -108,6 +109,10 @@ if (JSON_Diagnostics)
    message(STATUS "Diagnostics enabled (JSON_DIAGNOSTICS=1)")
 endif()

+if (JSON_StrictNulHandling)
+    message(STATUS "Strict NUL-byte handling enabled (JSON_STRICT_NUL_HANDLING=1)")
+endif()
+
 if (JSON_Diagnostic_Positions)
    message(STATUS "Diagnostic positions enabled (JSON_DIAGNOSTIC_POSITIONS=1)")
 endif()
@@ -141,6 +146,7 @@ target_compile_definitions(
    $<$<BOOL:${JSON_Diagnostics}>:JSON_DIAGNOSTICS=1>
    $<$<BOOL:${JSON_Diagnostic_Positions}>:JSON_DIAGNOSTIC_POSITIONS=1>
    $<$<BOOL:${JSON_LegacyDiscardedValueComparison}>:JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1>
+    $<$<BOOL:${JSON_StrictNulHandling}>:JSON_STRICT_NUL_HANDLING=1>
 )

 target_include_directories(
@@ -1421,7 +1421,7 @@ I deeply appreciate the help of the following people.
 6. [Joshua C. Randall](https://github.com/jrandall) fixed a bug in the floating-point serialization.
 7. [Aaron Burghardt](https://github.com/aburgh) implemented code to parse streams incrementally. Furthermore, he greatly improved the parser class by allowing the definition of a filter function to discard undesired elements while parsing.
 8. [Daniel Kopeček](https://github.com/dkopecek) fixed a bug in the compilation with GCC 5.0.
-9. [Florian Weber](https://github.com/Florianjw) fixed a bug in and improved the performance of the comparison operators.
+9. [Fiona Johanna Weber](https://github.com/Fiona-J-W) fixed a bug in and improved the performance of the comparison operators.
 10. [Eric Cornelius](https://github.com/EricMCornelius) pointed out a bug in the handling with NaN and infinity values. He also improved the performance of the string escaping.
 11. [易思龙](https://github.com/likebeta) implemented a conversion from anonymous enums.
 12. [kepkin](https://github.com/kepkin) patiently pushed forward the support for Microsoft Visual Studio.
@@ -1523,14 +1523,14 @@ I deeply appreciate the help of the following people.
 108. [Kevin Tonon](https://github.com/ktonon) overworked the C++11 compiler checks in CMake.
 109. [Axel Huebl](https://github.com/ax3l) simplified a CMake check and added support for the [Spack package manager](https://spack.io).
 110. [Carlos O'Ryan](https://github.com/coryan) fixed a typo.
-111. [James Upjohn](https://github.com/jammehcow) fixed a version number in the compilers section.
+111. [James Upjohn](https://github.com/jupjohn) fixed a version number in the compilers section.
 112. [Chuck Atkins](https://github.com/chuckatkins) adjusted the CMake files to the CMake packaging guidelines and provided documentation for the CMake integration.
 113. [Jan Schöppach](https://github.com/dns13) fixed a typo.
 114. [martin-mfg](https://github.com/martin-mfg) fixed a typo.
 115. [Matthias Möller](https://github.com/TinyTinni) removed the dependency from `std::stringstream`.
 116. [agrianius](https://github.com/agrianius) added code to use alternative string implementations.
 117. [Daniel599](https://github.com/Daniel599) allowed to use more algorithms with the `items()` function.
-118. [Julius Rakow](https://github.com/jrakow) fixed the Meson include directory and fixed the links to [cppreference.com](https://cppreference.com).
+118. [Julius Rakow](https://github.com/juliusrakow) fixed the Meson include directory and fixed the links to [cppreference.com](https://cppreference.com).
 119. [Sonu Lohani](https://github.com/sonulohani) fixed the compilation with MSVC 2015 in debug mode.
 120. [grembo](https://github.com/grembo) fixed the test suite and re-enabled several test cases.
 121. [Hyeon Kim](https://github.com/simnalamburt) introduced the macro `JSON_INTERNAL_CATCH` to control the exception handling inside the library.
@@ -1581,7 +1581,7 @@ I deeply appreciate the help of the following people.
 166. [Mark Beckwith](https://github.com/wythe) fixed a typo.
 167. [yann-morin-1998](https://github.com/yann-morin-1998) helped to reduce the CMake requirement to version 3.1.
 168. [Konstantin Podsvirov](https://github.com/podsvirov) maintains a package for the MSYS2 software distro.
-169. [remyabel](https://github.com/remyabel) added GNUInstallDirs to the CMake files.
+169. [remyabel](https://github.com/remyabel2) added GNUInstallDirs to the CMake files.
 170. [Taylor Howard](https://github.com/taylorhoward92) fixed a unit test.
 171. [Gabe Ron](https://github.com/Macr0Nerd) implemented the `to_string` method.
 172. [Watal M. Iwasaki](https://github.com/heavywatal) fixed a Clang warning.
@@ -1608,7 +1608,7 @@ I deeply appreciate the help of the following people.
 193. [Hubert Chathi](https://github.com/uhoreg) made CMake's version config file architecture-independent.
 194. [OmnipotentEntity](https://github.com/OmnipotentEntity) implemented the binary values for CBOR, MessagePack, BSON, and UBJSON.
 195. [ArtemSarmini](https://github.com/ArtemSarmini) fixed a compilation issue with GCC 10 and fixed a leak.
-196. [Evgenii Sopov](https://github.com/sea-kg) integrated the library to the wsjcpp package manager.
+196. [Evgenii Sopov](https://github.com/sea5kg) integrated the library to the wsjcpp package manager.
 197. [Sergey Linev](https://github.com/linev) fixed a compiler warning.
 198. [Miguel Magalhães](https://github.com/magamig) fixed the year in the copyright.
 199. [Gareth Sylvester-Bradley](https://github.com/garethsb-sony) fixed a compilation issue with MSVC.
@@ -1702,7 +1702,7 @@ I deeply appreciate the help of the following people.
 287. [NN](https://github.com/NN---) added the Visual Studio output directory to `.gitignore`.
 288. [Romain Reignier](https://github.com/romainreignier) improved the performance of the vector output adapter.
 289. [Mike](https://github.com/Mike-Leo-Smith) fixed the `std::iterator_traits`.
-290. [Richard Hozák](https://github.com/zxey) added macro `JSON_NO_ENUM` to disable default enum conversions.
+290. [Richard Hozák](https://github.com/richardhozak) added macro `JSON_NO_ENUM` to disable default enum conversions.
 291. [vakokako](https://github.com/vakokako) fixed tests when compiling with C++20.
 292. [Alexander “weej” Jones](https://github.com/alexweej) fixed an example in the README.
 293. [Eli Schwartz](https://github.com/eli-schwartz) added more files to the `include.zip` archive.
@@ -1727,7 +1727,7 @@ I deeply appreciate the help of the following people.
 312. [Gareth Sylvester-Bradley](https://github.com/garethsb) added `operator/=` and `operator/` to construct JSON pointers.
 313. [Michael Macnair](https://github.com/mykter) added support for afl-fuzz testing.
 314. [Berkus Decker](https://github.com/berkus) fixed a typo in the README.
-315. [Illia Polishchuk](https://github.com/effolkronium) improved the CMake testing.
+315. [Illia Polishchuk](https://github.com/ilqvya) improved the CMake testing.
 316. [Ikko Ashimine](https://github.com/eltociear) fixed a typo.
 317. [Raphael Grimm](https://github.com/barcode) added the possibility to define a custom base class.
 318. [tocic](https://github.com/tocic) fixed typos in the documentation.
@@ -1797,6 +1797,66 @@ I deeply appreciate the help of the following people.
 382. [bitFiedler](https://github.com/bitFiedler) made GDB pretty printer work with Python 3.8.
 383. [Gianfranco Costamagna](https://github.com/LocutusOfBorg) fixed a compiler warning.
 384. [risa2000](https://github.com/risa2000) made `std::filesystem::path` conversion to/from UTF-8 encoded string explicit.
+385. [AM](https://github.com/maqnouch) fixed typos in the README.
+386. [dmenendez-gruposantander](https://github.com/dmenendez-gruposantander) fixed typos in the comments of the examples.
+387. [Mihai Stan](https://github.com/mstan-xx) fixed comparisons against the literal `0`.
+388. [Matt Gumbel](https://github.com/intelmatt) fixed some `-Weffc++` warnings.
+389. [vimpunk](https://github.com/vimpunk) moved a lambda out of an unevaluated context to support older compilers.
+390. [Chris Harris](https://github.com/cjh1) fixed the compilation with GCC 4.8.
+391. [Palmer Dabbelt](https://github.com/palmer-dabbelt) generated and installed a pkg-config file.
+392. [Gus Pozuelo](https://github.com/ap-viavi) made `ordered_map` compatible with GCC 5.5, Clang 3.6, and Xcode 9.
+393. [AK](https://github.com/Lioncky) fixed an MSVC build error caused by the `min`/`max` macros from `windows.h`.
+394. [Sergiu Deitsch](https://github.com/sergiud) provided a fallback for missing `char8_t` support.
+395. [Xiaochuan Ye](https://github.com/XueSongTap) fixed `from_msgpack` for `std::byte` input by specializing `std::char_traits`.
+396. [Ville Vesilehto](https://github.com/thevilledev) fixed an overflow in the BJData size calculation and rejected overflowing negative integers in CBOR.
+397. [NmPassTHFan](https://github.com/nmpassthf) replaced the deprecated `std::is_trivial` for C++26.
+398. [Chris Ever](https://github.com/chirsz-ever) added the `ignore_trailing_commas` parser option.
+399. [Kuan-Fu Wu](https://github.com/kfwu1999) fixed the example code for `json_pointer` initialization.
+400. [David Kilzer](https://github.com/ddkilzer) added a missing header to the input adapters.
+401. [Miko](https://github.com/mikomikotaishi) added proper C++20 module support, simplified the module API, and fixed missing exports.
+402. [hitgirl](https://github.com/hitgil) fixed the CMake configuration when cross-compiling.
+403. [Devon Thomas](https://github.com/ThomaDevOSU) mentioned the Artistic Style formatting in the contribution guidelines.
+404. [Erik Hu](https://github.com/Erikhu1) made Coveralls upload errors non-fatal in the CI.
+405. [co63oc](https://github.com/co63oc) fixed typos.
+406. [DmitriBogdanov](https://github.com/DmitriBogdanov) fixed broken package manager links in the documentation.
+407. [Bander](https://github.com/banderzhm) improved the MSVC compatibility of the C++ modules.
+408. [Andy Choi](https://github.com/ccpong) removed an unnecessary `template` keyword before `get` in the README and the documentation.
+409. [SamareshSingh](https://github.com/ssam18) fixed single-element brace initialization to copy/move instead of wrapping in an array, fixed the `WITH_DEFAULT` macros for `ordered_map`, and handled moved events in `serve_header.py`.
+410. [Aditya](https://github.com/Lumowhisp) improved the documentation of the documentation generation.
+411. [cheese1](https://github.com/cheese1) clarified the README.
+412. [KhloodElhossiny](https://github.com/khloodelhossiny) enabled `std::string_view` keys in `operator[]`.
+413. [Charles Cabergs](https://github.com/cacharle) fixed a `-Wtautological-constant-out-of-range-compare` warning.
+414. [EALePain](https://github.com/EALePain) made the `std::tuple` conversion work with reference types such as `std::tie`.
+415. [koala_oishi](https://github.com/chibi-dogs) fixed grammatical wording in the README.
+416. [riccardoori11](https://github.com/riccardoori11) fixed a typo in the documentation.
+417. [Swastik Bose](https://github.com/VasuBhakt) fixed the parent pointers after `update()` with `JSON_DIAGNOSTICS` and fixed the Doxygen autolinking of requirements.
+418. [trdesilva](https://github.com/trdesilva) added `front`, `pop_front`, and `push_front` to `json_pointer`.
+419. [Akhilesh Arora](https://github.com/akhilesharora) fixed an incomplete-type error with `ordered_json`.
+420. [Hariom Phulre](https://github.com/hariomphulre) fixed the C++20 modules compilation with GCC.
+421. [Kirill Lokotkov](https://github.com/RUSLoker) fixed printing `long double` values.
+422. [George Sedov](https://github.com/radistmorse) added the `NLOHMANN_DEFINE_TYPE_*_WITH_NAMES` macros.
+423. [Caillin Nugent](https://github.com/nugentcaillin) added the `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT` macro.
+424. [Cosmin D.](https://github.com/drcosmin) fixed `std::filesystem::path` conversions and added an MSVC workaround for `std::unique_ptr`.
+425. [Paul Dreik](https://github.com/pauldreik) fixed a test relying on implementation-specific behavior.
+426. [Daniel Falk](https://github.com/daniel-falk) added missing copyright notices to the SBOM.
+427. [Federico Sfriso](https://github.com/federicosfriso05-dotcom) added support for constructing JSON values from C++20 range views.
+428. [Luke Banicevic](https://github.com/banaboi) fixed corrupt BSON output for lengths exceeding `INT32_MAX`, cleaned up the BSON writer, and improved the documentation.
+429. [Patrick Armstrong](https://github.com/Patrick10199) updated the CBOR references and the half-precision float assertions.
+430. [Yash Bavadiya](https://github.com/xevrion) added checks to all BSON reads.
+431. [hum4nBeing](https://github.com/hum4nBeing) fixed the overflow handling of high-precision numbers in UBJSON.
+432. [tomatotomata](https://github.com/tomatotomata) added checks for reading CBOR tagged subtypes.
+433. [YingqiDuan](https://github.com/YingqiDuan) documented the BSON interoperability.
+434. [KBS](https://github.com/youdie006) documented the standards compliance and the strictness of `parse()` and `operator>>`.
+435. [Petr Bělohlávek](https://github.com/petrbel) added Clang 21 and 22 to the CI.
+436. [Dmitry Rantovov](https://github.com/darkdi) fixed the placement of a CBOR documentation block.
+437. [ljcjclljc](https://github.com/ljcjclljc) fixed the comparison of large unsigned integers with signed integers.
+438. [Sahil Kamate](https://github.com/sahilkamate03) fixed the handling of CBOR tags 0-5 and 21-23.
+439. [Krishnanand G](https://github.com/Krishnanand-G) made the UBJSON writer reject `use_type` without `use_size`.
+440. [whn](https://github.com/Whning0513) documented the lenient BSON input handling and corrected the complexity of `to_bson`.
+441. [elix3r](https://github.com/22elix3r) fixed `update()` with `merge_objects` when merging a primitive into an object.
+442. [Avionic Harshit](https://github.com/avionicharshit-byte) made `diff()` linear when an array shrinks.
+443. [Qatadaha Bin Matloob](https://github.com/qatcod) fixed comparisons between integers and floats and fixed unparsable BJData output.
+444. [Wu Shuwen](https://github.com/dajiaohuang) removed an unused include.

 Thanks a lot for helping out! Please [let me know](mailto:mail@nlohmann.me) if I forgot someone.

@@ -245,6 +245,23 @@ add_custom_target(ci_test_brace_init_copy_semantics
    COMMENT "Compile and test with brace-init copy semantics enabled"
 )

+###############################################################################
+# Enable strict NUL-byte handling.
+###############################################################################
+
+add_custom_target(ci_test_strict_nul_handling
+    COMMAND ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_StrictNulHandling=ON
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_strict_nul_handling
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_strict_nul_handling
+    # unit-testsuites contains a fixture (a "1e308" test value) that relies on the
+    # legacy NUL-as-end-of-input behavior this macro disables; exclude it here, as
+    # it is expected to fail under strict NUL handling and is out of scope for it
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_strict_nul_handling && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure -E "test-testsuites"
+    COMMENT "Compile and test with strict NUL-byte handling enabled"
+)
+
 ###############################################################################
 # Disable global UDLs.
 ###############################################################################
@@ -260,6 +277,40 @@ add_custom_target(ci_test_noglobaludls
    COMMENT "Compile and test with global UDLs disabled"
 )

+###############################################################################
+# Disable enum serialization.
+###############################################################################
+
+add_custom_target(ci_test_disableenumserialization
+    COMMAND ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_DisableEnumSerialization=ON
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_disableenumserialization
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_disableenumserialization
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_disableenumserialization && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test with enum serialization disabled"
+)
+
+###############################################################################
+# Skip the multiple-inclusion library version check.
+###############################################################################
+
+# tests/src/skip_library_version_check.cpp deliberately simulates a scenario
+# (mixing two differently-versioned inclusions of the library in one
+# translation unit) that unavoidably triggers the compiler's own "macro
+# redefined" warning, so -- unlike the ci_test_* targets above -- it is
+# compiled directly here, with a modest warning set, instead of being folded
+# into the library's own -Weverything/-Werror unit test matrix.
+add_custom_target(ci_test_skiplibraryversioncheck
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${PROJECT_BINARY_DIR}/skip_library_version_check
+    COMMAND ${CMAKE_CXX_COMPILER} -std=c++11 -Wall -Wextra
+        -I${PROJECT_SOURCE_DIR}/include
+        ${PROJECT_SOURCE_DIR}/tests/src/skip_library_version_check.cpp
+        -o ${PROJECT_BINARY_DIR}/skip_library_version_check/skip_library_version_check
+    COMMAND ${PROJECT_BINARY_DIR}/skip_library_version_check/skip_library_version_check
+    COMMENT "Compile and run a translation unit simulating a mismatched library version, with JSON_SKIP_LIBRARY_VERSION_CHECK defined"
+)
+
 ###############################################################################
 # Coverage.
 ###############################################################################
@@ -564,7 +615,7 @@ add_custom_target(ci_single_binaries
 add_custom_target(ci_benchmarks
    COMMAND ${CMAKE_COMMAND}
        -DCMAKE_BUILD_TYPE=Release -GNinja
-        -S${PROJECT_SOURCE_DIR}/benchmarks -B${PROJECT_BINARY_DIR}/build_benchmarks
+        -S${PROJECT_SOURCE_DIR}/tests/benchmarks -B${PROJECT_BINARY_DIR}/build_benchmarks
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_benchmarks --target json_benchmarks
    COMMAND cd ${PROJECT_BINARY_DIR}/build_benchmarks && ./json_benchmarks
    COMMENT "Run benchmarks"
@@ -77,7 +77,7 @@ if(CMAKE_CROSSCOMPILING)
 endif()
 if(NOT DEFINED LIBCPP_VERSION_OUTPUT_CACHED)
    try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
-        "${CMAKE_BINARY_DIR}" SOURCES "${CMAKE_SOURCE_DIR}/cmake/detect_libcpp_version.cpp"
+        "${CMAKE_BINARY_DIR}" SOURCES "${CMAKE_CURRENT_LIST_DIR}/detect_libcpp_version.cpp"
        RUN_OUTPUT_VARIABLE LIBCPP_VERSION_OUTPUT
        COMPILE_OUTPUT_VARIABLE LIBCPP_VERSION_COMPILE_OUTPUT
    )
@@ -90,6 +90,10 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.

 A UTF-8 byte order mark is silently ignored.

+By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input, rather than as an ordinary (and,
+outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for details and the
+[`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) macro to opt into rejecting it instead.
+
 ## Examples

 ??? example
@@ -111,6 +115,8 @@ A UTF-8 byte order mark is silently ignored.
 - [parse](parse.md) - deserialize from a compatible input
 - [sax_parse](sax_parse.md) - parse input using the SAX interface
 - [operator>>](../operator_gtgt.md) - deserialize from stream
+- [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) - opt in to rejecting a NUL byte in the input
+  instead of treating it as end of input

 ## Version history

@@ -120,6 +126,8 @@ A UTF-8 byte order mark is silently ignored.
 - Added `ignore_trailing_commas` in version 3.13.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 to optionally reject a NUL byte in the input instead of treating
+  it as end of input; planned to become the default in version 4.0.0.

 !!! warning "Deprecation"

@@ -88,6 +88,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
      do not belong to the same JSON value; example: `"iterators do not fit"`
    - Throws [`invalid_iterator.211`](../../home/exceptions.md#jsonexceptioninvalid_iterator211) if `first` or `last`
      are iterators into container for which insert is called; example: `"passed iterators may not belong to container"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if `first` or `last`
+      do not point to an array; example: `"iterators first and last must point to arrays"`
 4. The function can throw the following exceptions:
    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
      arrays; example: `"cannot use insert() with string"`
@@ -103,6 +103,10 @@ A UTF-8 byte order mark is silently ignored.
 Invalid Unicode escapes and unpaired surrogates in the input are reported as
 [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) with a detailed message.

+By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input, rather than as an ordinary (and,
+outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for details and the
+[`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) macro to opt into rejecting it instead.
+
 ## Examples

 ??? example "Parsing from a character array"
@@ -236,6 +240,8 @@ Invalid Unicode escapes and unpaired surrogates in the input are reported as
 - [accept](accept.md) - check if the input is valid JSON
 - [sax_parse](sax_parse.md) - parse input using the SAX interface
 - [operator>>](../operator_gtgt.md) - deserialize from stream
+- [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) - opt in to rejecting a NUL byte in the input
+  instead of treating it as end of input

 ## Version history

@@ -246,6 +252,8 @@ Invalid Unicode escapes and unpaired surrogates in the input are reported as
 - Added `ignore_trailing_commas` in version 3.13.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 to optionally reject a NUL byte in the input instead of treating
+  it as end of input; planned to become the default in version 4.0.0.

 !!! warning "Deprecation"

@@ -14,6 +14,11 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_DIAGNOSTIC_POSITIONS**](json_diagnostic_positions.md) - access positions of elements
 - [**JSON_NOEXCEPTION**](json_noexception.md) - switch off exceptions

+## Parsing
+
+- [**JSON_STRICT_NUL_HANDLING**](json_strict_nul_handling.md) - opt in to rejecting a NUL byte in the input instead of
+  treating it as end of input
+
 ## Language support

 - [**JSON_HAS_CPP_11**<br>**JSON_HAS_CPP_14**<br>**JSON_HAS_CPP_17**<br>**JSON_HAS_CPP_20**](json_has_cpp_11.md) - set supported C++ standard
@@ -0,0 +1,126 @@
+# JSON_STRICT_NUL_HANDLING
+
+```cpp
+#define JSON_STRICT_NUL_HANDLING /* value */
+```
+
+When defined to `1`, a `'\0'` (NUL) byte in JSON text input is rejected with `parse_error.101`, like any other
+unexpected byte, instead of being silently treated as end of input.
+
+The macro only affects the JSON text parser ([`parse`](../basic_json/parse.md), [`accept`](../basic_json/accept.md),
+[`sax_parse`](../basic_json/sax_parse.md), and [`operator>>`](../operator_gtgt.md)). There are three cases where a NUL
+byte is still not rejected:
+
+- The binary formats ([`from_bjdata`](../basic_json/from_bjdata.md), [`from_bson`](../basic_json/from_bson.md),
+  [`from_cbor`](../basic_json/from_cbor.md), [`from_msgpack`](../basic_json/from_msgpack.md),
+  [`from_ubjson`](../basic_json/from_ubjson.md)) are never affected: there, `0x00` is ordinary data.
+- A bare `const char*` pointer has no length of its own, so its length is still determined with `strlen()`. The first
+  NUL byte therefore still marks the end of the input, and nothing after it is read.
+- One trailing `'\0'` at the end of a `char` array (e.g., a string literal) is trimmed; see the warning below.
+
+## Default definition
+
+The default value is `0` (disabled — existing behavior is preserved).
+
+```cpp
+#define JSON_STRICT_NUL_HANDLING 0
+```
+
+## Notes
+
+!!! note "Background"
+
+    By default, a `'\0'` byte anywhere in the input is treated the same as the real end of the input, rather than as
+    an ordinary (and, outside of a string, invalid) byte. Everything from that byte onward is silently ignored,
+    without a parse error - including further, otherwise well-formed JSON:
+
+    ```cpp
+    json::parse(std::string("123") + '\0');          // == 123, no error
+    json::parse(std::string("123") + '\0' + "true"); // == 123, the "true" is silently ignored too
+    ```
+
+    This falls out of the same convention used when no explicit input length is given at all: parsing from a
+    `const char*` already stops at the first NUL byte via `strlen()`, since a bare pointer has no length of its own.
+    The library applies that same NUL-terminated-C-string convention uniformly, rather than only when a length is
+    genuinely unavailable - so a `std::string`, iterator range, or container whose content happens to include a NUL
+    byte is affected the same way a raw `const char*` would be (see the
+    [FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for a fuller explanation).
+
+    This was not fixed unconditionally, because doing so is backwards-incompatible for any caller who happens to
+    depend on the current behavior - even unknowingly, for instance because their input already contains trailing
+    padding they never noticed was being discarded (see [#5530](https://github.com/nlohmann/json/issues/5530)).
+    This macro instead offers an opt-in path to the corrected behavior ahead of version 4.0.0, where it is planned to
+    become the default.
+
+!!! warning "Opt-in only"
+
+    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
+    effect.
+
+    Enabling it also changes how a `char` array (including a string literal, e.g. `json::parse("123")`) is read: such
+    an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With this macro
+    enabled, that one trailing byte is trimmed if present so that parsing a string literal keeps working; every other
+    byte in the array - including any `'\0'` that is not the very last element - is read as real data and rejected
+    like any other unexpected byte. Arrays of any other element type (`unsigned char`, `std::uint8_t`, ...), as used
+    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.
+
+!!! tip "Workaround without the macro"
+
+    To reject a NUL byte without enabling this macro, trim your input yourself before calling `parse()`:
+
+    ```cpp
+    s.resize(s.find('\0')); // drop everything from the first NUL onward, if any
+    json::parse(s);
+    ```
+
+## Examples
+
+??? example "Default behavior (macro not defined)"
+
+    Without the macro, a NUL byte silently ends parsing at that point:
+
+    ```cpp
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        json j = json::parse(std::string("123") + '\0' + "true");
+        // j is 123 -- the '\0' and everything after it is silently ignored
+    }
+    ```
+
+??? example "Opt-in strict handling (macro defined to 1)"
+
+    With the macro, a NUL byte is rejected like any other unexpected byte:
+
+    ```cpp
+    #define JSON_STRICT_NUL_HANDLING 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        json j = json::parse(std::string("123") + '\0' + "true");
+        // throws parse_error.101 -- the NUL byte is now invalid input,
+        // exactly like any other unexpected trailing byte
+
+        json ok = json::parse("123");
+        // ok is 123 -- parsing from a string literal still works
+    }
+    ```
+
+## See also
+
+- [FAQ: NUL bytes in the input](../../home/faq.md#nul-bytes-in-the-input)
+- [**parse**](../basic_json/parse.md) - deserialize from a compatible input
+- [**accept**](../basic_json/accept.md) - check if the input is valid JSON
+- [**operator>>**](../operator_gtgt.md) - deserialize from stream
+
+## Version history
+
+- Added in version 3.13.0.
+- Planned to become the default (with the macro removed) in version 4.0.0.
@@ -72,6 +72,13 @@ input >> j2;  // parses the next value
 Note that reading concatenated values does **not** work for [JSON Lines](../features/parsing/json_lines.md)
 (newline-delimited JSON) input -- see that page for why and for the recommended alternative.

+By default, a `'\0'` (NUL) byte encountered while reading a value is treated as end of input, rather than as an
+ordinary (and, outside of a string, invalid) byte; see the [FAQ entry](../home/faq.md#nul-bytes-in-the-input) for
+details and the [`JSON_STRICT_NUL_HANDLING`](macros/json_strict_nul_handling.md) macro to opt into rejecting it
+instead. Because `operator>>` only parses a single value and does not require the rest of the stream to be consumed,
+a NUL byte *after* a complete value has no effect on `operator>>` either way; it only matters while a value is still
+being read.
+
 !!! warning "Deprecation"

    This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
@@ -98,7 +105,11 @@ Note that reading concatenated values does **not** work for [JSON Lines](../feat

 - [accept](basic_json/accept.md) - check if the input is valid JSON
 - [parse](basic_json/parse.md) - deserialize from a compatible input
+- [`JSON_STRICT_NUL_HANDLING`](macros/json_strict_nul_handling.md) - opt in to rejecting a NUL byte in the input
+  instead of treating it as end of input

 ## Version history

 - Added in version 1.0.0.
+- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 to optionally reject a NUL byte in the input instead of treating
+  it as end of input; planned to become the default in version 4.0.0.
@@ -105,6 +105,19 @@ using the library with compilers that do not fully support C++11 and may only wo

 See [full documentation of `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`](../api/macros/json_skip_unsupported_compiler_check.md).

+## `JSON_STRICT_NUL_HANDLING`
+
+When defined to `1`, a `'\0'` (NUL) byte anywhere in the input is rejected with `parse_error.101`, like any other
+unexpected byte, instead of being silently treated as end of input (see the
+[FAQ entry](../home/faq.md#nul-bytes-in-the-input) for background). The default value is `0`, which preserves the
+existing behavior; this is planned to become the default in version 4.0.0.
+
+The strict handling can also be enabled with the CMake option
+[`JSON_StrictNulHandling`](../integration/cmake.md#json_strictnulhandling) (`OFF` by default) which sets
+`JSON_STRICT_NUL_HANDLING` accordingly.
+
+See [full documentation of `JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md).
+
 ## `JSON_THROW_USER(exception)`

 This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown.
@@ -970,6 +970,21 @@ A JSON Patch `move` operation's `"from"` location is a proper prefix of its `"pa

    This exception was added in version 3.13.0. Before that, this situation could succeed with a corrupted result: for an array target, removing the "from" element before the "add" step shifted subsequent indices, so "path" silently re-resolved to a different element than intended.

+### json.exception.out_of_range.415
+
+MessagePack's ext type and BSON's binary subtype are each stored in a single byte. This exception is thrown when serializing a
+[`byte_container_with_subtype`](../api/byte_container_with_subtype/index.md) whose subtype exceeds 255.
+
+!!! failure "Example message"
+
+    ```
+    [json.exception.out_of_range.415] subtype 70000 is too large for the MessagePack ext type (max 255)
+    ```
+
+!!! note
+
+    This exception was added in version 3.13.0. Before that, subtypes above 255 were silently truncated modulo 256 instead of raising an error.
+
 ## Further exceptions

 This exception is thrown in case of errors that cannot be classified with the
@@ -90,6 +90,54 @@ The library supports **Unicode input** as follows:
 In most cases, the parser is right to complain, because the input is not UTF-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or ISO 8859-1 is often the standard encoding.


+### NUL bytes in the input
+
+!!! question "Questions"
+
+    - Why does `json::parse()` silently ignore part of my input?
+    - Why does a `std::string`/buffer with extra data after the JSON text parse without error, while a similar-looking string with extra text does not?
+
+A `'\0'` (NUL) byte anywhere in the input is treated the same as the real end of the input, rather than as an ordinary (and, outside of a string, invalid) byte. Everything from that byte onward is silently ignored, without a parse error — including further, otherwise well-formed JSON:
+
+```cpp
+json::parse(std::string("123") + '\0');          // == 123, no error
+json::parse(std::string("123") + '\0' + "true"); // == 123, the "true" is silently ignored too
+```
+
+This is different from any other unexpected trailing byte, which *does* raise [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101):
+
+```cpp
+json::parse("123x"); // throws parse_error.101: unexpected additional data
+```
+
+This falls out of the same convention used when no explicit input length is given at all: `json::parse(const char*)` already stops at the first NUL byte via `strlen()`, since a bare pointer has no length of its own. The library applies that same NUL-terminated-C-string convention uniformly, rather than only when a length is genuinely unavailable — so a `std::string`, iterator range, or container whose content happens to include a NUL byte is affected the same way a raw `const char*` would be.
+
+If your input may contain a trailing or embedded NUL that is **not** meant to signal the end of the JSON text — for instance, a fixed-size, zero-padded buffer — trim it yourself before calling `parse()`, since the library will otherwise silently stop there instead of raising an error:
+
+```cpp
+s.resize(s.find('\0')); // drop everything from the first NUL onward, if any
+json::parse(s);
+```
+
+**Opt-in strict handling (since version 3.13.0)**
+
+Manually trimming every input is easy to forget. If you define [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md) to `1` before including the library, a `'\0'` byte is instead rejected like any other unexpected byte and raises `parse_error.101`, instead of being treated as end of input:
+
+```cpp
+#define JSON_STRICT_NUL_HANDLING 1
+#include <nlohmann/json.hpp>
+
+json::parse(std::string("123") + '\0'); // throws parse_error.101 instead of silently returning 123
+```
+
+This macro defaults to `0` (disabled, preserving the behavior described above) to avoid breaking existing code that may depend on it, even unknowingly; it is planned to become the default in version 4.0.0. See [its documentation](../api/macros/json_strict_nul_handling.md) for details, including how it also affects `char` arrays such as string literals.
+
+Note that this is unrelated to an *unescaped* NUL byte occurring **inside** a quoted JSON string, which is a different, already-invalid case and is correctly rejected either way:
+
+```cpp
+json::parse(std::string("\"") + '\0' + "\""); // throws parse_error.101: control character U+0000 (NUL) must be escaped to \u0000
+```
+
 ### Wide string handling

 !!! question
@@ -198,6 +198,11 @@ Use the non-amalgamated version of the library. This option is `ON` by default.

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

+### `JSON_StrictNulHandling`
+
+Reject a `'\0'` (NUL) byte in the input instead of treating it as end of input, by defining the macro
+[`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md). This option is `OFF` by default.
+
 ### `JSON_Valgrind`

 Execute the test suite with [Valgrind](https://valgrind.org). This option is `OFF` by default. Depends on `JSON_BuildTests`.
@@ -294,6 +294,7 @@ nav:
          - 'JSON_NO_IO': api/macros/json_no_io.md
          - 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md
          - 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
+          - 'JSON_STRICT_NUL_HANDLING': api/macros/json_strict_nul_handling.md
          - 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md
          - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
          - 'JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON': api/macros/json_use_legacy_discarded_value_comparison.md
@@ -1,7 +1,7 @@
 wheel==0.48.0

 mkdocs==1.6.1                                       # documentation framework
-mkdocs-git-revision-date-localized-plugin==1.5.4    # plugin "git-revision-date-localized"
+mkdocs-git-revision-date-localized-plugin==1.6.0    # plugin "git-revision-date-localized"
 mkdocs-material==9.7.7                             # theme for mkdocs
 mkdocs-material-extensions==1.3.1                   # extensions
 mkdocs-minify-plugin==0.8.0                         # plugin "minify"
@@ -762,6 +762,21 @@ contiguous_bytes_input_adapter input_adapter(CharT b)
 template<typename T, std::size_t N>
 auto input_adapter(T (&array)[N]) -> decltype(input_adapter(array, array + N)) // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
 {
+#if JSON_STRICT_NUL_HANDLING
+    // A `char` array from string-literal initialization (e.g. json::parse("123"))
+    // carries a trailing '\0' contributed by the compiler, not by the source
+    // text; drop exactly that one byte so it is not mistaken for real trailing
+    // data. Every other element type (unsigned char, std::uint8_t, ...) keeps
+    // the full extent unconditionally, since a trailing zero byte there is
+    // genuine data (e.g. CBOR/MessagePack). This intentionally does not
+    // strlen()-scan the array (as the pointer overload above does for a
+    // null-delimited string): for a `char` array that is not NUL-terminated
+    // within its bounds, that would read past the end of the array.
+    if (std::is_same<typename std::remove_cv<T>::type, char>::value && N > 0 && array[N - 1] == 0)
+    {
+        return input_adapter(array, array + N - 1);
+    }
+#endif
    return input_adapter(array, array + N);
 }

@@ -8,11 +8,11 @@

 #pragma once

-#include <algorithm> // min
+#include <algorithm> // find_if, min
 #include <cstddef>
 #include <string> // string
 #include <type_traits> // enable_if_t
-#include <utility> // move
+#include <utility> // move, pair
 #include <vector> // vector

 #include <nlohmann/detail/exceptions.hpp>
@@ -278,7 +278,7 @@ class json_sax_dom_parser

        if (JSON_HEDLEY_UNLIKELY(len != detail::unknown_size() && len > ref_stack.back()->max_size()))
        {
-            JSON_THROW(out_of_range::create(408, concat("excessive object size: ", std::to_string(len)), ref_stack.back()));
+            return parse_error(0, "", out_of_range::create(408, concat("excessive object size: ", std::to_string(len)), ref_stack.back()));
        }

        return true;
@@ -327,7 +327,7 @@ class json_sax_dom_parser

        if (JSON_HEDLEY_UNLIKELY(len != detail::unknown_size() && len > ref_stack.back()->max_size()))
        {
-            JSON_THROW(out_of_range::create(408, concat("excessive array size: ", std::to_string(len)), ref_stack.back()));
+            return parse_error(0, "", out_of_range::create(408, concat("excessive array size: ", std::to_string(len)), ref_stack.back()));
        }

        if (len != detail::unknown_size())
@@ -611,7 +611,7 @@ class json_sax_dom_callback_parser
            // check object limit
            if (JSON_HEDLEY_UNLIKELY(len != detail::unknown_size() && len > ref_stack.back()->max_size()))
            {
-                JSON_THROW(out_of_range::create(408, concat("excessive object size: ", std::to_string(len)), ref_stack.back()));
+                return parse_error(0, "", out_of_range::create(408, concat("excessive object size: ", std::to_string(len)), ref_stack.back()));
            }
        }
        return true;
@@ -631,7 +631,17 @@ class json_sax_dom_callback_parser
        // add discarded value at the given key and store the reference for later
        if (keep && ref_stack.back())
        {
-            object_element = &(ref_stack.back()->m_data.m_value.object->operator[](val) = discarded);
+            auto& obj = *ref_stack.back()->m_data.m_value.object;
+            const auto it = obj.find(val);
+            if (it != obj.end())
+            {
+                // this is a duplicate key (legal in JSON); remember its
+                // current value so it can be restored later if the new
+                // value is rejected by the callback, instead of being
+                // erased together with the discarded placeholder
+                duplicate_key_stash.emplace_back(&(it->second), it->second);
+            }
+            object_element = &(obj[val] = discarded);
        }

        return true;
@@ -643,13 +653,18 @@ class json_sax_dom_callback_parser
        {
            if (!callback(static_cast<int>(ref_stack.size()) - 1, parse_event_t::object_end, *ref_stack.back()))
            {
-                // discard object
-                *ref_stack.back() = discarded;
+                // discard object, unless this slot holds a duplicate key's
+                // previous value pending restoration, in which case that
+                // value is restored instead of being discarded
+                if (!resolve_duplicate_key_stash(ref_stack.back(), true))
+                {
+                    *ref_stack.back() = discarded;

 #if JSON_DIAGNOSTIC_POSITIONS
-                // Set start/end positions for discarded object.
-                handle_diagnostic_positions_for_json_value(*ref_stack.back());
+                    // Set start/end positions for discarded object.
+                    handle_diagnostic_positions_for_json_value(*ref_stack.back());
 #endif
+                }
            }
            else
            {
@@ -663,6 +678,10 @@ class json_sax_dom_callback_parser
 #endif

                ref_stack.back()->set_parents();
+                // this object is finally, definitively kept; drop any
+                // pending duplicate-key stash entry for its slot since it
+                // can no longer be restored
+                resolve_duplicate_key_stash(ref_stack.back(), false);
            }
        }

@@ -711,7 +730,7 @@ class json_sax_dom_callback_parser
            // check array limit
            if (JSON_HEDLEY_UNLIKELY(len != detail::unknown_size() && len > ref_stack.back()->max_size()))
            {
-                JSON_THROW(out_of_range::create(408, concat("excessive array size: ", std::to_string(len)), ref_stack.back()));
+                return parse_error(0, "", out_of_range::create(408, concat("excessive array size: ", std::to_string(len)), ref_stack.back()));
            }

            if (len != detail::unknown_size())
@@ -743,16 +762,25 @@ class json_sax_dom_callback_parser
 #endif

                ref_stack.back()->set_parents();
+                // this array is finally, definitively kept; drop any
+                // pending duplicate-key stash entry for its slot since it
+                // can no longer be restored
+                resolve_duplicate_key_stash(ref_stack.back(), false);
            }
            else
            {
-                // discard array
-                *ref_stack.back() = discarded;
+                // discard array, unless this slot holds a duplicate key's
+                // previous value pending restoration, in which case that
+                // value is restored instead of being discarded
+                if (!resolve_duplicate_key_stash(ref_stack.back(), true))
+                {
+                    *ref_stack.back() = discarded;

 #if JSON_DIAGNOSTIC_POSITIONS
-                // Set start/end positions for discarded array.
-                handle_diagnostic_positions_for_json_value(*ref_stack.back());
+                    // Set start/end positions for discarded array.
+                    handle_diagnostic_positions_for_json_value(*ref_stack.back());
 #endif
+                }
            }
        }

@@ -869,6 +897,35 @@ class json_sax_dom_callback_parser
    }
 #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
+    /// new value at that slot was rejected); otherwise the stash entry is
+    /// simply dropped (use this when the new value was accepted, so it
+    /// correctly supersedes the old one and no restore should ever happen
+    /// for this slot again)
+    /// @return whether a matching stash entry was found (and processed)
+    bool resolve_duplicate_key_stash(BasicJsonType* slot, bool restore_value)
+    {
+        const auto it = std::find_if(duplicate_key_stash.begin(), duplicate_key_stash.end(),
+                                     [slot](const std::pair<BasicJsonType*, BasicJsonType>& entry)
+        {
+            return entry.first == slot;
+        });
+
+        if (it == duplicate_key_stash.end())
+        {
+            return false;
+        }
+
+        if (restore_value)
+        {
+            *slot = std::move(it->second);
+        }
+        duplicate_key_stash.erase(it);
+        return true;
+    }
+
    /*!
    @brief the key the value now being handled will be stored under

@@ -887,7 +944,9 @@ class json_sax_dom_callback_parser
    }

    /*!
-    @brief remove the discarded value the callback rejected from its parent
+    @brief remove the discarded value the callback rejected from its parent,
+    unless it is a duplicate key's slot with a stashed previous value, in
+    which case that previous value is restored instead

    A rejected value can only ever be the one most recently added to @a parent:
    the last element of an array, or the placeholder key() stored under @a key
@@ -902,7 +961,7 @@ class json_sax_dom_callback_parser
    @param[in,out] parent  the container to remove the rejected value from
    @param[in] key  the key the value was stored under; unused for arrays
    */
-    static void remove_discarded_value(BasicJsonType& parent, const string_t& key)
+    void remove_discarded_value(BasicJsonType& parent, const string_t& key)
    {
        if (parent.is_array())
        {
@@ -918,7 +977,12 @@ class json_sax_dom_callback_parser
            const auto it = object.find(key);
            if (it != object.end() && it->second.is_discarded())
            {
-                object.erase(it);
+                // a duplicate key's slot has a stashed previous value that
+                // must be restored instead of being erased
+                if (!resolve_duplicate_key_stash(&it->second, true))
+                {
+                    object.erase(it);
+                }
            }
        }
    }
@@ -1020,6 +1084,16 @@ class json_sax_dom_callback_parser

        JSON_ASSERT(object_element);
        *object_element = std::move(value);
+        if (!skip_callback)
+        {
+            // this scalar value finally, definitively replaces whatever was
+            // at this slot; drop any pending duplicate-key stash entry for
+            // it since it can no longer be restored (a container value at
+            // this slot is resolved later, in end_object()/end_array(),
+            // since skip_callback is true for the placeholder handling that
+            // happens here for those)
+            resolve_duplicate_key_stash(object_element, false);
+        }
        return {true, object_element};
    }

@@ -1039,6 +1113,12 @@ class json_sax_dom_callback_parser
    std::vector<string_t> container_key_stack {}; // NOLINT(readability-redundant-member-init)
    /// helper to hold the reference for the next object element
    BasicJsonType* object_element = nullptr;
+    /// stash of (slot pointer, previous value) for object members that
+    /// already existed when key() was called again for the same key
+    /// (duplicate keys); used to restore the previous value if the new
+    /// value is later rejected by the callback, instead of erasing the
+    /// member entirely
+    std::vector<std::pair<BasicJsonType*, BasicJsonType>> duplicate_key_stash {};
    /// whether a syntax error occurred
    bool errored = false;
    /// callback function
@@ -952,7 +952,9 @@ class lexer : public lexer_base<BasicJsonType>
                        case '\n':
                        case '\r':
                        case char_traits<char_type>::eof():
+#if !JSON_STRICT_NUL_HANDLING
                        case '\0':
+#endif
                            return true;

                        default:
@@ -970,8 +972,10 @@ class lexer : public lexer_base<BasicJsonType>
                {
                    switch (get())
                    {
-                        case char_traits<char_type>::eof():
+#if !JSON_STRICT_NUL_HANDLING
                        case '\0':
+#endif
+                        case char_traits<char_type>::eof():
                        {
                            error_message = "invalid comment; missing closing '*/'";
                            return false;
@@ -2153,9 +2157,12 @@ scan_number_done:
            case '9':
                return scan_number_dispatch(std::integral_constant<bool, bulk_scan> {});

-            // end of input (the null byte is needed when parsing from
-            // string literals)
+#if !JSON_STRICT_NUL_HANDLING
            case '\0':
+#endif
+            // end of input; by default, a null byte is also treated as end of
+            // input for backwards compatibility (see JSON_STRICT_NUL_HANDLING
+            // to opt into rejecting a null byte in the input instead)
            case char_traits<char_type>::eof():
                return token_type::end_of_input;

@@ -807,3 +807,7 @@ void templated_json_throw(ExceptionType exception)
 #ifndef JSON_BRACE_INIT_COPY_SEMANTICS
    #define JSON_BRACE_INIT_COPY_SEMANTICS 0
 #endif
+
+#ifndef JSON_STRICT_NUL_HANDLING
+    #define JSON_STRICT_NUL_HANDLING 0
+#endif
@@ -27,6 +27,7 @@
 #undef JSON_DISABLE_ENUM_SERIALIZATION
 #undef JSON_USE_GLOBAL_UDLS
 #undef JSON_BRACE_INIT_COPY_SEMANTICS
+#undef JSON_STRICT_NUL_HANDLING

 #ifndef JSON_TEST_KEEP_MACROS
    #undef JSON_CATCH
@@ -13,6 +13,7 @@
 #include <iterator> // back_inserter
 #include <memory> // shared_ptr, make_shared
 #include <string> // basic_string
+#include <utility> // move
 #include <vector> // vector

 #ifndef JSON_NO_IO
@@ -44,22 +45,32 @@ template<typename CharType> struct output_adapter_protocol
 template<typename CharType>
 using output_adapter_t = std::shared_ptr<output_adapter_protocol<CharType>>;

-/// output adapter for byte vectors
+/// @brief non-virtual output sink writing into a std::vector
+///
+/// This sink is not part of the virtual output_adapter_protocol hierarchy: it is
+/// passed to binary_writer by value as a template parameter, so
+/// write_character()/write_characters() are ordinary (inlinable) calls with no
+/// vtable lookup and no shared_ptr. It is used for the common
+/// `to_cbor`/`to_msgpack`/... into a std::vector. output_vector_adapter below
+/// wraps this same sink to provide the virtual interface.
 template<typename CharType, typename AllocatorType = std::allocator<CharType>>
-class output_vector_adapter : public output_adapter_protocol<CharType>
+class output_vector_sink
 {
  public:
-    explicit output_vector_adapter(std::vector<CharType, AllocatorType>& vec) noexcept
+    explicit output_vector_sink(std::vector<CharType, AllocatorType>& vec) noexcept
        : v(vec)
    {}

-    void write_character(CharType c) override
+    void write_character(CharType c)
    {
        v.push_back(c);
    }

-    JSON_HEDLEY_NON_NULL(2)
-    void write_characters(const CharType* s, std::size_t length) override
+    // no JSON_HEDLEY_NON_NULL here: binary_writer legitimately passes a null
+    // pointer with length 0 for empty strings/binary values. Appending an empty
+    // range is a no-op; the type-erased path tolerates this via the (unattributed)
+    // virtual base, and the concrete sink must do the same.
+    void write_characters(const CharType* s, std::size_t length)
    {
        v.insert(v.end(), s, s + length);
    }
@@ -68,6 +79,34 @@ class output_vector_adapter : public output_adapter_protocol<CharType>
    std::vector<CharType, AllocatorType>& v;
 };

+/// output adapter for byte vectors
+///
+/// The appending itself lives in output_vector_sink; this class only adds the
+/// virtual output_adapter_protocol interface on top of it, so both the
+/// type-erased and the templated path share one implementation.
+template<typename CharType, typename AllocatorType = std::allocator<CharType>>
+class output_vector_adapter : public output_adapter_protocol<CharType>
+{
+  public:
+    explicit output_vector_adapter(std::vector<CharType, AllocatorType>& vec) noexcept
+        : sink(vec)
+    {}
+
+    void write_character(CharType c) override
+    {
+        sink.write_character(c);
+    }
+
+    JSON_HEDLEY_NON_NULL(2)
+    void write_characters(const CharType* s, std::size_t length) override
+    {
+        sink.write_characters(s, length);
+    }
+
+  private:
+    output_vector_sink<CharType, AllocatorType> sink;
+};
+
 #ifndef JSON_NO_IO
 /// output adapter for output streams
 template<typename CharType>
@@ -118,6 +157,39 @@ class output_string_adapter : public output_adapter_protocol<CharType>
    StringType& str;
 };

+/// @brief output sink forwarding to a type-erased output adapter
+///
+/// Wraps the polymorphic output_adapter_t so the same binary_writer template can
+/// also target arbitrary adapters (output streams, strings, user-provided
+/// adapters) via the `output_adapter`-based overloads. Each write still goes
+/// through one virtual call, exactly as before; only the concrete sinks above
+/// avoid it.
+template<typename CharType>
+class output_adapter_sink
+{
+  public:
+    explicit output_adapter_sink(output_adapter_t<CharType> adapter)
+        : oa(std::move(adapter))
+    {
+        JSON_ASSERT(oa);
+    }
+
+    void write_character(CharType c)
+    {
+        oa->write_character(c);
+    }
+
+    // no JSON_HEDLEY_NON_NULL: forwards (null, 0) for empty payloads, exactly as
+    // the type-erased path already did before this sink existed
+    void write_characters(const CharType* s, std::size_t length)
+    {
+        oa->write_characters(s, length);
+    }
+
+  private:
+    output_adapter_t<CharType> oa;
+};
+
 template<typename CharType, typename StringType = std::basic_string<CharType>>
 class output_adapter
 {
@@ -140,7 +140,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    friend ::nlohmann::detail::serializer<basic_json>;
    template<typename BasicJsonType>
    friend class ::nlohmann::detail::iter_impl;
-    template<typename BasicJsonType, typename CharType>
+    template<typename BasicJsonType, typename CharType, typename OutputSinkType>
    friend class ::nlohmann::detail::binary_writer;
    template<typename BasicJsonType, typename InputType, typename SAX>
    friend class ::nlohmann::detail::binary_reader;
@@ -188,6 +188,14 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    template<typename InputType>
    using binary_reader = ::nlohmann::detail::binary_reader<basic_json, InputType>;
    template<typename CharType> using binary_writer = ::nlohmann::detail::binary_writer<basic_json, CharType>;
+    // binary_writer over a concrete (non-virtual) sink appending into a std::vector,
+    // used by the vector-returning to_* overloads
+    template<typename CharType> using vector_binary_writer =
+        ::nlohmann::detail::binary_writer<basic_json, CharType, ::nlohmann::detail::output_vector_sink<CharType>>;
+    template<typename CharType> static vector_binary_writer<CharType> vector_writer(std::vector<CharType>& v)
+    {
+        return vector_binary_writer<CharType>(::nlohmann::detail::output_vector_sink<CharType>(v));
+    }

  JSON_PRIVATE_UNLESS_TESTED:
    using serializer = ::nlohmann::detail::serializer<basic_json>;
@@ -3511,6 +3519,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
            JSON_THROW(invalid_iterator::create(211, "passed iterators may not belong to container", this));
        }

+        // passed iterators must belong to arrays
+        if (JSON_HEDLEY_UNLIKELY(!first.m_object->is_array()))
+        {
+            JSON_THROW(invalid_iterator::create(202, "iterators first and last must point to arrays", this));
+        }
+
        // insert to array and return iterator
        return insert_iterator(pos, first.m_it.array_iterator, last.m_it.array_iterator);
    }
@@ -4438,7 +4452,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    static std::vector<std::uint8_t> to_cbor(const basic_json& j)
    {
        std::vector<std::uint8_t> result;
-        to_cbor(j, result);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_cbor(j);
        return result;
    }

@@ -4461,7 +4476,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    static std::vector<std::uint8_t> to_msgpack(const basic_json& j)
    {
        std::vector<std::uint8_t> result;
-        to_msgpack(j, result);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_msgpack(j);
        return result;
    }

@@ -4486,7 +4502,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
            const bool use_type = false)
    {
        std::vector<std::uint8_t> result;
-        to_ubjson(j, result, use_size, use_type);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_ubjson(j, use_size, use_type);
        return result;
    }

@@ -4514,7 +4531,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
            const bjdata_version_t version = bjdata_version_t::draft2)
    {
        std::vector<std::uint8_t> result;
-        to_bjdata(j, result, use_size, use_type, version);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_ubjson(j, use_size, use_type, true, true, version);
        return result;
    }

@@ -4541,7 +4559,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
    static std::vector<std::uint8_t> to_bson(const basic_json& j)
    {
        std::vector<std::uint8_t> result;
-        to_bson(j, result);
+        result.reserve(detail::binary_reserve_hint(j));
+        vector_writer(result).write_bson(j);
        return result;
    }

@@ -5332,34 +5351,139 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec

            case value_t::object:
            {
-                // first pass: traverse this object's elements
+                // first pass: record, for every source key, whether it is
+                // common to both objects (in source's iteration order) or
+                // was deleted (i.e., in source but not in target) -- this is
+                // a by-product of the target.find() call already needed to
+                // tell the two cases apart, so it adds no extra lookups. The
+                // "remove" ops themselves are emitted later, interleaved
+                // with the recursive per-key diffs in the fast path below,
+                // to match source's original iteration order (as the
+                // original, pre-reordering-aware implementation did) instead
+                // of grouping all removes before all recursive diffs.
+                std::vector<typename object_t::key_type> common_keys_source_order;
                for (auto it = source.cbegin(); it != source.cend(); ++it)
                {
-                    // escape the key name to be used in a JSON patch
-                    const auto path_key = detail::concat<string_t>(path, '/', detail::escape(it.key()));
-
                    if (target.find(it.key()) != target.end())
                    {
-                        // recursive call to compare object values at key it
-                        auto temp_diff = diff(it.value(), target[it.key()], path_key);
-                        result.insert(result.end(), temp_diff.begin(), temp_diff.end());
+                        common_keys_source_order.push_back(it.key());
+                    }
+                }
+
+                // second pass: find keys that were added (i.e., in target but
+                // not in source), and record the keys common to both, in
+                // target's iteration order -- again a by-product of the
+                // source.find() call already needed to detect added keys. At
+                // the same time, determine whether every added key comes
+                // after every common key in target's order (a precondition
+                // for the fast path below, which only ever appends new keys
+                // at the very end): for an object_t whose iteration order is
+                // a pure function of the key set (e.g. the default std::map,
+                // which always iterates in sorted key order), the order
+                // check further below is always true and this whole
+                // mechanism is effectively a no-op; it only matters for a
+                // reorderable object_t such as the one backing `ordered_json`.
+                // patch ops for keys that were added (i.e., in target but not
+                // in source); built here so the fast path below can reuse
+                // them without a second source.find() per target key. Only
+                // used by the fast path -- the slow (reordering) path
+                // rebuilds "add" ops for every key itself.
+                std::vector<typename object_t::key_type> common_keys_target_order;
+                basic_json added_ops(value_t::array);
+                bool new_keys_form_suffix = true;
+                bool seen_new_key = false;
+                for (auto it = target.cbegin(); it != target.cend(); ++it)
+                {
+                    if (source.find(it.key()) == source.end())
+                    {
+                        seen_new_key = true;
+                        const auto path_key = detail::concat<string_t>(path, '/', detail::escape(it.key()));
+                        added_ops.push_back(
+                        {
+                            {"op", "add"}, {"path", path_key},
+                            {"value", it.value()}
+                        });
                    }
                    else
                    {
-                        // found a key that is not in o -> remove it
+                        common_keys_target_order.push_back(it.key());
+                        if (seen_new_key)
+                        {
+                            new_keys_form_suffix = false;
+                        }
+                    }
+                }
+
+                if (common_keys_source_order == common_keys_target_order && new_keys_form_suffix)
+                {
+                    // fast path: order of common keys already matches (or the
+                    // object_t's iteration order does not depend on
+                    // insertion history), so a plain per-key recursive diff
+                    // is correct and minimal, as before. common_keys_source_order
+                    // is, by construction, the subsequence of source's keys
+                    // that are common to both objects, in source's iteration
+                    // order -- so it can be walked in lockstep with `source`
+                    // using a cheap key comparison instead of another lookup.
+                    // Deleted keys (those source keys not in common_keys_source_order)
+                    // are interleaved here too, in source's original order, to
+                    // match the historical (pre-reordering-aware) output order.
+                    auto common_it = common_keys_source_order.cbegin();
+                    for (auto it = source.cbegin(); it != source.cend(); ++it)
+                    {
+                        if (common_it != common_keys_source_order.cend() && it.key() == *common_it)
+                        {
+                            const auto path_key = detail::concat<string_t>(path, '/', detail::escape(it.key()));
+                            auto temp_diff = diff(it.value(), target[it.key()], path_key);
+                            result.insert(result.end(), temp_diff.begin(), temp_diff.end());
+                            ++common_it;
+                        }
+                        else
+                        {
+                            // found a key that is not in target -> remove it
+                            const auto path_key = detail::concat<string_t>(path, '/', detail::escape(it.key()));
+                            result.push_back(object(
+                            {
+                                {"op", "remove"}, {"path", path_key}
+                            }));
+                        }
+                    }
+
+                    // append the "add" ops for brand-new keys collected above
+                    // during the pass over target -- no second source.find()
+                    // per target key needed
+                    result.insert(result.end(), added_ops.begin(), added_ops.end());
+                }
+                else
+                {
+                    // slow path: the common keys are in a different relative
+                    // order in source and target (only possible for a
+                    // reorderable object_t like ordered_map). Building a
+                    // minimal reordering patch is a nontrivial (LCS-like)
+                    // problem; instead, remove every source key -- both
+                    // deleted keys (which must be removed regardless) and
+                    // common keys (removed so they can be re-added in
+                    // target's order) -- and re-add every key that should
+                    // remain, with its final target value, in target's
+                    // order. basic_json::patch()'s "add" operation on an
+                    // object uses operator[], which appends at the end for a
+                    // vector-backed insertion-ordered map when the key does
+                    // not already exist -- so removing a key and then adding
+                    // it moves it to the end, fixing its position.
+                    for (auto it = source.cbegin(); it != source.cend(); ++it)
+                    {
+                        const auto path_key = detail::concat<string_t>(path, '/', detail::escape(it.key()));
                        result.push_back(object(
                        {
                            {"op", "remove"}, {"path", path_key}
                        }));
                    }
-                }

-                // second pass: traverse other object's elements
-                for (auto it = target.cbegin(); it != target.cend(); ++it)
-                {
-                    if (source.find(it.key()) == source.end())
+                    // add every key that is either common (just removed
+                    // above) or brand new, in target's iteration order, so
+                    // that the final order after applying the patch matches
+                    // target exactly
+                    for (auto it = target.cbegin(); it != target.cend(); ++it)
                    {
-                        // found a key that is not in this -> add it
                        const auto path_key = detail::concat<string_t>(path, '/', detail::escape(it.key()));
                        result.push_back(
                        {
@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.11...3.14)
+cmake_minimum_required(VERSION 3.14)
 project(JSON_Benchmarks LANGUAGES CXX)

 # set compiler flags
@@ -6,29 +6,35 @@ if((CMAKE_CXX_COMPILER_ID MATCHES GNU) OR (CMAKE_CXX_COMPILER_ID MATCHES Clang))
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -flto -DNDEBUG -O3")
 endif()

-# configure Google Benchmarks
+# configure Google Benchmark; a fixed release, so that results stay comparable
+set(JSON_GOOGLE_BENCHMARK_VERSION 1.9.5)
 include(FetchContent)
-FetchContent_Declare(
-    benchmark
-    GIT_REPOSITORY https://github.com/google/benchmark.git
-    GIT_TAG origin/main
-    GIT_SHALLOW TRUE
-)

-FetchContent_GetProperties(benchmark)
-if(NOT benchmark_POPULATED)
-    FetchContent_Populate(benchmark)
-    set(BENCHMARK_ENABLE_TESTING OFF CACHE INTERNAL "" FORCE)
-    add_subdirectory(${benchmark_SOURCE_DIR} ${benchmark_BINARY_DIR})
-endif()
+# only the library is needed; -Werror would break the pinned release as soon as
+# a newer compiler adds a warning
+set(BENCHMARK_ENABLE_TESTING OFF CACHE BOOL "" FORCE)
+set(BENCHMARK_ENABLE_INSTALL OFF CACHE BOOL "" FORCE)
+set(BENCHMARK_ENABLE_WERROR OFF CACHE BOOL "" FORCE)
+
+FetchContent_Declare(benchmark
+    URL https://github.com/google/benchmark/archive/refs/tags/v${JSON_GOOGLE_BENCHMARK_VERSION}.tar.gz
+    URL_HASH SHA256=9631341c82bac4a288bef951f8b26b41f69021794184ece969f8473977eaa340
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+)
+FetchContent_MakeAvailable(benchmark)

 # download test data
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../cmake ${CMAKE_MODULE_PATH})
 include(download_test_data)

+# the header to benchmark; point this at a directory holding another version's
+# nlohmann/json.hpp to compare versions (see README.md)
+set(JSON_BENCHMARK_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../single_include" CACHE PATH
+    "directory containing the nlohmann/json.hpp to benchmark")
+
 # benchmark binary
 add_executable(json_benchmarks src/benchmarks.cpp)
 target_compile_features(json_benchmarks PRIVATE cxx_std_11)
 target_link_libraries(json_benchmarks benchmark ${CMAKE_THREAD_LIBS_INIT})
 add_dependencies(json_benchmarks download_test_data)
-target_include_directories(json_benchmarks PRIVATE ${CMAKE_SOURCE_DIR}/../../single_include ${CMAKE_BINARY_DIR}/include)
+target_include_directories(json_benchmarks PRIVATE ${JSON_BENCHMARK_INCLUDE_DIR} ${CMAKE_BINARY_DIR}/include)
@@ -0,0 +1,130 @@
+# Benchmarks
+
+Micro-benchmarks for parsing, serialization and the binary formats, written with
+[Google Benchmark](https://github.com/google/benchmark). They are not run by CI; see
+[When to run them](#when-to-run-them).
+
+## What is measured
+
+| benchmark | what it does |
+|---|---|
+| `ParseFile`, `ParseString` | parse JSON from a file stream or a string |
+| `ParseIndented` | parse the large files re-indented by 4 spaces, for the lexer's whitespace handling |
+| `Dump` | serialize, compact (`-`) and indented (`4`) |
+| `ToCbor`, `BinaryToCbor` | write CBOR; `BinaryToCbor` writes binary values of growing size |
+| `FromMsgpack` | read MessagePack; unchanged over the years, so its numbers stay comparable across releases |
+| `FromBinaryBuffer`, `FromBinaryFile` | read CBOR, MessagePack, UBJSON, BJData and BSON from a buffer or a `FILE*` |
+| `FromBinaryShape` | read deeply nested, container-heavy and scalar-heavy documents in every binary format |
+| `FromCborChunkedString` | read CBOR strings split into indefinite-length chunks |
+
+The input files are those of [nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark) (`canada`,
+`citm_catalog`, `twitter`), a large `jeopardy` file, and number-heavy files (`floats`, `signed_ints`, ...).
+`bytes_per_second` counts the bytes read or written: the JSON text when parsing, the output when serializing.
+
+## Requirements
+
+- CMake 3.14 or later, a C++11 compiler, and Ninja for the `make` target.
+- Network access on the first configure: CMake downloads Google Benchmark and the
+  [test data](https://github.com/nlohmann/json_test_data) into the build directory. To reuse a download of the test
+  data, pass `-DJSON_TestDataDirectory=<build directory>/test_files`.
+- Google Benchmark is pinned to a release (1.9.5), so that results from different days stay comparable. To update it,
+  change `JSON_GOOGLE_BENCHMARK_VERSION` and the archive's `URL_HASH` in `CMakeLists.txt` together.
+- The benchmarks include `single_include/nlohmann/json.hpp`, so run `make amalgamate` after changing anything in
+  `include/`.
+
+GCC and Clang builds use `-O3 -flto -DNDEBUG`.
+
+## Running them
+
+From the repository root, this builds everything from scratch in `cmake-build-benchmarks` and runs all benchmarks:
+
+```sh
+make run_benchmarks
+```
+
+To build once and run selectively:
+
+```sh
+cmake -S tests/benchmarks -B build-benchmarks -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build-benchmarks
+build-benchmarks/json_benchmarks --benchmark_filter='ParseString|Dump'
+```
+
+Useful options of `json_benchmarks`:
+
+| option | effect |
+|---|---|
+| `--benchmark_list_tests` | list the benchmarks instead of running them |
+| `--benchmark_filter=<regex>` | run only the benchmarks whose names match |
+| `--benchmark_repetitions=<n>` | run every benchmark `n` times and add mean, median, standard deviation and coefficient of variation |
+| `--benchmark_enable_random_interleaving=true` | run the repetitions in random order, which spreads out drifts such as thermal throttling |
+| `--benchmark_min_time=<seconds>s` | run each benchmark at least this long (e.g. `2s`) |
+| `--benchmark_out=<file> --benchmark_out_format=json` | also write the results to a file, e.g. for `compare.py` |
+
+## Reading the output
+
+Each line shows the wall-clock `Time` and the `CPU` time per iteration, the number of `Iterations` Google Benchmark
+chose, and the throughput in `bytes_per_second`. With repetitions, the lines ending in `_median` are the ones to
+compare. A `_cv` (coefficient of variation) above a few percent means the machine was too noisy for small
+differences to mean anything.
+
+## Comparing two versions
+
+To see what a change or a release did, build the same benchmarks twice: once against the header of the version to
+compare with, and once against the current one. `JSON_BENCHMARK_INCLUDE_DIR` names the directory holding the
+`nlohmann/json.hpp` to benchmark. For example, to compare the current checkout with 3.12.0:
+
+```sh
+# the header of the version to compare with
+mkdir -p build-baseline-header/nlohmann
+git show v3.12.0:single_include/nlohmann/json.hpp > build-baseline-header/nlohmann/json.hpp
+
+# the same benchmarks, built against either header
+cmake -S tests/benchmarks -B build-baseline -G Ninja -DCMAKE_BUILD_TYPE=Release \
+      -DJSON_BENCHMARK_INCLUDE_DIR="$PWD/build-baseline-header"
+cmake -S tests/benchmarks -B build-current -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build-baseline
+cmake --build build-current
+
+# run both, back to back
+build-baseline/json_benchmarks --benchmark_repetitions=10 --benchmark_enable_random_interleaving=true \
+                               --benchmark_out=build-baseline/results.json --benchmark_out_format=json
+build-current/json_benchmarks --benchmark_repetitions=10 --benchmark_enable_random_interleaving=true \
+                              --benchmark_out=build-current/results.json --benchmark_out_format=json
+```
+
+Google Benchmark ships a tool to compare the two result files. It needs NumPy and SciPy:
+
+```sh
+python3 -m venv build-venv
+build-venv/bin/pip install numpy scipy
+build-venv/bin/python build-current/_deps/benchmark-src/tools/compare.py -a benchmarks build-baseline/results.json build-current/results.json
+```
+
+The tool's own `tools/requirements.txt` pins NumPy and SciPy versions that need Python 3.11 or later; with an older
+Python, unpinned versions work as well. In its output:
+
+- the `Time` and `CPU` columns are relative changes: `-0.35` means 35% faster, `+0.10` means 10% slower;
+- `_pvalue` lines report a Mann-Whitney U test of whether the two versions differ. It needs at least 9
+  repetitions, and a p-value below 0.05 means the difference is unlikely to be noise;
+- `OVERALL_GEOMEAN` summarizes all benchmarks;
+- `-a` shows only the aggregates, not every repetition.
+
+The header you compare with must support everything the benchmarks use. The current benchmarks build against 3.12.0.
+Only benchmarks present in both result files are compared, so for older releases, either filter the benchmarks or
+build that release's own `tests/benchmarks` against its own header.
+
+## Getting stable numbers
+
+- Build and run both versions on the same machine, one right after the other.
+- Keep the machine otherwise idle: no builds, no browser, and a laptop plugged in.
+- On Linux, set the CPU frequency governor to `performance`, e.g. `sudo cpupower frequency-set --governor performance`.
+  Google Benchmark prints a warning when frequency scaling is enabled. Pinning the process to a core
+  (`taskset -c 2 ...`) helps as well.
+- Use 10 or more repetitions with random interleaving, compare medians, and treat changes within the `_cv` as noise.
+
+## When to run them
+
+They are a manual step, not part of CI: shared CI runners vary more between runs than most of the effects measured.
+Run the comparison above before a release, comparing the previous release tag with `develop`, and for pull requests
+that claim to change performance.
@@ -131,7 +131,8 @@ static void Dump(benchmark::State& state, const char* filename, int indent)

    while (state.KeepRunning())
    {
-        j.dump(indent);
+        std::string output = j.dump(indent);
+        benchmark::DoNotOptimize(output);
    }

    state.SetBytesProcessed(state.iterations() * j.dump(indent).size());
@@ -21,6 +21,27 @@ array data, it performs the following steps:
 - j4 = from_bjdata(vec3)
 - assert(j1 == j4)

+Re-serializing j2/j3/j4 with the same use_size/use_type settings is checked
+for value-stability rather than byte-exact stability: from_bjdata(to_bjdata(j2))
+must equal j2 (and likewise for j3, j4). Byte-exact stability does not hold in
+general, because a BJData value can lose type fidelity across a round trip
+(e.g. a binary_t value serialized without the optimized "$U#" array header is
+parsed back as a plain array of numbers, see #5398 and the discussion on
+PR #5494) - the numeric value is preserved, but the writer's smallest-type
+selection for the now-plain numbers may legitimately pick a different, but
+equally valid, single-byte type marker than the dedicated binary-data writer
+would have. Both encodings are valid BJData and both decode to the same
+value, so this is not treated as a round-trip failure here.
+
+"Value-stable" is checked by comparing dump()s rather than with operator==
+directly: a BJData/UBJSON payload can decode to a non-finite double (NaN or
+-Infinity), and IEEE 754 NaN is never equal to itself, so operator== would
+report two structurally-identical trees as different whenever a NaN is
+involved -- not a round-trip bug, just NaN's ordinary (non-)reflexivity.
+dump() serializes any non-finite double the same deterministic way (as JSON
+`null`, since JSON itself cannot represent NaN/Infinity), so comparing
+dumps is stable under exactly the same values that break operator==.
+
 The provided function `LLVMFuzzerTestOneInput` can be used in different fuzzer
 drivers.
 */
@@ -31,6 +52,13 @@ drivers.

 using json = nlohmann::json;

+// value-stable comparison for the round-trip checks below; see the note
+// above on why this compares dump()s rather than the json values directly
+static bool is_value_stable(const json& lhs, const json& rhs)
+{
+    return lhs.dump() == rhs.dump();
+}
+
 // see http://llvm.org/docs/LibFuzzer.html
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
 {
@@ -56,10 +84,12 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
            json const j3 = json::from_bjdata(vec3);
            json const j4 = json::from_bjdata(vec4);

-            // serializations must match
-            assert(json::to_bjdata(j2, false, false) == vec2);
-            assert(json::to_bjdata(j3, true, false) == vec3);
-            assert(json::to_bjdata(j4, true, true) == vec4);
+            // re-serializing must be value-stable (see the notes above on
+            // why byte-exact stability is not guaranteed in general, and
+            // why this compares dump()s rather than the values directly)
+            assert(is_value_stable(json::from_bjdata(json::to_bjdata(j2, false, false)), j2));
+            assert(is_value_stable(json::from_bjdata(json::to_bjdata(j3, true, false)), j3));
+            assert(is_value_stable(json::from_bjdata(json::to_bjdata(j4, true, true)), j4));
        }
        catch (const json::parse_error&)
        {
@@ -0,0 +1,61 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  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
+
+// Standalone compile-and-run check for the JSON_SKIP_LIBRARY_VERSION_CHECK
+// configuration macro, which (per #5423) was never exercised anywhere in the
+// test matrix.
+//
+// include/nlohmann/detail/abi_macros.hpp normally emits a #warning if
+// NLOHMANN_JSON_VERSION_MAJOR/MINOR/PATCH are already defined (as they would
+// be by an earlier inclusion of a different version of the library) with
+// values that mismatch the version about to be defined -- unless
+// JSON_SKIP_LIBRARY_VERSION_CHECK is defined, in which case the check (and
+// that #warning) is skipped.
+//
+// This file deliberately is not named tests/src/unit-*.cpp: it is compiled
+// directly (with a modest, non-strict warning set) by the dedicated
+// ci_test_skiplibraryversioncheck target in cmake/ci.cmake, rather than being
+// folded into the library's own -Weverything/-Werror unit test matrix. That
+// is because the scenario simulated here -- mixing two different, already
+// differently-versioned inclusions of the library in one translation unit --
+// unavoidably also triggers the *compiler's own* "macro redefined" warning,
+// independent of (and unaffected by) JSON_SKIP_LIBRARY_VERSION_CHECK, which
+// only ever silences the library's own #warning. Building this file under
+// -Weverything -Werror would therefore fail for a reason unrelated to the
+// macro under test.
+#define NLOHMANN_JSON_VERSION_MAJOR 0
+#define NLOHMANN_JSON_VERSION_MINOR 0
+#define NLOHMANN_JSON_VERSION_PATCH 0
+
+#define JSON_SKIP_LIBRARY_VERSION_CHECK 1
+
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    // reaching this point at all already proves that the mismatched,
+    // pre-defined version macros above did not stop compilation -- which is
+    // exactly what JSON_SKIP_LIBRARY_VERSION_CHECK is for. The library must
+    // also still be fully usable.
+    const nlohmann::json j = {{"a", 1}, {"b", {1, 2, 3}}};
+    if (j.dump() != "{\"a\":1,\"b\":[1,2,3]}")
+    {
+        return 1;
+    }
+
+    // include/nlohmann/detail/abi_macros.hpp unconditionally (re)defines the
+    // version macros to the library's real, current version right after the
+    // (here, skipped) mismatch check, regardless of the deliberately wrong
+    // stand-in values defined above.
+    if (NLOHMANN_JSON_VERSION_MAJOR == 0 && NLOHMANN_JSON_VERSION_MINOR == 0 && NLOHMANN_JSON_VERSION_PATCH == 0)
+    {
+        return 1;
+    }
+
+    return 0;
+}
@@ -0,0 +1,198 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  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
+
+#include "doctest_compatibility.h"
+
+#include <nlohmann/json.hpp>
+using nlohmann::json;
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace
+{
+
+// a spread of values exercising every writer path: scalars of each width, the
+// float paths, strings, binary, and containers big enough to reallocate
+std::vector<json> test_values()
+{
+    json big_array = json::array();
+    for (int i = 0; i < 5000; ++i)
+    {
+        big_array.push_back(i);
+    }
+
+    json big_object = json::object();
+    for (int i = 0; i < 1000; ++i)
+    {
+        big_object[std::to_string(i)] = i;
+    }
+
+    return
+    {
+        json(nullptr), json(true), json(false),
+        json(0), json(-1), json(255), json(-129), json(65535), json(-32769),
+        json(4294967295U), json(-2147483649LL), json(18446744073709551615ULL),
+        json(0.0), json(-0.5), json(3.1415926535897932),
+        json(""), json("hello"), json(std::string(1000, 'x')),
+        json::binary({0x00, 0x01, 0x02}, 42),
+        json::array(), json::object(),
+        json::array({1, 2, 3}), json({{"a", 1}, {"b", nullptr}}),
+        json({{"nested", {{"deep", json::array({1, "two", 3.0, nullptr})}}}}),
+        big_array, big_object
+    };
+}
+
+// values to_bson() accepts: the document must be an object
+std::vector<json> bson_values()
+{
+    json big_object = json::object();
+    for (int i = 0; i < 1000; ++i)
+    {
+        big_object[std::to_string(i)] = i;
+    }
+
+    return
+    {
+        json::object(),
+        json({{"a", 1}, {"b", nullptr}, {"c", true}, {"d", 2.5}, {"e", "text"}}),
+        json({{"arr", json::array({1, 2, 3})}, {"obj", {{"k", "v"}}}}),
+        big_object
+    };
+}
+
+} // namespace
+
+// The vector-returning to_*(j) overloads write through the non-virtual
+// output_vector_sink, while to_*(j, adapter) goes through output_adapter_sink.
+// The two are separate code paths that must stay byte-for-byte identical; these
+// checks fail if either overload is ever changed without the other.
+TEST_CASE("binary writer output sinks")
+{
+    SECTION("vector sink and adapter sink agree")
+    {
+        // note: no SUBCASE inside these loops - doctest keys subcases by
+        // name/file/line, so a subcase in a loop body would only ever run for
+        // the first iteration
+        for (const auto& j : test_values())
+        {
+            CAPTURE(j.dump(-1, ' ', false, json::error_handler_t::replace));
+
+            std::vector<std::uint8_t> cbor;
+            json::to_cbor(j, cbor);
+            CHECK(json::to_cbor(j) == cbor);
+
+            std::vector<std::uint8_t> msgpack;
+            json::to_msgpack(j, msgpack);
+            CHECK(json::to_msgpack(j) == msgpack);
+
+            for (const bool use_size :
+                    {
+                        false, true
+                    })
+            {
+                for (const bool use_type :
+                        {
+                            false, true
+                        })
+                {
+                    if (use_type && !use_size)
+                    {
+                        continue; // not a supported combination
+                    }
+                    CAPTURE(use_size);
+                    CAPTURE(use_type);
+                    std::vector<std::uint8_t> ubjson;
+                    json::to_ubjson(j, ubjson, use_size, use_type);
+                    CHECK(json::to_ubjson(j, use_size, use_type) == ubjson);
+                }
+            }
+
+            for (const auto version :
+                    {
+                        json::bjdata_version_t::draft2, json::bjdata_version_t::draft3
+                    })
+            {
+                std::vector<std::uint8_t> bjdata;
+                json::to_bjdata(j, bjdata, false, false, version);
+                CHECK(json::to_bjdata(j, false, false, version) == bjdata);
+            }
+        }
+
+        for (const auto& j : bson_values())
+        {
+            CAPTURE(j.dump());
+            std::vector<std::uint8_t> bson;
+            json::to_bson(j, bson);
+            CHECK(json::to_bson(j) == bson);
+        }
+    }
+
+    SECTION("the char adapter produces the same bytes")
+    {
+        for (const auto& j : test_values())
+        {
+            CAPTURE(j.dump(-1, ' ', false, json::error_handler_t::replace));
+
+            const std::vector<std::uint8_t> expected = json::to_cbor(j);
+            std::vector<char> as_char;
+            json::to_cbor(j, as_char);
+
+            REQUIRE(as_char.size() == expected.size());
+            std::vector<std::uint8_t> as_bytes;
+            as_bytes.reserve(as_char.size());
+            for (const char c : as_char)
+            {
+                as_bytes.push_back(static_cast<std::uint8_t>(c));
+            }
+            CHECK(as_bytes == expected);
+        }
+    }
+}
+
+// binary_reserve_hint() is documented as a *lower* bound on the serialized size,
+// so that reserving it up front can never leave the returned vector holding
+// capacity beyond what the value actually needs.
+TEST_CASE("binary_reserve_hint never over-reserves")
+{
+    for (const auto& j : test_values())
+    {
+        CAPTURE(j.dump(-1, ' ', false, json::error_handler_t::replace));
+
+        const std::size_t hint = nlohmann::detail::binary_reserve_hint(j);
+
+        CHECK(hint <= json::to_cbor(j).size());
+        CHECK(hint <= json::to_msgpack(j).size());
+        CHECK(hint <= json::to_ubjson(j).size());
+        CHECK(hint <= json::to_ubjson(j, true, true).size());
+        CHECK(hint <= json::to_bjdata(j).size());
+    }
+
+    for (const auto& j : bson_values())
+    {
+        CAPTURE(j.dump());
+        CHECK(nlohmann::detail::binary_reserve_hint(j) <= json::to_bson(j).size());
+    }
+
+    SECTION("scalars get no hint")
+    {
+        CHECK(nlohmann::detail::binary_reserve_hint(json(nullptr)) == 0);
+        CHECK(nlohmann::detail::binary_reserve_hint(json(42)) == 0);
+        CHECK(nlohmann::detail::binary_reserve_hint(json("a string")) == 0);
+        CHECK(nlohmann::detail::binary_reserve_hint(json::binary({0x01})) == 0);
+    }
+
+    SECTION("containers are hinted from their element count")
+    {
+        CHECK(nlohmann::detail::binary_reserve_hint(json::array()) == 1);
+        CHECK(nlohmann::detail::binary_reserve_hint(json::array({1, 2, 3})) == 4);
+        CHECK(nlohmann::detail::binary_reserve_hint(json::object()) == 1);
+        CHECK(nlohmann::detail::binary_reserve_hint(json({{"a", 1}, {"b", 2}})) == 5);
+    }
+}
@@ -2586,7 +2586,12 @@ TEST_CASE("BJData")
                CHECK(json::to_bjdata(json::from_bjdata(v_d), true, true) == v_d);
                CHECK(json::to_bjdata(json::from_bjdata(v_D), true, true) == v_D);
                CHECK(json::to_bjdata(json::from_bjdata(v_C), true, true) == v_C);
-                CHECK(json::to_bjdata(json::from_bjdata(v_B), true, true) == v_B);
+                // v_B uses the Draft-3-only 'B' marker, so it round-trips only when
+                // Draft 3 is explicitly selected (see GitHub issue #5404); the
+                // default Draft 2 falls back to a plain object instead, covered by
+                // the "ndarray with _ArrayType_ "byte" is gated by the BJData draft
+                // version" section below
+                CHECK(json::to_bjdata(json::from_bjdata(v_B), true, true, json::bjdata_version_t::draft3) == v_B);
            }

            SECTION("ndarray with data not matching _ArrayType_ is written as an object")
@@ -2629,8 +2634,10 @@ TEST_CASE("BJData")
                // the C++ API stores an int literal as number_integer, so _ArrayType_
                // names the wire type rather than the storage. Both storages have to
                // produce the same typed array for every type.
+                // "byte" is checked separately below since it additionally requires
+                // BJData Draft 3 to be selected explicitly (see GitHub issue #5404).
                for (const char* type :
-                        {"uint8", "int8", "uint16", "int16", "uint32", "int32", "uint64", "int64", "char", "byte"
+                        {"uint8", "int8", "uint16", "int16", "uint32", "int32", "uint64", "int64", "char"
                        })
                {
                    CAPTURE(type);
@@ -2641,6 +2648,14 @@ TEST_CASE("BJData")
                    CHECK(from_text == json::to_bjdata(json({{"_ArrayType_", type}, {"_ArraySize_", {2, 3}}, {"_ArrayData_", {1, 2, 3, 4, 5, 6}}})));
                }

+                {
+                    const std::string text = R"({"_ArrayType_":"byte","_ArraySize_":[2,3],"_ArrayData_":[1,2,3,4,5,6]})";
+                    const auto from_text = json::to_bjdata(json::parse(text), true, true, json::bjdata_version_t::draft3);
+                    CHECK(from_text.at(0) == '[');
+                    CHECK(from_text == json::to_bjdata(json({{"_ArrayType_", "byte"}, {"_ArraySize_", {2, 3}}, {"_ArrayData_", {1, 2, 3, 4, 5, 6}}}),
+                    true, true, json::bjdata_version_t::draft3));
+                }
+
                // negative values under a signed type behave the same way
                const auto from_neg = json::to_bjdata(json::parse(R"({"_ArrayType_":"int32","_ArraySize_":[2],"_ArrayData_":[-5,7]})"));
                CHECK(from_neg.at(0) == '[');
@@ -2731,6 +2746,83 @@ TEST_CASE("BJData")
                CHECK(json::from_bjdata(json::to_bjdata(j_size), true, true) == j_size);
            }

+            SECTION("ndarray whose _ArrayType_ is not a string stays as object")
+            {
+                // the type name is looked up as a string below the annotation
+                // check; a non-string _ArrayType_ cannot name a known dtype,
+                // so calling get<string_t>() on it would throw type_error.302
+                // instead of falling back like an unrecognized type name
+                // already does (see GitHub issue #5398)
+                json const j_number = json({{"_ArrayType_", 1}, {"_ArraySize_", {2}}, {"_ArrayData_", {1, 2}}});
+                const auto out_number = json::to_bjdata(j_number);
+                CHECK(out_number.at(0) == '{');
+                CHECK(json::from_bjdata(out_number) == j_number);
+
+                json const j_null = json({{"_ArrayType_", nullptr}, {"_ArraySize_", {2}}, {"_ArrayData_", {1, 2}}});
+                const auto out_null = json::to_bjdata(j_null);
+                CHECK(out_null.at(0) == '{');
+                CHECK(json::from_bjdata(out_null) == j_null);
+
+                json const j_bool = json({{"_ArrayType_", true}, {"_ArraySize_", {2}}, {"_ArrayData_", {1, 2}}});
+                const auto out_bool = json::to_bjdata(j_bool);
+                CHECK(out_bool.at(0) == '{');
+                CHECK(json::from_bjdata(out_bool) == j_bool);
+
+                json const j_array = json({{"_ArrayType_", {"uint8"}}, {"_ArraySize_", {2}}, {"_ArrayData_", {1, 2}}});
+                const auto out_array = json::to_bjdata(j_array);
+                CHECK(out_array.at(0) == '{');
+                CHECK(json::from_bjdata(out_array) == j_array);
+
+                json const j_object = json({{"_ArrayType_", {{"a", 1}}}, {"_ArraySize_", {2}}, {"_ArrayData_", {1, 2}}});
+                const auto out_object = json::to_bjdata(j_object);
+                CHECK(out_object.at(0) == '{');
+                CHECK(json::from_bjdata(out_object) == j_object);
+            }
+
+            SECTION("re-serializing a value containing a plain-array-of-bytes is value-stable but not byte-stable")
+            {
+                // OSS-Fuzz found this input (an array whose first element is a
+                // binary_t byte, followed by an object whose _ArrayType_ is
+                // not a string) while exercising the fix for #5398 above: once
+                // the fix stops to_bjdata() from throwing type_error.302 for
+                // the third element, serialization proceeds far enough to
+                // reach a pre-existing, unrelated round-trip quirk in how a
+                // single-byte binary_t value is re-encoded.
+                std::vector<std::uint8_t> const input
+                {
+                    0x5b, 0x5b, 0x24, 0x42, 0x23, 0x5b, 0x69, 0x01, 0x5d, 0x5b, 0x5b, 0x5d, 0x7b, 0x55, 0x0b,
+                    0x5f, 0x41, 0x72, 0x72, 0x61, 0x79, 0x44, 0x61, 0x74, 0x61, 0x5f, 0x54, 0x55, 0x0b, 0x5f,
+                    0x41, 0x72, 0x72, 0x61, 0x79, 0x53, 0x69, 0x7a, 0x65, 0x5f, 0x5a, 0x55, 0x0b, 0x5f, 0x41,
+                    0x72, 0x72, 0x61, 0x79, 0x54, 0x79, 0x70, 0x65, 0x5f, 0x54, 0x7d, 0x5d
+                };
+                json const j1 = json::from_bjdata(input);
+
+                // to_bjdata() must not throw (this is what #5398 fixes)
+                std::vector<std::uint8_t> vec2;
+                CHECK_NOTHROW(vec2 = json::to_bjdata(j1, false, false));
+
+                // parsing back a plain (non-optimized) array of bytes cannot
+                // recover that it used to be a binary_t: from_bjdata() has no
+                // way to distinguish "array of uint8 numbers" from "array of
+                // bytes" unless the compact "$U#" array header is used, so
+                // the binary_t collapses into a plain JSON array
+                json const j2 = json::from_bjdata(vec2);
+                CHECK(j1 != j2);
+                CHECK(j2 == json({{91}, json::array(), {{"_ArrayData_", true}, {"_ArraySize_", nullptr}, {"_ArrayType_", true}}}));
+
+                // re-serializing j2 no longer goes through the dedicated
+                // binary_t writer (which always uses the 'U' marker for raw
+                // bytes); the now-plain number 91 goes through the generic
+                // smallest-type writer instead, which - like the rest of the
+                // UBJSON/BJData writer, and unchanged by this fix - prefers
+                // the 'i' (int8) marker over 'U' (uint8) for values that fit
+                // both. Both markers are valid BJData and both decode back to
+                // 91, so this is not byte-for-byte identical to vec2, but it
+                // is value-stable: parsing it again reproduces j2 exactly.
+                std::vector<std::uint8_t> const vec3 = json::to_bjdata(j2, false, false);
+                CHECK(json::from_bjdata(vec3) == j2);
+            }
+
            SECTION("ndarray whose dimensions overflow stays as object")
            {
                // the product of the dimensions wraps around std::size_t to 0
@@ -2823,6 +2915,36 @@ TEST_CASE("BJData")
                CHECK(out_single_ok.at(0) == '[');
                CHECK(json::from_bjdata(out_single_ok) == json({1.5f}));
            }
+
+            SECTION("ndarray with _ArrayType_ \"byte\" is gated by the BJData draft version")
+            {
+                // the 'B' (byte) marker used by _ArrayType_ "byte" is only defined
+                // by BJData Draft 3; Draft 2 (the default) has no such marker, so
+                // emitting it unconditionally produced a stream that a Draft 2
+                // reader could not parse as intended (see GitHub issue #5404).
+                // Two dimensions are used so that a successfully written ndarray
+                // round-trips back into the annotated object (a single dimension
+                // is, by the BJData ndarray convention, read back as a plain
+                // binary value rather than the annotated object, same as every
+                // other single-dimension ndarray of a non-"byte" type is read
+                // back as a plain array instead of the annotated object).
+                json const j_byte = json({{"_ArrayType_", "byte"}, {"_ArraySize_", {2, 3}}, {"_ArrayData_", {1, 2, 3, 4, 5, 6}}});
+
+                // default (Draft 2): falls back to a plain object and round-trips
+                const auto out_draft2 = json::to_bjdata(j_byte);
+                CHECK(out_draft2.at(0) == '{');
+                CHECK(json::from_bjdata(out_draft2) == j_byte);
+
+                // explicit Draft 2: same as the default
+                const auto out_draft2_explicit = json::to_bjdata(j_byte, true, true, json::bjdata_version_t::draft2);
+                CHECK(out_draft2_explicit.at(0) == '{');
+                CHECK(json::from_bjdata(out_draft2_explicit) == j_byte);
+
+                // Draft 3 explicitly selected: still uses the compact 'B' ndarray encoding
+                const auto out_draft3 = json::to_bjdata(j_byte, true, true, json::bjdata_version_t::draft3);
+                CHECK(out_draft3 == std::vector<uint8_t>({'[', '$', 'B', '#', '[', '$', 'i', '#', 'i', 2, 2, 3, 1, 2, 3, 4, 5, 6}));
+                CHECK(json::from_bjdata(out_draft3) == j_byte);
+            }
        }
    }

@@ -791,6 +791,15 @@ TEST_CASE("BSON")
    }
 }

+TEST_CASE("regression test - BSON binary subtype rejects a value that doesn't fit a single byte")
+{
+    json const doc255 = {{"b", json::binary({1, 2}, 255)}};
+    CHECK(json::from_bson(json::to_bson(doc255))["b"].get_binary().subtype() == 255);
+
+    CHECK_THROWS_AS(json::to_bson(json{{"b", json::binary({1, 2}, 256)}}), json::out_of_range);
+    CHECK_THROWS_WITH_AS(json::to_bson(json{{"b", json::binary({1, 2}, 300)}}), "[json.exception.out_of_range.415] subtype 300 is too large for the BSON binary subtype (max 255)", json::out_of_range);
+}
+
 TEST_CASE("BSON input/output_adapters")
 {
    const json json_representation =
@@ -42,6 +42,39 @@ TEST_CASE("byte_container_with_subtype")
        CHECK(container.subtype() == static_cast<subtype_type>(-1));
    }

+    SECTION("move semantics")
+    {
+        // the rvalue-reference constructor (without a subtype) must actually move
+        // the passed-in container rather than copy it; comparing the buffer address
+        // before and after is a stronger check than just observing the source is
+        // empty afterward, since a copy-then-clear could also leave it empty
+        {
+            std::vector<std::uint8_t> bytes = {{0xCA, 0xFE, 0xBA, 0xBE}};
+            const auto* const data_ptr = bytes.data();
+
+            nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>> container(std::move(bytes));
+
+            CHECK(container.size() == 4);
+            CHECK(container.data() == data_ptr);
+            CHECK(!container.has_subtype());
+            CHECK(bytes.empty()); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move,hicpp-invalid-access-moved)
+        }
+
+        // same check for the rvalue-reference constructor that also takes a subtype
+        {
+            std::vector<std::uint8_t> bytes = {{0xCA, 0xFE, 0xBA, 0xBE}};
+            const auto* const data_ptr = bytes.data();
+
+            nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>> container(std::move(bytes), 42);
+
+            CHECK(container.size() == 4);
+            CHECK(container.data() == data_ptr);
+            CHECK(container.has_subtype());
+            CHECK(container.subtype() == 42);
+            CHECK(bytes.empty()); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move,hicpp-invalid-access-moved)
+        }
+    }
+
    SECTION("comparisons")
    {
        std::vector<std::uint8_t> const bytes = {{0xCA, 0xFE, 0xBA, 0xBE}};
@@ -8,6 +8,14 @@

 #include "doctest_compatibility.h"

+// 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)
+#if defined(JSON_STRICT_NUL_HANDLING) && (JSON_STRICT_NUL_HANDLING == 1)
+    #define JSON_TEST_STRICT_NUL_HANDLING_ENABLED 1
+#endif
+
 #define JSON_TESTS_PRIVATE
 #include <nlohmann/json.hpp>
 using nlohmann::json;
@@ -17,6 +25,8 @@ using nlohmann::json;

 #include <valarray>
 #include <algorithm>
+#include <cstdio>
+#include <fstream>
 #include <list>
 #include <sstream>
 #include <string>
@@ -543,6 +553,88 @@ TEST_CASE("parser class")
            }
        }

+        SECTION("NUL byte handling (issue #5530, JSON_STRICT_NUL_HANDLING)")
+        {
+            // by default, a NUL byte anywhere in the input (not inside a quoted
+            // string, which is covered above) is silently treated the same as
+            // real end of input; JSON_STRICT_NUL_HANDLING (off by default, see
+            // docs/mkdocs/docs/api/macros/json_strict_nul_handling.md) makes a
+            // NUL byte an error like any other unexpected byte instead.
+            //
+            // The two sections below are mutually exclusive: this whole test
+            // binary is compiled once, with JSON_STRICT_NUL_HANDLING either
+            // 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.
+#if !defined(JSON_TEST_STRICT_NUL_HANDLING_ENABLED)
+            SECTION("default behavior (macro not enabled)")
+            {
+                // a NUL byte after a complete value silently truncates the input
+                std::string s = "123";
+                s.push_back('\0');
+                s += "4";
+                CHECK(json::parse(s) == json(123));
+                CHECK(json::accept(s));
+
+                // parsing from a string literal is unaffected either way
+                CHECK(json::parse("123") == json(123));
+            }
+#endif
+
+#if defined(JSON_TEST_STRICT_NUL_HANDLING_ENABLED)
+            SECTION("opt-in strict behavior (JSON_STRICT_NUL_HANDLING == 1)")
+            {
+                // a NUL byte after a complete value is now a parse error,
+                // instead of silently truncating the input
+                {
+                    std::string s = "123";
+                    s.push_back('\0');
+                    json _; // NOLINT(readability-identifier-naming)
+                    CHECK_THROWS_WITH_AS(_ = json::parse(s),
+                                         "[json.exception.parse_error.101] parse error at line 1, column 4: syntax error while parsing value - invalid literal; last read: '123<U+0000>'; expected end of input",
+                                         json::parse_error&);
+                    CHECK_FALSE(json::accept(s));
+                }
+
+                // a NUL byte where a value is expected is now a parse error,
+                // instead of being treated the same as an empty input
+                {
+                    const std::string s(1, '\0');
+                    json _; // NOLINT(readability-identifier-naming)
+                    CHECK_THROWS_WITH_AS(_ = json::parse(s),
+                                         "[json.exception.parse_error.101] parse error at line 1, column 1: syntax error while parsing value - invalid literal; last read: '<U+0000>'",
+                                         json::parse_error&);
+                    CHECK_FALSE(json::accept(s));
+                }
+
+                // a NUL byte inside a // comment no longer stops the comment
+                // scan early; scanning continues correctly past it
+                {
+                    std::string s = "1 // a";
+                    s.push_back('\0');
+                    s += "b\n";
+                    CHECK(json::parse(s, nullptr, true, true) == json(1));
+                    CHECK(json::accept(s, true, true));
+                }
+
+                // a NUL byte inside a /* */ comment no longer stops the
+                // comment scan early either
+                {
+                    std::string s = "1 /* a";
+                    s.push_back('\0');
+                    s += "b */ ";
+                    CHECK(json::parse(s, nullptr, true, true) == json(1));
+                    CHECK(json::accept(s, true, true));
+                }
+
+                // regression guard: parsing from a string literal (which
+                // carries a compiler-appended trailing '\0') still works,
+                // even though a NUL byte is now rejected everywhere else
+                CHECK(json::parse("123") == json(123));
+            }
+#endif
+        }
+
        SECTION("number")
        {
            SECTION("integers")
@@ -1892,7 +1984,13 @@ TEST_CASE("parser class")

        SECTION("from std::array")
        {
-            std::array<uint8_t, 5> v { {'t', 'r', 'u', 'e'} };
+            // NOTE: this array is sized to exactly the length of "true" (unlike
+            // the trailing-NUL-tolerant default behavior elsewhere in this file,
+            // see the "NUL byte handling" section above); a size of 5 here would
+            // leave a value-initialized trailing 0x00 element that is only
+            // silently accepted as end-of-input by default and would fail under
+            // JSON_STRICT_NUL_HANDLING
+            std::array<uint8_t, 4> v { {'t', 'r', 'u', 'e'} };
            json j;
            json::parser(nlohmann::detail::input_adapter(std::begin(v), std::end(v))).parse(true, j);
            CHECK(j == json(true));
@@ -2033,7 +2131,17 @@ TEST_CASE("parser class")
    {
        json _;
        CHECK_THROWS_WITH_AS(_ = json::parse("/a", nullptr, true, true), "[json.exception.parse_error.101] parse error at line 1, column 2: syntax error while parsing value - invalid comment; expecting '/' or '*' after '/'; last read: '/a'", json::parse_error);
+        // "/*" is a string literal, so it carries a compiler-appended trailing
+        // '\0'; by default that NUL is read like any other byte and shows up
+        // in "last read", but JSON_STRICT_NUL_HANDLING trims exactly that one
+        // trailing byte from a char array (see
+        // docs/mkdocs/docs/api/macros/json_strict_nul_handling.md), so it no
+        // longer appears in the message in that state
+#if defined(JSON_TEST_STRICT_NUL_HANDLING_ENABLED)
+        CHECK_THROWS_WITH_AS(_ = json::parse("/*", nullptr, true, true), "[json.exception.parse_error.101] parse error at line 1, column 3: syntax error while parsing value - invalid comment; missing closing '*/'; last read: '/*'", json::parse_error);
+#else
        CHECK_THROWS_WITH_AS(_ = json::parse("/*", nullptr, true, true), "[json.exception.parse_error.101] parse error at line 1, column 3: syntax error while parsing value - invalid comment; missing closing '*/'; last read: '/*<U+0000>'", json::parse_error);
+#endif
    }

 #if JSON_DIAGNOSTIC_POSITIONS
@@ -2259,86 +2367,6 @@ TEST_CASE("parser class")
 #endif
 }

-#if JSON_DIAGNOSTIC_POSITIONS
-
-TEST_CASE("diagnostic positions: value lifetime")
-{
-    SECTION("copy constructor copies positions, recursively")
-    {
-        const std::string s = R"({"a":1,"b":[1,2,3]})";
-        const json a = json::parse(s);
-        const json b = a; // NOLINT(performance-unnecessary-copy-initialization)
-
-        CHECK(b.start_pos() == a.start_pos());
-        CHECK(b.end_pos() == a.end_pos());
-        CHECK(b["b"].start_pos() == a["b"].start_pos());
-        CHECK(b["b"].end_pos() == a["b"].end_pos());
-    }
-
-    SECTION("move constructor resets the moved-from value to npos")
-    {
-        const std::string s = R"({"a":1,"b":[1,2,3]})";
-        json a = json::parse(s);
-        const auto a_start = a.start_pos();
-        const auto a_end = a.end_pos();
-
-        const json b(std::move(a));
-
-        CHECK(b.start_pos() == a_start);
-        CHECK(b.end_pos() == a_end);
-
-        CHECK(a.start_pos() == std::string::npos); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move)
-        CHECK(a.end_pos() == std::string::npos); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move)
-    }
-
-    SECTION("swap() exchanges positions along with the values")
-    {
-        // basic_json::swap() (and the friend swap() that forwards to it) used
-        // to swap only m_data.m_type/m_data.m_value, leaving
-        // start_position/end_position untouched -- unlike copy-assignment's
-        // operator=(basic_json), which swaps positions as part of its
-        // copy-and-swap implementation. After swap(a, b), each value ended up
-        // with the *other* value's content but its *own* original position.
-        // This is now fixed so that swap() is consistent with copy-assignment.
-        json a = json::parse(R"({"a":1})");
-        json b = json::parse(R"([1,2,3,4,5])");
-        const auto a_start = a.start_pos();
-        const auto a_end = a.end_pos();
-        const auto b_start = b.start_pos();
-        const auto b_end = b.end_pos();
-        // lengths (and thus end positions) differ, which is enough to tell
-        // after the swap whether positions actually moved with the values
-        CHECK(a_end != b_end);
-
-        using std::swap;
-        swap(a, b);
-
-        CHECK(a == json::parse(R"([1,2,3,4,5])"));
-        CHECK(b == json::parse(R"({"a":1})"));
-
-        CHECK(a.start_pos() == b_start);
-        CHECK(a.end_pos() == b_end);
-        CHECK(b.start_pos() == a_start);
-        CHECK(b.end_pos() == a_end);
-
-        // member swap() behaves the same as the free function
-        json c = json::parse(R"({"a":1})");
-        json d = json::parse(R"([1,2,3,4,5])");
-        const auto c_start = c.start_pos();
-        const auto c_end = c.end_pos();
-        const auto d_start = d.start_pos();
-        const auto d_end = d.end_pos();
-
-        c.swap(d);
-
-        CHECK(c.start_pos() == d_start);
-        CHECK(c.end_pos() == d_end);
-        CHECK(d.start_pos() == c_start);
-        CHECK(d.end_pos() == c_end);
-    }
-}
-#endif
-
 // this test relies on parse errors being thrown, so it is skipped when
 // exceptions are disabled (json::parse aborts instead of throwing there)
 #if !defined(JSON_NOEXCEPTION)
@@ -2445,3 +2473,329 @@ TEST_CASE("last-read diagnostics are identical across input adapters")
    }
 }
 #endif // !defined(JSON_NOEXCEPTION)
+
+// this test characterizes the current (documented-by-example, not otherwise
+// specified) behavior of JSON_DIAGNOSTIC_POSITIONS positions with respect to
+// value lifetime (copy/move/swap/mutation), the various input adapters, and
+// user-driven SAX usage. It is regression protection, not a behavior
+// specification: if any of these checks fail after a change to json.hpp,
+// that change deliberately altered observable behavior and the test (and
+// this comment) should be updated accordingly, rather than "fixed" blindly.
+#if JSON_DIAGNOSTIC_POSITIONS
+TEST_CASE("diagnostic positions: value lifetime, input adapters, and SAX")
+{
+    SECTION("value lifetime")
+    {
+        SECTION("copy constructor copies positions, recursively")
+        {
+            // basic_json(const basic_json&) (json.hpp, around line 1192) copies
+            // start_position/end_position for the value itself; nested values
+            // are copied via their own copy constructor (through the copied
+            // object/array container), so positions are preserved throughout
+            // the whole tree.
+            const std::string s = R"({"a":1,"b":[1,2,3]})";
+            const json a = json::parse(s);
+            const json b = a; // NOLINT(performance-unnecessary-copy-initialization)
+
+            CHECK(b.start_pos() == a.start_pos());
+            CHECK(b.end_pos() == a.end_pos());
+            CHECK(b["b"].start_pos() == a["b"].start_pos());
+            CHECK(b["b"].end_pos() == a["b"].end_pos());
+            CHECK(b["b"][0].start_pos() == a["b"][0].start_pos());
+            CHECK(b["b"][0].end_pos() == a["b"][0].end_pos());
+
+            // sanity: the positions are meaningful (not all npos)
+            CHECK(b.start_pos() == 0);
+            CHECK(b.end_pos() == s.size());
+        }
+
+        SECTION("move constructor resets the moved-from value to npos")
+        {
+            // basic_json(basic_json&&) (json.hpp, around line 1265) copies
+            // other's start_position/end_position into *this and then resets
+            // other's to npos (see the cppcheck-suppress[accessForwarded]
+            // annotation there, which flags this reset as worth a second
+            // look). Only the top-level moved-from value is affected; its
+            // (moved-away) children are gone along with it.
+            const std::string s = R"({"a":1,"b":[1,2,3]})";
+            json a = json::parse(s);
+            const auto a_start = a.start_pos();
+            const auto a_end = a.end_pos();
+            const auto nested_start = a["b"].start_pos();
+            const auto nested_end = a["b"].end_pos();
+
+            const json b(std::move(a));
+
+            // the destination retains the original positions, recursively
+            CHECK(b.start_pos() == a_start);
+            CHECK(b.end_pos() == a_end);
+            CHECK(b["b"].start_pos() == nested_start);
+            CHECK(b["b"].end_pos() == nested_end);
+
+            // the moved-from value is reset to a null and reports npos
+            CHECK(a.is_null()); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move)
+            CHECK(a.start_pos() == std::string::npos); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move)
+            CHECK(a.end_pos() == std::string::npos); // NOLINT(bugprone-use-after-move,clang-analyzer-cplusplus.Move)
+        }
+
+        SECTION("swap() exchanges positions along with values")
+        {
+            // basic_json::swap() (json.hpp, around line 3626, and the friend
+            // swap() that forwards to it) swaps start_position/end_position
+            // together with m_data.m_type and m_data.m_value, so after
+            // swap(a, b) each variable's position describes its own new
+            // content, consistent with copy-assignment's
+            // operator=(basic_json) (json.hpp, around line 1291), which also
+            // swaps positions as part of its copy-and-swap implementation.
+            json a = json::parse(R"({"a":1})");
+            json b = json::parse(R"([1,2,3,4,5])");
+            const auto a_start = a.start_pos();
+            const auto a_end = a.end_pos();
+            const auto b_start = b.start_pos();
+            const auto b_end = b.end_pos();
+            // both start at 0 (root values start right away), but their
+            // lengths (and thus end positions) differ, which is enough to
+            // tell after the swap whether positions actually moved with
+            // the values
+            CHECK(a_end != b_end);
+
+            using std::swap;
+            swap(a, b);
+
+            // values were exchanged as expected ...
+            CHECK(a == json::parse(R"([1,2,3,4,5])"));
+            CHECK(b == json::parse(R"({"a":1})"));
+
+            // ... and so were positions: each variable now carries the
+            // other's original position, describing its own new content
+            CHECK(a.start_pos() == b_start);
+            CHECK(a.end_pos() == b_end);
+            CHECK(b.start_pos() == a_start);
+            CHECK(b.end_pos() == a_end);
+
+            // member swap() behaves the same as the free function
+            json c = json::parse(R"({"a":1})");
+            json d = json::parse(R"([1,2,3,4,5])");
+            const auto c_start = c.start_pos();
+            const auto c_end = c.end_pos();
+            const auto d_start = d.start_pos();
+            const auto d_end = d.end_pos();
+
+            c.swap(d);
+
+            CHECK(c.start_pos() == d_start);
+            CHECK(c.end_pos() == d_end);
+            CHECK(d.start_pos() == c_start);
+            CHECK(d.end_pos() == c_end);
+        }
+
+        SECTION("mutating a parsed document leaves positions of unrelated values untouched")
+        {
+            // Positions are recorded once, during parsing, and are not
+            // recomputed on mutation. As a consequence, after a mutation the
+            // parent's own recorded span may no longer describe its current
+            // (serialized) content -- it still describes what was originally
+            // parsed. This is characterized here as current behavior, not
+            // asserted to be desirable or specified.
+            SECTION("operator[] adding a new object key")
+            {
+                const std::string s = R"({"a":1})";
+                json j = json::parse(s);
+                const auto root_start = j.start_pos();
+                const auto root_end = j.end_pos();
+                const auto a_start = j["a"].start_pos();
+                const auto a_end = j["a"].end_pos();
+
+                j["c"] = 42;
+
+                // the newly-added value was never parsed, so it has no position
+                CHECK(j["c"].start_pos() == std::string::npos);
+                CHECK(j["c"].end_pos() == std::string::npos);
+
+                // the existing sibling's position is unaffected
+                CHECK(j["a"].start_pos() == a_start);
+                CHECK(j["a"].end_pos() == a_end);
+
+                // the parent's own recorded span is left as-is (now stale:
+                // it still reflects the original, shorter `{"a":1}` string)
+                CHECK(j.start_pos() == root_start);
+                CHECK(j.end_pos() == root_end);
+            }
+
+            SECTION("push_back on a parsed array")
+            {
+                const std::string s = R"([1,2,3])";
+                json j = json::parse(s);
+                const auto root_start = j.start_pos();
+                const auto root_end = j.end_pos();
+                const auto first_start = j[0].start_pos();
+
+                j.push_back(4);
+
+                CHECK(j.back().start_pos() == std::string::npos);
+                CHECK(j.back().end_pos() == std::string::npos);
+                CHECK(j[0].start_pos() == first_start);
+                CHECK(j.start_pos() == root_start);
+                CHECK(j.end_pos() == root_end);
+            }
+
+            SECTION("erase on a parsed array shifts elements but keeps their own positions")
+            {
+                const std::string s = R"([1,2,3])";
+                json j = json::parse(s);
+                const auto second_start = j[1].start_pos();
+                const auto third_start = j[2].start_pos();
+                const auto root_start = j.start_pos();
+                const auto root_end = j.end_pos();
+
+                j.erase(0);
+
+                // remaining elements moved down an index, but each one still
+                // reports the position it had *before* the erase (i.e. its
+                // position in the original source string, not a
+                // recalculated one)
+                CHECK(j[0].start_pos() == second_start);
+                CHECK(j[1].start_pos() == third_start);
+
+                // the parent's own recorded span is again left as-is
+                CHECK(j.start_pos() == root_start);
+                CHECK(j.end_pos() == root_end);
+            }
+        }
+    }
+
+    SECTION("input adapters")
+    {
+        SECTION("wide string input: positions count transcoded UTF-8 bytes, not wide characters")
+        {
+            // 'é' (U+00E9) is a single code unit in a wchar_t/UTF-16 string, but
+            // transcodes to 2 bytes in UTF-8; the lexer only ever sees the
+            // transcoded UTF-8 byte stream, so reported positions are byte
+            // offsets into that UTF-8 stream, not indices into the original
+            // std::wstring.
+            // é (rather than a literal 'é' byte sequence in this source
+            // file) so the wide-string literal's meaning does not depend on
+            // the compiler's assumed source character set (MSVC, without
+            // /utf-8, would otherwise decode the raw UTF-8 bytes using the
+            // system code page instead of as UTF-8)
+            const std::wstring ws = L"{\"a\":\"\u00e9\u00e9\"}";
+            CHECK(ws.size() == 10); // 10 wide characters
+
+            const json j = json::parse(ws);
+            CHECK(j.start_pos() == 0);
+            // the transcoded UTF-8 form is 2 bytes longer than the wide string,
+            // because each of the two 'é' characters becomes 2 UTF-8 bytes
+            CHECK(j.end_pos() == 12);
+            CHECK(j.end_pos() != ws.size());
+
+            const json& a = j["a"];
+            CHECK(a.start_pos() == 5);
+            CHECK(a.end_pos() == 11);
+        }
+
+        SECTION("BOM-prefixed input: start_pos() reflects the skipped 3-byte BOM")
+        {
+            const std::string s = "\xEF\xBB\xBF{\"a\":1}";
+            const json j = json::parse(s);
+
+            // the lexer silently skips the BOM before parsing the value, so
+            // the root value's recorded span starts right after it
+            CHECK(j.start_pos() == 3);
+            CHECK(j.end_pos() == s.size());
+        }
+
+        SECTION("std::istringstream: positions are consistent, not npos")
+        {
+            const std::string s = R"({"a":1,"b":2})";
+            std::istringstream ss(s);
+            const json j = json::parse(ss);
+
+            CHECK(j.start_pos() == 0);
+            CHECK(j.end_pos() == s.size());
+            CHECK(j["a"].start_pos() == 5);
+        }
+
+        SECTION("std::ifstream: positions are consistent, not npos")
+        {
+            const std::string s = R"({"a":1,"b":2})";
+            {
+                std::ofstream file("unit-class_parser_diagnostic_positions.tmp");
+                file << s;
+            }
+
+            {
+                std::ifstream f("unit-class_parser_diagnostic_positions.tmp");
+                const json j = json::parse(f);
+
+                CHECK(j.start_pos() == 0);
+                CHECK(j.end_pos() == s.size());
+                CHECK(j["a"].start_pos() == 5);
+            }
+
+            static_cast<void>(std::remove("unit-class_parser_diagnostic_positions.tmp"));
+        }
+
+        SECTION("iterator-pair input: positions are consistent, not npos")
+        {
+            const std::string s = R"({"a":1,"b":2})";
+            const json j = json::parse(s.begin(), s.end());
+
+            CHECK(j.start_pos() == 0);
+            CHECK(j.end_pos() == s.size());
+            CHECK(j["a"].start_pos() == 5);
+        }
+
+        SECTION("binary formats have no text positions")
+        {
+            // binary formats (CBOR, MessagePack, UBJSON, BSON, BJData) are
+            // parsed via detail::binary_reader, which never sets
+            // start_position/end_position on the values it produces (they
+            // have no notion of a text offset), so every value's position
+            // stays at its default of npos.
+            const json src = json::parse(R"({"a":1,"b":[1,2]})");
+
+            const json from_cbor = json::from_cbor(json::to_cbor(src));
+            CHECK(from_cbor.start_pos() == std::string::npos);
+            CHECK(from_cbor.end_pos() == std::string::npos);
+            CHECK(from_cbor["a"].start_pos() == std::string::npos);
+            CHECK(from_cbor["b"][0].start_pos() == std::string::npos);
+
+            const json from_msgpack = json::from_msgpack(json::to_msgpack(src));
+            CHECK(from_msgpack.start_pos() == std::string::npos);
+            CHECK(from_msgpack.end_pos() == std::string::npos);
+
+            const json from_ubjson = json::from_ubjson(json::to_ubjson(src));
+            CHECK(from_ubjson.start_pos() == std::string::npos);
+            CHECK(from_ubjson.end_pos() == std::string::npos);
+
+            const json from_bson_val = json::from_bson(json::to_bson(src));
+            CHECK(from_bson_val.start_pos() == std::string::npos);
+            CHECK(from_bson_val.end_pos() == std::string::npos);
+        }
+    }
+
+    SECTION("user-driven SAX consumers with no lexer report npos")
+    {
+        // json::parse() internally wires up its json_sax_dom_parser with a
+        // pointer to its own lexer (see parser.hpp), which is how positions
+        // get set at all. A user who constructs a json_sax_dom_parser
+        // directly (e.g. to drive it via json::sax_parse()) and does not
+        // supply a lexer pointer gets a consumer with m_lexer_ref == nullptr;
+        // every "if (m_lexer_ref)" guard in json_sax.hpp is then skipped, so
+        // every value it produces keeps its default, unset position (npos).
+        // This was previously true but silently unasserted (operator==
+        // ignores positions), see #5420.
+        json result;
+        nlohmann::detail::json_sax_dom_parser<json, nlohmann::detail::string_input_adapter_type> sdp(result);
+        const std::string s = R"({"a":1,"b":[1,2,3]})";
+        CHECK(json::sax_parse(s, &sdp));
+
+        CHECK(result.start_pos() == std::string::npos);
+        CHECK(result.end_pos() == std::string::npos);
+        CHECK(result["a"].start_pos() == std::string::npos);
+        CHECK(result["a"].end_pos() == std::string::npos);
+        CHECK(result["b"][0].start_pos() == std::string::npos);
+        CHECK(result["b"][0].end_pos() == std::string::npos);
+    }
+}
+#endif
@@ -1792,6 +1792,40 @@ TEST_CASE("std::filesystem::path")
 }
 #endif

+// the ADL to_json overload for std::u8string only exists under the same guard
+// as std::filesystem::path support (it is otherwise only reached indirectly,
+// via std::filesystem::path::u8string()) -- mirror both #if conditions from
+// include/nlohmann/detail/conversions/to_json.hpp exactly
+#if JSON_HAS_FILESYSTEM || JSON_HAS_EXPERIMENTAL_FILESYSTEM
+#if defined(__cpp_lib_char8_t)
+TEST_CASE("std::u8string")
+{
+    SECTION("ascii")
+    {
+        const std::u8string s = u8"Path";
+        json const j = s;
+
+        CHECK(j.template get<std::string>() == "Path");
+    }
+
+    SECTION("utf-8")
+    {
+        // use \u universal-character-names (rather than raw \x byte escapes
+        // or literal non-ASCII source bytes) to compose the multi-byte UTF-8
+        // encoding -- MSVC treats \x escapes used that way inside a u8
+        // literal as a nonstandard extension (warning C5321), which some of
+        // our CI configs promote to an error; \u is portable and produces
+        // the exact same encoded bytes without depending on the source
+        // file's encoding
+        const std::u8string s = u8"P\u011B\u0161ina";
+        json const j = s;
+
+        CHECK(j.template get<std::string>() == "P\xc4\x9b\xc5\xa1ina");
+    }
+}
+#endif
+#endif
+
 TEST_CASE("std::optional")
 {
    SECTION("null")
@@ -8,6 +8,14 @@

 #include "doctest_compatibility.h"

+// 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)
+#if defined(JSON_STRICT_NUL_HANDLING) && (JSON_STRICT_NUL_HANDLING == 1)
+    #define JSON_TEST_STRICT_NUL_HANDLING_ENABLED 1
+#endif
+
 #include <nlohmann/json.hpp>
 using nlohmann::json;
 #ifdef JSON_TEST_NO_GLOBAL_UDLS
@@ -323,6 +331,23 @@ TEST_CASE("deserialization")
            CHECK(j == json({"foo", 1, 2, 3, false, {{"one", 1}}}));
        }

+        SECTION("operator>> with a NUL byte after the value (issue #5530)")
+        {
+            // operator>> parses non-strictly (it does not require the whole
+            // stream to be consumed), so a NUL byte following a complete
+            // value is simply left unread on the stream and never reaches
+            // the "expected end of input" check that JSON_STRICT_NUL_HANDLING
+            // affects; this holds regardless of the macro (verified below for
+            // the opt-in state as well)
+            std::string data = "123";
+            data.push_back('\0');
+            std::istringstream ss(data);
+            json j;
+            ss >> j;
+            CHECK(j == json(123));
+            CHECK(ss.good());
+        }
+
        SECTION("user-defined string literal")
        {
            CHECK("[\"foo\",1,2,3,false,{\"one\":1}]"_json == json({"foo", 1, 2, 3, false, {{"one", 1}}}));
@@ -405,6 +430,27 @@ TEST_CASE("deserialization")
            CHECK_THROWS_WITH_AS(ss >> j, "[json.exception.parse_error.101] parse error at line 1, column 29: syntax error while parsing array - unexpected end of input; expected ']'", json::parse_error&);
        }

+#if defined(JSON_TEST_STRICT_NUL_HANDLING_ENABLED)
+        SECTION("operator>> with a NUL byte where a value is expected (JSON_STRICT_NUL_HANDLING == 1, issue #5530)")
+        {
+            // a trailing NUL byte *after* a complete value is unaffected by the
+            // macro (see the successful-deserialization "operator>> with a NUL
+            // byte after the value" section above): operator>> parses
+            // non-strictly and never reaches the "expected end of input" check
+            // that the macro changes. A NUL byte where a *value* is expected,
+            // however, goes through the same token dispatch as any other input
+            // and is affected: with the macro enabled it now raises
+            // parse_error.101 (like any other unrecognized byte) instead of
+            // being silently treated the same as an empty stream.
+            std::string const data(1, '\0');
+            std::istringstream ss(data);
+            json j;
+            CHECK_THROWS_WITH_AS(ss >> j,
+                                 "[json.exception.parse_error.101] parse error at line 1, column 1: syntax error while parsing value - invalid literal; last read: '<U+0000>'",
+                                 json::parse_error&);
+        }
+#endif
+
        SECTION("user-defined string literal")
        {
            CHECK_THROWS_WITH_AS("[\"foo\",1,2,3,false,{\"one\":1}"_json, "[json.exception.parse_error.101] parse error at line 1, column 29: syntax error while parsing array - unexpected end of input; expected ']'", json::parse_error&);
@@ -453,7 +499,11 @@ TEST_CASE("deserialization")

            SECTION("from std::array")
            {
-                std::array<uint8_t, 5> const v { {'t', 'r', 'u', 'e'} };
+                // sized to exactly the length of "true": a size of 5 would leave
+                // a value-initialized trailing 0x00 element that is only
+                // silently accepted as end-of-input by default and would fail
+                // under JSON_STRICT_NUL_HANDLING
+                std::array<uint8_t, 4> const v { {'t', 'r', 'u', 'e'} };
                CHECK(json::parse(v) == json(true));
                CHECK(json::accept(v));

@@ -549,7 +599,9 @@ TEST_CASE("deserialization")

            SECTION("from std::array")
            {
-                std::array<uint8_t, 5> v { {'t', 'r', 'u', 'e'} };
+                // sized to exactly the length of "true", see the analogous
+                // "from std::array" section above for why
+                std::array<uint8_t, 4> v { {'t', 'r', 'u', 'e'} };
                CHECK(json::parse(std::begin(v), std::end(v)) == json(true));
                CHECK(json::accept(std::begin(v), std::end(v)));

@@ -672,6 +672,102 @@ TEST_CASE("JSON patch")
        }
    }

+    SECTION("patch_inplace")
+    {
+        SECTION("happy path: patch_inplace mirrors patch() on success")
+        {
+            // mirrors "A.5. Replacing a Value" above, but applies the patch with
+            // patch_inplace() to a mutable copy instead of using patch()'s
+            // returned copy
+            json doc = R"(
+                    {
+                        "baz": "qux",
+                        "foo": "bar"
+                    }
+                )"_json;
+
+            json const patch = R"(
+                    [
+                        { "op": "replace", "path": "/baz", "value": "boo" }
+                    ]
+                )"_json;
+
+            json const expected = R"(
+                    {
+                        "baz": "boo",
+                        "foo": "bar"
+                    }
+                )"_json;
+
+            doc.patch_inplace(patch);
+            CHECK(doc == expected);
+        }
+
+        // this test relies on the "test" operation actually throwing so the
+        // partial-application state can be observed right after the throw
+        // point; under JSON_NOEXCEPTION, JSON_THROW() calls std::abort()
+        // instead (there is no C++ exception to throw), and doctest's
+        // CHECK_THROWS_AS() is compiled out to a no-op that never even
+        // invokes the given expression (see doctest's "--no-throw" test
+        // filter, which ci_test_noexceptions passes) -- so patch()/
+        // patch_inplace() would never be called at all and the follow-up
+        // state assertions below would fail against the untouched original
+#if !defined(JSON_NOEXCEPTION)
+        SECTION("distinguishing contract vs patch(): partial application on failure")
+        {
+            // Unlike patch(), which is all-or-nothing because it applies the
+            // patch to an internal copy that is simply discarded when an
+            // exception is thrown (leaving the original untouched no matter
+            // what), patch_inplace() mutates the document it is called on
+            // directly and immediately, operation by operation. So if a JSON
+            // Patch fails partway through, whatever operations already
+            // succeeded remain applied -- the document is left in a partially
+            // patched state. This is empirically verified current behavior,
+            // not just documented intent, and is pinned here as such.
+            json const original = R"(
+                    {
+                        "baz": "qux",
+                        "foo": "bar"
+                    }
+                )"_json;
+
+            // the first operation ("replace") succeeds; the second ("test")
+            // fails because the value at "/baz" no longer (and never did)
+            // equal "not boo"
+            json const patch = R"(
+                    [
+                        { "op": "replace", "path": "/baz", "value": "boo" },
+                        { "op": "test", "path": "/baz", "value": "not boo" }
+                    ]
+                )"_json;
+
+            // patch() never modifies the object it is called on -- it always
+            // operates on (and returns) a separate copy, so the original is
+            // left completely untouched, regardless of success or failure.
+            // copy_for_patch is intentionally a real copy, not a reference
+            // to `original`: the whole point of this check is to catch a
+            // hypothetical future regression where patch() *does* mutate its
+            // receiver. Using a reference here would make the assertion
+            // below compare `original` to itself -- trivially true even if
+            // such a bug existed -- which is exactly what a static analyzer
+            // can't see when it suggests "this copy is never modified, use
+            // a reference instead".
+            json copy_for_patch = original; // NOLINT(performance-unnecessary-copy-initialization)
+            CHECK_THROWS_AS(copy_for_patch.patch(patch), json::other_error&);
+            CHECK(copy_for_patch == original);
+
+            // patch_inplace(), in contrast, already applied the successful
+            // "replace" operation to the document before the "test" operation
+            // threw -- that change is not rolled back
+            json doc = original;
+            CHECK_THROWS_AS(doc.patch_inplace(patch), json::other_error&);
+            CHECK(doc != original);
+            CHECK(doc.at("baz") == "boo");
+            CHECK(doc.at("foo") == "bar");
+        }
+#endif // !defined(JSON_NOEXCEPTION)
+    }
+
    SECTION("errors")
    {
        SECTION("unknown operation")
@@ -641,6 +641,20 @@ TEST_CASE("modifiers")
                CHECK_THROWS_WITH_AS(j_array.insert(j_array.end(), j_other_array.begin(), j_other_array2.end()), "[json.exception.invalid_iterator.210] iterators do not fit",
                                     json::invalid_iterator&);
            }
+
+            SECTION("iterators not pointing into an array")
+            {
+                json j_object2 = {{"k", 1}, {"l", 2}};
+                json j_primitive = 5;
+                json j_null;
+
+                CHECK_THROWS_WITH_AS(j_array.insert(j_array.begin(), j_object2.begin(), j_object2.end()), "[json.exception.invalid_iterator.202] iterators first and last must point to arrays",
+                                     json::invalid_iterator&);
+                CHECK_THROWS_WITH_AS(j_array.insert(j_array.begin(), j_primitive.begin(), j_primitive.end()), "[json.exception.invalid_iterator.202] iterators first and last must point to arrays",
+                                     json::invalid_iterator&);
+                CHECK_THROWS_WITH_AS(j_array.insert(j_array.begin(), j_null.begin(), j_null.end()), "[json.exception.invalid_iterator.202] iterators first and last must point to arrays",
+                                     json::invalid_iterator&);
+            }
        }

        SECTION("range for object")
@@ -1682,6 +1682,21 @@ TEST_CASE("issue #5405 - array reserve for definite-length MessagePack arrays")
    }
 }

+TEST_CASE("regression test - MessagePack ext type rejects a subtype that doesn't fit a single byte")
+{
+    // subtype 0-255 must still round-trip correctly (regression guard, pre-existing behavior)
+    CHECK(json::from_msgpack(json::to_msgpack(json::binary({1, 2}, 0))).get_binary().subtype() == 0);
+    CHECK(json::from_msgpack(json::to_msgpack(json::binary({1, 2}, 200))).get_binary().subtype() == 200);
+    CHECK(json::from_msgpack(json::to_msgpack(json::binary({1, 2}, 255))).get_binary().subtype() == 255);
+
+    // a subtype > 255 must throw instead of silently truncating
+    CHECK_THROWS_AS(json::to_msgpack(json::binary({1, 2}, 256)), json::out_of_range);
+    CHECK_THROWS_WITH_AS(json::to_msgpack(json::binary({1, 2}, 70000)), "[json.exception.out_of_range.415] subtype 70000 is too large for the MessagePack ext type (max 255)", json::out_of_range);
+
+    // a binary value with no subtype at all must be unaffected
+    CHECK(json::from_msgpack(json::to_msgpack(json::binary({1, 2}))).get_binary().has_subtype() == false);
+}
+
 // use this testcase outside [hide] to run it with Valgrind
 TEST_CASE("MessagePack nesting does not consume the call stack")
 {
@@ -70,7 +70,7 @@ TEST_CASE("check_for_mem_leak_on_adl_to_json-2")
    }
 }

-TEST_CASE("check_for_mem_leak_on_adl_to_json-2")
+TEST_CASE("check_for_mem_leak_on_adl_to_json-3")
 {
    try
    {
@@ -0,0 +1,91 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  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 is a dedicated, small compile-and-run check for two
+// configuration macros that (per #5423) were never exercised anywhere in the
+// test matrix:
+// - JSON_NO_IO, which removes the library's <istream>/<ostream> support
+//   (operator<<, operator>>, and the stream-based overloads of dump()/parse())
+// - the JSON_THROW_USER / JSON_TRY_USER / JSON_CATCH_USER trio, which lets a
+//   user replace the library's internal exception handling
+//
+// Both macros are about excluding/replacing a facility the library would
+// otherwise pull in on its own, and defining one has no bearing on the other,
+// so -- to keep the test matrix small -- they are exercised together in a
+// single dedicated file instead of two.
+//
+// JSON_NO_IO requires this file itself to never rely on <iostream>/<sstream>;
+// only string-based parsing/dumping is used below.
+#define JSON_NO_IO 1
+
+// The user-supplied exception macros below are a *conforming* replacement:
+// they simply forward to the real throw/try/catch keywords (via a counter so
+// the test can assert each macro was actually invoked, not just defined), so
+// every exception-related behavior the library relies on internally --
+// including rethrowing std::out_of_range as json::out_of_range in at() --
+// keeps working exactly as it would with the library's own default macros.
+static int json_throw_user_call_count = 0; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
+
+#define JSON_THROW_USER(exception) do { ++json_throw_user_call_count; throw (exception); } while (false) // NOLINT(cppcoreguidelines-macro-usage)
+#define JSON_TRY_USER try // NOLINT(cppcoreguidelines-macro-usage)
+#define JSON_CATCH_USER(exception) catch (exception) // NOLINT(cppcoreguidelines-macro-usage)
+
+#include "doctest_compatibility.h"
+
+#include <nlohmann/json.hpp>
+using json = nlohmann::json;
+
+TEST_CASE("JSON_NO_IO")
+{
+    // everything that does not touch <istream>/<ostream> must keep working:
+    // parsing from and dumping to std::string
+    const json j = json::parse(R"({"a":[1,2,3],"b":true})");
+    CHECK(j.dump() == R"({"a":[1,2,3],"b":true})");
+    CHECK(j.at("a").size() == 3);
+    CHECK(j.at("b").get<bool>() == true);
+}
+
+// this test relies on CHECK_THROWS_AS() actually invoking the guarded
+// expression so json_throw_user_call_count gets bumped and can be observed
+// afterwards; doctest's "--no-throw" test filter (which ci_test_noexceptions
+// passes, together with a global -DJSON_NOEXCEPTION added to CMAKE_CXX_FLAGS
+// for every translation unit in that build, this file included) compiles
+// CHECK_THROWS_AS() out to a no-op that never even invokes the given
+// expression -- so json::parse()/at() below would never be called at all and
+// the call-count assertions would fail even though our JSON_THROW_USER
+// override (which always really throws, regardless of JSON_NOEXCEPTION) would
+// have worked fine on its own
+#if !defined(JSON_NOEXCEPTION)
+TEST_CASE("JSON_THROW_USER, JSON_TRY_USER, JSON_CATCH_USER")
+{
+    json_throw_user_call_count = 0;
+
+    // json::parse() is [[nodiscard]] (JSON_HEDLEY_WARN_UNUSED_RESULT); under
+    // GCC in C++11 mode that expands to __attribute__((warn_unused_result)),
+    // which -- unlike a [[nodiscard]] attribute proper -- GCC does not
+    // consider satisfied by doctest's CHECK_THROWS_AS() wrapping the
+    // expression in a (void) cast, so the discarded return value would still
+    // be flagged under -Werror=unused-result; assign it to discard it instead,
+    // matching the established `json _ = json::parse(...)` pattern used
+    // elsewhere in the test suite (see unit-class_parser.cpp)
+    json _; // NOLINT(readability-identifier-naming)
+
+    // a parse error goes through JSON_THROW directly, i.e., through our
+    // JSON_THROW_USER override
+    CHECK_THROWS_AS(_ = json::parse("this is not JSON"), json::parse_error&);
+    CHECK(json_throw_user_call_count > 0);
+
+    // at() on an out-of-range array index internally catches std::out_of_range
+    // (JSON_TRY_USER/JSON_CATCH_USER) and rethrows it as json::out_of_range
+    // (JSON_THROW_USER again), so this exercises all three macros together
+    const int count_before = json_throw_user_call_count;
+    const json arr = json::array({1, 2, 3});
+    CHECK_THROWS_AS(arr.at(10), json::out_of_range&);
+    CHECK(json_throw_user_call_count > count_before);
+}
+#endif
@@ -81,3 +81,84 @@ TEST_CASE("regression test for issue #3732 - iteration_proxy_value<iter_impl<ord
    };
    static_cast<void>(fn);
 }
+
+TEST_CASE("regression test - diff() must account for ordered_json member order")
+{
+    SECTION("pure reorder, no value changes")
+    {
+        ordered_json a = {{"a", 1}, {"b", 2}};
+        ordered_json b = {{"b", 2}, {"a", 1}};
+        CHECK(a != b); // order-sensitive equality
+        CHECK(a.patch(ordered_json::diff(a, b)) == b);
+    }
+
+    SECTION("new key must land at the front")
+    {
+        ordered_json c = {{"b", 2}};
+        ordered_json e = {{"a", 1}, {"b", 2}};
+        CHECK(c.patch(ordered_json::diff(c, e)) == e);
+    }
+
+    SECTION("reorder plus a value change on one of the reordered keys")
+    {
+        ordered_json a = {{"a", 1}, {"b", 2}};
+        ordered_json b = {{"b", 20}, {"a", 1}};
+        CHECK(a != b);
+        CHECK(a.patch(ordered_json::diff(a, b)) == b);
+    }
+
+    SECTION("reorder plus a deleted key")
+    {
+        ordered_json a = {{"a", 1}, {"b", 2}, {"c", 3}};
+        ordered_json b = {{"b", 2}, {"a", 1}};
+        CHECK(a != b);
+        CHECK(a.patch(ordered_json::diff(a, b)) == b);
+    }
+
+    SECTION("reorder plus a nested value that itself needs a recursive diff")
+    {
+        ordered_json a = {{"a", {{"x", 1}, {"y", 2}}}, {"b", 2}};
+        ordered_json b = {{"b", 2}, {"a", {{"x", 1}, {"y", 99}}}};
+        CHECK(a != b);
+        CHECK(a.patch(ordered_json::diff(a, b)) == b);
+    }
+
+    SECTION("three or more keys shuffled into a different order")
+    {
+        ordered_json a = {{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}};
+        ordered_json b = {{"d", 4}, {"b", 2}, {"a", 1}, {"c", 3}};
+        CHECK(a != b);
+        CHECK(a.patch(ordered_json::diff(a, b)) == b);
+    }
+
+    SECTION("matching order still produces a minimal patch (fast path unaffected)")
+    {
+        ordered_json a = {{"a", 1}, {"b", 2}, {"c", 3}};
+        ordered_json b = {{"a", 1}, {"b", 20}, {"c", 3}};
+        auto p = ordered_json::diff(a, b);
+        // only the changed value should be touched, not a wholesale remove+add
+        CHECK(p.size() == 1);
+        CHECK(p[0]["op"] == "replace");
+        CHECK(p[0]["path"] == "/b");
+        CHECK(a.patch(p) == b);
+    }
+
+    SECTION("plain json (std::map-backed) is unaffected by same-key-different-insertion-order")
+    {
+        json a;
+        a["b"] = 2;
+        a["a"] = 1;
+
+        json b;
+        b["a"] = 1;
+        b["b"] = 2;
+
+        // std::map iteration is always sorted by key, so a == b regardless of
+        // insertion order, and diff() must still produce the same minimal
+        // (empty) result as before this fix
+        CHECK(a == b);
+        auto p = json::diff(a, b);
+        CHECK(p.empty());
+        CHECK(a.patch(p) == b);
+    }
+}
@@ -0,0 +1,489 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  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-FileCopyrightText: 2018 Vitaliy Manushkin <agri@akamo.info>
+// SPDX-License-Identifier: MIT
+
+// This file closes a test-coverage gap described in GitHub issue #5421:
+// nlohmann::ordered_json (and other non-default basic_json specializations,
+// such as the alt_string-based one from unit-alt-string.cpp) were never
+// exercised through the binary formats (CBOR/MessagePack/UBJSON/BSON/BJData)
+// or through flatten()/unflatten()/diff()/patch()/merge_patch().
+
+#include "doctest_compatibility.h"
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <string>
+#include <utility>
+#include <vector>
+
+using nlohmann::json;
+using nlohmann::ordered_json;
+
+/////////////////////////////////////////////////////////////////////////////
+// alt_json: a second, independent copy of the custom-string_t basic_json
+// specialization defined in unit-alt-string.cpp.
+//
+// It is duplicated here (rather than shared via a header) because every
+// unit-*.cpp file in this test suite is compiled into its own standalone
+// executable (see tests/CMakeLists.txt), so there is no ODR concern in
+// having the same class name defined in multiple translation units.
+//
+// Two members had to be added relative to the original alt_string
+// (a constructor from std::string, and a find(char, pos) overload) because
+// the original type was never used with the binary writers/readers before
+// this file: BSON's array/document writer converts std::to_string() results
+// and checks for embedded NUL characters via find(char), and the UBJSON/BSON
+// high-precision-number path constructs the SAX string_t argument from a
+// std::string. Neither path is exercised anywhere else in the test suite for
+// this type, which is presumably why the gap was never noticed.
+/////////////////////////////////////////////////////////////////////////////
+
+class alt_string;
+bool operator<(const char* op1, const alt_string& op2) noexcept; // NOLINT(misc-use-internal-linkage)
+void int_to_string(alt_string& target, std::size_t value); // NOLINT(misc-use-internal-linkage)
+
+class alt_string
+{
+  public:
+    using value_type = std::string::value_type;
+
+    static constexpr auto npos = (std::numeric_limits<std::size_t>::max)();
+
+    alt_string(const char* str): str_impl(str) {}
+    alt_string(const char* str, std::size_t count): str_impl(str, count) {}
+    alt_string(std::string str): str_impl(std::move(str)) {}
+    alt_string(size_t count, char chr): str_impl(count, chr) {}
+    alt_string() = default;
+
+    alt_string& append(char ch)
+    {
+        str_impl.push_back(ch);
+        return *this;
+    }
+
+    alt_string& append(const alt_string& str)
+    {
+        str_impl.append(str.str_impl);
+        return *this;
+    }
+
+    alt_string& append(const char* s, std::size_t length)
+    {
+        str_impl.append(s, length);
+        return *this;
+    }
+
+    void push_back(char c)
+    {
+        str_impl.push_back(c);
+    }
+
+    template <typename op_type>
+    bool operator==(const op_type& op) const
+    {
+        return str_impl == op;
+    }
+
+    bool operator==(const alt_string& op) const
+    {
+        return str_impl == op.str_impl;
+    }
+
+    template <typename op_type>
+    bool operator!=(const op_type& op) const
+    {
+        return str_impl != op;
+    }
+
+    bool operator!=(const alt_string& op) const
+    {
+        return str_impl != op.str_impl;
+    }
+
+    std::size_t size() const noexcept
+    {
+        return str_impl.size();
+    }
+
+    void resize(std::size_t n)
+    {
+        str_impl.resize(n);
+    }
+
+    void resize(std::size_t n, char c)
+    {
+        str_impl.resize(n, c);
+    }
+
+    template <typename op_type>
+    bool operator<(const op_type& op) const noexcept
+    {
+        return str_impl < op;
+    }
+
+    bool operator<(const alt_string& op) const noexcept
+    {
+        return str_impl < op.str_impl;
+    }
+
+    const char* c_str() const
+    {
+        return str_impl.c_str();
+    }
+
+    char& operator[](std::size_t index)
+    {
+        return str_impl[index];
+    }
+
+    const char& operator[](std::size_t index) const
+    {
+        return str_impl[index];
+    }
+
+    char& back()
+    {
+        return str_impl.back();
+    }
+
+    const char& back() const
+    {
+        return str_impl.back();
+    }
+
+    void clear()
+    {
+        str_impl.clear();
+    }
+
+    const value_type* data() const
+    {
+        return str_impl.data();
+    }
+
+    bool empty() const
+    {
+        return str_impl.empty();
+    }
+
+    std::size_t find(const alt_string& str, std::size_t pos = 0) const
+    {
+        return str_impl.find(str.str_impl, pos);
+    }
+
+    // needed by binary_writer's BSON support, which probes string keys for
+    // embedded NUL characters via find(char)
+    std::size_t find(char c, std::size_t pos = 0) const
+    {
+        return str_impl.find(c, pos);
+    }
+
+    std::size_t find_first_of(char c, std::size_t pos = 0) const
+    {
+        return str_impl.find_first_of(c, pos);
+    }
+
+    alt_string substr(std::size_t pos = 0, std::size_t count = npos) const
+    {
+        const std::string s = str_impl.substr(pos, count);
+        return {s.data(), s.size()};
+    }
+
+    alt_string& replace(std::size_t pos, std::size_t count, const alt_string& str)
+    {
+        str_impl.replace(pos, count, str.str_impl);
+        return *this;
+    }
+
+    void reserve(std::size_t new_cap = 0)
+    {
+        str_impl.reserve(new_cap);
+    }
+
+  private:
+    std::string str_impl {}; // NOLINT(readability-redundant-member-init)
+
+    friend bool operator<(const char* /*op1*/, const alt_string& /*op2*/) noexcept;
+};
+
+void int_to_string(alt_string& target, std::size_t value)
+{
+    target = std::to_string(value).c_str();
+}
+
+using alt_json = nlohmann::basic_json <
+                 std::map,
+                 std::vector,
+                 alt_string,
+                 bool,
+                 std::int64_t,
+                 std::uint64_t,
+                 double,
+                 std::allocator,
+                 nlohmann::adl_serializer >;
+
+bool operator<(const char* op1, const alt_string& op2) noexcept
+{
+    return op1 < op2.str_impl;
+}
+
+namespace
+{
+
+// collects the object keys of j, in iteration order
+std::vector<std::string> collect_keys(const ordered_json& j)
+{
+    std::vector<std::string> result;
+    for (auto it = j.cbegin(); it != j.cend(); ++it)
+    {
+        result.push_back(it.key());
+    }
+    return result;
+}
+
+// a nested object/array value with keys inserted in non-alphabetical order,
+// used to check both round-trip equality and (for ordered_json) that
+// insertion order survives a trip through a binary format
+ordered_json make_rich_ordered_json()
+{
+    ordered_json j;
+    j["zebra"] = 1;
+    j["apple"] = ordered_json::array({1, 2, 3});
+    j["mango"]["z_nested"] = true;
+    j["mango"]["a_nested"] = nullptr;
+    j["banana"] = "some text";
+    j["cherry"] = 3.14;
+    return j;
+}
+
+alt_json make_rich_alt_json()
+{
+    alt_json j;
+    j["zebra"] = 1;
+    j["apple"] = alt_json::array({1, 2, 3});
+    j["mango"]["z_nested"] = true;
+    j["mango"]["a_nested"] = nullptr;
+    j["banana"] = "some text";
+    j["cherry"] = 3.14;
+    return j;
+}
+
+} // namespace
+
+TEST_CASE("ordered_json across binary formats")
+{
+    const ordered_json original = make_rich_ordered_json();
+    const std::vector<std::string> original_keys = collect_keys(original);
+    const std::vector<std::string> original_mango_keys = collect_keys(original["mango"]);
+
+    SECTION("CBOR")
+    {
+        const auto bytes = ordered_json::to_cbor(original);
+        const auto restored = ordered_json::from_cbor(bytes);
+        CHECK(restored == original);
+        CHECK(collect_keys(restored) == original_keys);
+        CHECK(collect_keys(restored["mango"]) == original_mango_keys);
+    }
+
+    SECTION("MessagePack")
+    {
+        const auto bytes = ordered_json::to_msgpack(original);
+        const auto restored = ordered_json::from_msgpack(bytes);
+        CHECK(restored == original);
+        CHECK(collect_keys(restored) == original_keys);
+        CHECK(collect_keys(restored["mango"]) == original_mango_keys);
+    }
+
+    SECTION("UBJSON")
+    {
+        const auto bytes = ordered_json::to_ubjson(original);
+        const auto restored = ordered_json::from_ubjson(bytes);
+        CHECK(restored == original);
+        CHECK(collect_keys(restored) == original_keys);
+        CHECK(collect_keys(restored["mango"]) == original_mango_keys);
+    }
+
+    SECTION("BSON")
+    {
+        const auto bytes = ordered_json::to_bson(original);
+        const auto restored = ordered_json::from_bson(bytes);
+        CHECK(restored == original);
+        CHECK(collect_keys(restored) == original_keys);
+        CHECK(collect_keys(restored["mango"]) == original_mango_keys);
+    }
+
+    SECTION("BJData")
+    {
+        const auto bytes = ordered_json::to_bjdata(original);
+        const auto restored = ordered_json::from_bjdata(bytes);
+        CHECK(restored == original);
+        CHECK(collect_keys(restored) == original_keys);
+        CHECK(collect_keys(restored["mango"]) == original_mango_keys);
+    }
+}
+
+TEST_CASE("alt_json (custom string_t) across binary formats")
+{
+    const alt_json original = make_rich_alt_json();
+
+    SECTION("CBOR")
+    {
+        const auto bytes = alt_json::to_cbor(original);
+        const auto restored = alt_json::from_cbor(bytes);
+        CHECK(restored == original);
+    }
+
+    SECTION("MessagePack")
+    {
+        const auto bytes = alt_json::to_msgpack(original);
+        const auto restored = alt_json::from_msgpack(bytes);
+        CHECK(restored == original);
+    }
+
+    SECTION("UBJSON")
+    {
+        const auto bytes = alt_json::to_ubjson(original);
+        const auto restored = alt_json::from_ubjson(bytes);
+        CHECK(restored == original);
+    }
+
+    SECTION("BSON")
+    {
+        const auto bytes = alt_json::to_bson(original);
+        const auto restored = alt_json::from_bson(bytes);
+        CHECK(restored == original);
+    }
+
+    SECTION("BJData")
+    {
+        const auto bytes = alt_json::to_bjdata(original);
+        const auto restored = alt_json::from_bjdata(bytes);
+        CHECK(restored == original);
+    }
+}
+
+TEST_CASE("ordered_json operator== is sensitive to key order")
+{
+    // Unlike nlohmann::json (whose object_t is a std::map, so equality never
+    // depends on insertion order), ordered_json's object_t (ordered_map) is a
+    // std::vector<std::pair<Key, T>> under the hood, and does not define its
+    // own operator==: it inherits std::vector's element-wise comparison. As a
+    // result, two ordered_json objects holding the very same key/value pairs
+    // in different insertion order compare *unequal*. This is the property
+    // that makes the round-trip `CHECK(restored == original)` checks above a
+    // meaningful order-preservation check by themselves (the explicit
+    // collect_keys() comparisons make that check explicit/readable, and
+    // guard against this operator== behavior ever changing).
+    ordered_json a;
+    a["x"] = 1;
+    a["y"] = 2;
+
+    ordered_json b;
+    b["y"] = 2;
+    b["x"] = 1;
+
+    CHECK(a.size() == b.size());
+    CHECK(a["x"] == b["x"]);
+    CHECK(a["y"] == b["y"]);
+    CHECK_FALSE(a == b);
+}
+
+TEST_CASE("duplicate keys in a binary-encoded object")
+{
+    // CBOR encoding of a map with two entries under the same key "a": {"a": 1, "a": 2}
+    const std::vector<std::uint8_t> cbor_bytes
+    {
+        0xA2, 0x61, 'a', 0x01, 0x61, 'a', 0x02
+    };
+
+    // Both json (std::map, via operator[]) and ordered_json (ordered_map, via
+    // operator[]) build binary-decoded objects by looking up/creating the
+    // entry for each incoming key and then assigning the value into it. This
+    // means a repeated key does *not* produce two entries in either case;
+    // instead, the *first* occurrence's position is kept (relevant only for
+    // ordered_json) while the *last* occurrence's value wins (for both) --
+    // this matches operator[]'s "assign the referenced slot" semantics, and
+    // is worth noting because it differs from the initializer-list
+    // construction path (`ordered_json{{"a",1},{"a",2}}`), which builds
+    // through insert()/emplace() and therefore keeps the *first* value, not
+    // the last (see the "There are no dup keys..." case in
+    // unit-ordered_json.cpp).
+    const auto j = json::from_cbor(cbor_bytes);
+    const auto oj = ordered_json::from_cbor(cbor_bytes);
+
+    CHECK(j.size() == 1);
+    CHECK(oj.size() == 1);
+    CHECK(j["a"] == 2);
+    CHECK(oj["a"] == 2);
+    CHECK(j == json(oj));
+}
+
+TEST_CASE("ordered_json through flatten/unflatten")
+{
+    const ordered_json original = make_rich_ordered_json();
+    const std::vector<std::string> original_keys = collect_keys(original);
+    const std::vector<std::string> original_mango_keys = collect_keys(original["mango"]);
+
+    const ordered_json flat = original.flatten();
+    const ordered_json unflattened = flat.unflatten();
+
+    CHECK(unflattened == original);
+    // flatten() walks the value depth-first in iteration order and
+    // unflatten() re-inserts each flattened key via operator[] in the flat
+    // object's iteration order, so for ordered_json the original key order
+    // (both top-level and nested) is preserved end-to-end.
+    CHECK(collect_keys(unflattened) == original_keys);
+    CHECK(collect_keys(unflattened["mango"]) == original_mango_keys);
+}
+
+TEST_CASE("ordered_json through diff/patch/patch_inplace")
+{
+    ordered_json original;
+    original["one"] = 1;
+    original["two"] = 2;
+    original["three"] = 3;
+
+    ordered_json target = original;
+    target["one"] = 100;      // replace
+    target.erase("two");      // remove
+    target["four"] = 4;       // add
+
+    const ordered_json patch = ordered_json::diff(original, target);
+
+    SECTION("patch")
+    {
+        const ordered_json patched = original.patch(patch);
+        CHECK(patched == target);
+    }
+
+    SECTION("patch_inplace")
+    {
+        ordered_json copy = original;
+        copy.patch_inplace(patch);
+        CHECK(copy == target);
+    }
+}
+
+TEST_CASE("ordered_json through merge_patch")
+{
+    ordered_json original;
+    original["a"] = 1;
+    original["b"] = 2;
+
+    const ordered_json patch = {{"b", nullptr}, {"c", 3}};
+
+    original.merge_patch(patch);
+
+    ordered_json expected;
+    expected["a"] = 1;
+    expected["c"] = 3;
+
+    CHECK(original == expected);
+    CHECK(collect_keys(original) == collect_keys(expected));
+}
@@ -606,7 +606,11 @@ TEST_CASE("regression tests 2")
    SECTION("issue #2546 - parsing containers of std::byte")
    {
        const char DATA[] = R"("Hello, world!")"; // NOLINT(misc-const-correctness,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
-        const auto s = std::as_bytes(std::span(DATA));
+        // exclude the trailing '\0' that string-literal initialization adds to
+        // DATA: std::span(DATA) would span the full array extent (including
+        // that NUL), which is only silently accepted as end-of-input by default
+        // and would fail under JSON_STRICT_NUL_HANDLING
+        const auto s = std::as_bytes(std::span(DATA, sizeof(DATA) - 1));
        const json j = json::parse(s);
        CHECK(j.dump() == "\"Hello, world!\"");
    }
@@ -763,4 +767,106 @@ TEST_CASE("regression tests 2")

 }

+TEST_CASE("regression test - parser callback must not lose a duplicate key's prior value")
+{
+    // a callback that rejects only the scalar value 2
+    const json::parser_callback_t drop_value_2 = [](int /*depth*/, json::parse_event_t ev, json & v) noexcept
+    {
+        return !(ev == json::parse_event_t::value && v == 2);
+    };
+
+    SECTION("duplicate key, second (scalar) value rejected - prior value is restored")
+    {
+        const json j = json::parse(R"({"a":1,"a":2})", drop_value_2);
+        CHECK(j.dump() == "{\"a\":1}");
+    }
+
+    SECTION("duplicate key, second value is an object rejected at object_end - prior value is restored")
+    {
+        const json j = json::parse(R"({"a":1,"a":{"x":2}})",
+                                   [](int depth, json::parse_event_t ev, json& /*parsed*/) noexcept
+        {
+            return !(ev == json::parse_event_t::object_end && depth == 1);
+        });
+        CHECK(j.dump() == "{\"a\":1}");
+    }
+
+    SECTION("duplicate key, second value is an array rejected at array_end - prior value is restored")
+    {
+        const json j = json::parse(R"({"a":1,"a":[9,9]})",
+                                   [](int depth, json::parse_event_t ev, json& /*parsed*/) noexcept
+        {
+            return !(ev == json::parse_event_t::array_end && depth == 1);
+        });
+        CHECK(j.dump() == "{\"a\":1}");
+    }
+
+    SECTION("duplicate key, second value accepted (scalar) - last value wins")
+    {
+        const json j = json::parse(R"({"a":1,"a":2})", [](int, json::parse_event_t, json&) noexcept
+        {
+            return true;
+        });
+        CHECK(j.dump() == "{\"a\":2}");
+    }
+
+    SECTION("duplicate key, second value accepted (object) - last value wins")
+    {
+        const json j = json::parse(R"({"a":1,"a":{"x":2}})", [](int, json::parse_event_t, json&) noexcept
+        {
+            return true;
+        });
+        CHECK(j.dump() == "{\"a\":{\"x\":2}}");
+    }
+
+    SECTION("brand new (non-duplicate) key, value rejected - member is fully absent")
+    {
+        const json j = json::parse(R"({"a":1,"b":2})", drop_value_2);
+        CHECK(j.dump() == "{\"a\":1}");
+    }
+
+    SECTION("duplicate key nested two levels deep")
+    {
+        const json j = json::parse(R"({"outer":{"a":1,"a":2}})", drop_value_2);
+        CHECK(j.dump() == "{\"outer\":{\"a\":1}}");
+    }
+
+    SECTION("three occurrences of the same key - middle rejected, last accepted")
+    {
+        const json j = json::parse(R"({"k":1,"k":2,"k":3})", drop_value_2);
+        CHECK(j.dump() == "{\"k\":3}");
+    }
+}
+
+TEST_CASE("regression test - excessive binary container size honors allow_exceptions=false")
+{
+    // CBOR array with declared length 2^63
+    const std::vector<std::uint8_t> cbor = {0x9b, 0x80, 0, 0, 0, 0, 0, 0, 0};
+    // CBOR map with declared length 2^63
+    const std::vector<std::uint8_t> cbor_m = {0xbb, 0x80, 0, 0, 0, 0, 0, 0, 0};
+    // UBJSON array with declared length 2^63-1
+    const std::vector<std::uint8_t> ubj = {'[', '#', 'L', 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
+    // BJData array with declared length 2^63-1 (little endian)
+    const std::vector<std::uint8_t> bjd = {'[', '#', 'L', 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f};
+
+    // allow_exceptions=false must report failure instead of throwing/aborting
+    CHECK(json::from_cbor(cbor, true, false).is_discarded());
+    CHECK(json::from_cbor(cbor_m, true, false).is_discarded());
+    CHECK(json::from_ubjson(ubj, true, false).is_discarded());
+    CHECK(json::from_bjdata(bjd, true, false).is_discarded());
+
+    // allow_exceptions=true (the default) must still throw exactly as before.
+    // The exact message text is not checked here: on platforms where
+    // std::size_t is 32-bit, the CBOR reader's own length-narrowing check
+    // (get_cbor_container_size(), unrelated to this fix) intercepts a
+    // declared length of 2^63 before it ever reaches the check this test
+    // targets, with different (but equally valid, and already correct)
+    // wording -- see unit-cbor.cpp for coverage of that message.
+    json _;
+    CHECK_THROWS_AS(_ = json::from_cbor(cbor), json::out_of_range);
+
+    // regression guard: a genuinely truncated CBOR input must remain discarded
+    CHECK(json::from_cbor(std::vector<std::uint8_t> {0x9b, 0, 0, 0, 0, 0, 0, 0, 0x02}, true, false).is_discarded());
+}
+
 DOCTEST_CLANG_SUPPRESS_WARNING_POP
@@ -18,6 +18,14 @@
 // for some reason including this after the json header leads to linker errors with VS 2017...
 #include <locale>

+// skip tests if JSON_DisableEnumSerialization=ON (#4384): std::byte is a
+// scoped enum, so get<std::byte>() (needed below to get<std::vector<std::byte>>()
+// from a plain JSON array, not just from an already-binary value) relies on
+// enum serialization being enabled
+#if defined(JSON_DISABLE_ENUM_SERIALIZATION) && (JSON_DISABLE_ENUM_SERIALIZATION == 1)
+    #define SKIP_TESTS_FOR_ENUM_SERIALIZATION
+#endif
+
 #define JSON_TESTS_PRIVATE
 #include <nlohmann/json.hpp>
 using json = nlohmann::json;
@@ -466,6 +474,7 @@ TEST_CASE("regression tests 3")
        CHECK((decoded == json_4804::array()));
    }

+#ifndef SKIP_TESTS_FOR_ENUM_SERIALIZATION
    SECTION("discussion #4209 - custom BinaryType direct assignment and round-tripping")
    {
        // Test that assigning a custom BinaryType directly creates a binary value, not an array
@@ -499,6 +508,7 @@ TEST_CASE("regression tests 3")
        CHECK(extracted[1] == std::byte{2});
        CHECK(extracted[2] == std::byte{3});
    }
+#endif

    SECTION("issue #5046 - implicit conversion of return json to std::optional no longer implicit")
    {
@@ -522,6 +522,19 @@ TEST_CASE("indentation is written straight into the write buffer")
        CHECK(json::parse(out) == j);
    }

+    SECTION("binary values are indented the same way")
+    {
+        // a binary value is serialized as an object with "bytes" and
+        // "subtype" keys; the byte array itself is always written compactly
+        // (see dump_byte()), so only the surrounding object's indentation
+        // goes through put_indent()
+        const json j = json::binary({1, 2, 3}, 128);
+        CHECK(j.dump(2000) == "{\n" + std::string(2000, ' ') + "\"bytes\": [1, 2, 3],\n"
+              + std::string(2000, ' ') + "\"subtype\": 128\n}");
+        CHECK(j.dump(2000, '\t') == "{\n" + std::string(2000, '\t') + "\"bytes\": [1, 2, 3],\n"
+              + std::string(2000, '\t') + "\"subtype\": 128\n}");
+    }
+
    SECTION("indentation is unchanged for ordinary widths")
    {
        const json j = {{"a", {1, 2}}, {"b", nullptr}};
@@ -17,6 +17,7 @@

 #include <nlohmann/json.hpp>
 using json = nlohmann::json;
+using ordered_json = nlohmann::ordered_json;

 // JSON_HAS_CPP_20 (do not remove; see note at top of file)
 #if JSON_HAS_STD_FORMAT
@@ -52,6 +53,23 @@ TEST_CASE("std::formatter<nlohmann::json>")
        CHECK(std::format("{:2}", j) == j.dump(2));
        CHECK(std::format("{:#2}", j) == j.dump(2));
        CHECK(std::format("{:8}", j) == j.dump(8));
+        // multi-digit widths must accumulate every digit, not just the first
+        CHECK(std::format("{:12}", j) == j.dump(12));
+        CHECK(std::format("{:#12}", j) == j.dump(12));
+        CHECK(std::format("{:10}", j) == j.dump(10));
+    }
+
+    SECTION("bare alignment with no fill character defaults to a space indent character")
+    {
+        const json j = {{"foo", 1}, {"bar", {1, 2, 3}}};
+        // without a preceding fill character, the alignment character itself must not
+        // be mistaken for the indent character -- the default space is kept
+        CHECK(std::format("{:<}", j) == j.dump());
+        CHECK(std::format("{:>}", j) == j.dump());
+        CHECK(std::format("{:^}", j) == j.dump());
+        CHECK(std::format("{:<3}", j) == j.dump(3, ' '));
+        CHECK(std::format("{:>3}", j) == j.dump(3, ' '));
+        CHECK(std::format("{:^3}", j) == j.dump(3, ' '));
    }

    SECTION("fill-and-align sets the indent character, like dump(indent, indent_char)")
@@ -93,4 +111,16 @@ TEST_CASE("std::formatter<nlohmann::json>")
    }
 }

+TEST_CASE("std::formatter<nlohmann::ordered_json>")
+{
+    // spot-check a non-default basic_json instantiation, since the formatter
+    // is written against the generic NLOHMANN_BASIC_JSON_TPL_DECLARATION
+    // template and must actually instantiate (and behave correctly) for
+    // template arguments other than nlohmann::json
+    const ordered_json j = {{"foo", 1}, {"bar", {1, 2, 3}}};
+    CHECK(std::format("{}", j) == j.dump());
+    CHECK(std::format("{:#}", j) == j.dump(4));
+    CHECK(std::format("{:2}", j) == j.dump(2));
+}
+
 #endif
@@ -306,8 +306,8 @@ TEST_CASE("Unicode (3/5)" * doctest::skip())
                        {
                            for (int byte4 = 0x00; byte4 <= 0xFF; ++byte4)
                            {
-                                // skip fourth second byte
-                                if (0x80 <= byte3 && byte3 <= 0xBF)
+                                // skip correct fourth byte
+                                if (0x80 <= byte4 && byte4 <= 0xBF)
                                {
                                    continue;
                                }
@@ -307,7 +307,7 @@ TEST_CASE("Unicode (4/5)" * doctest::skip())
                            for (int byte4 = 0x00; byte4 <= 0xFF; ++byte4)
                            {
                                // skip correct fourth byte
-                                if (0x80 <= byte3 && byte3 <= 0xBF)
+                                if (0x80 <= byte4 && byte4 <= 0xBF)
                                {
                                    continue;
                                }
@@ -307,7 +307,7 @@ TEST_CASE("Unicode (5/5)" * doctest::skip())
                            for (int byte4 = 0x00; byte4 <= 0xFF; ++byte4)
                            {
                                // skip correct fourth byte
-                                if (0x80 <= byte3 && byte3 <= 0xBF)
+                                if (0x80 <= byte4 && byte4 <= 0xBF)
                                {
                                    continue;
                                }