Merge branch 'develop' of https://github.com/nlohmann/json into bon8

Conflicts: docs/mkdocs/docs/api/basic_json/index.md docs/mkdocs/docs/features/binary_formats/index.md docs/mkdocs/mkdocs.yml tests/src/unit-binary_formats.cpp
2024-11-28 00:59:02 +08:00 · 2022-06-18 21:19:48 +02:00 · 2022-06-18 21:19:48 +02:00 · dfdbbc71bb
commit dfdbbc71bb
parent ad662d15bc 87cda1d664
146 changed files with 5201 additions and 1259 deletions
--- a/.clang-tidy
+++ b/.clang-tidy
@ -43,6 +43,7 @@ Checks: '*,
         -readability-identifier-length,
         -readability-magic-numbers,
         -readability-redundant-access-specifiers,
+         -readability-simplify-boolean-expr
         -readability-uppercase-literal-suffix'

 CheckOptions:
--- a/.github/workflows/macos.yml
+++ b/.github/workflows/macos.yml
@ -10,7 +10,7 @@ on:
  workflow_dispatch:

 jobs:
-  xcode:
+  xcode_1:
    runs-on: macos-10.15
    strategy:
      matrix:
@ -27,8 +27,25 @@ jobs:
      - name: test
        run: cd build ; ctest -j 10 --output-on-failure

+  xcode_2:
+    runs-on: macos-12
+    strategy:
+      matrix:
+        xcode: [13.3.1, 13.3, 13.2.1, 13.2, 13.1]
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: cmake
+        run: cmake -S . -B build -D CMAKE_BUILD_TYPE=Debug -DJSON_BuildTests=On -DJSON_FastTests=ON
+      - name: build
+        run: cmake --build build --parallel 10
+      - name: test
+        run: cd build ; ctest -j 10 --output-on-failure
+
  xcode_standards:
-    runs-on: macos-10.15
+    runs-on: macos-latest
    strategy:
      matrix:
        standard: [11, 14, 17, 20]
--- a/.github/workflows/ubuntu.yml
+++ b/.github/workflows/ubuntu.yml
@ -12,7 +12,7 @@ on:
 jobs:
  ci_test_clang:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    steps:
      - uses: actions/checkout@v3
      - name: cmake
@ -22,7 +22,7 @@ jobs:

  ci_test_gcc:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    steps:
      - uses: actions/checkout@v3
      - name: cmake
@ -32,7 +32,7 @@ jobs:

  ci_static_analysis:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    strategy:
      matrix:
        target: [ci_clang_tidy, ci_cppcheck, ci_test_valgrind, ci_test_clang_sanitizer, ci_test_amalgamation, ci_clang_analyze, ci_cpplint, ci_cmake_flags, ci_single_binaries, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_infer]
@ -43,12 +43,22 @@ jobs:
      - name: build
        run: cmake --build build --target ${{ matrix.target }}

+  ci_test_single_header:
+    runs-on: ubuntu-latest
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
+    steps:
+      - uses: actions/checkout@v3
+      - name: cmake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: build
+        run: cmake --build build --target ci_test_single_header
+
  ci_cmake_options:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    strategy:
      matrix:
-        target: [ci_test_diagnostics, ci_test_noexceptions, ci_test_noimplicitconversions]
+        target: [ci_test_diagnostics, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison]
    steps:
      - uses: actions/checkout@v3
      - name: cmake
@ -58,7 +68,7 @@ jobs:

  ci_test_coverage:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    steps:
      - uses: actions/checkout@v3
      - name: cmake
@ -78,10 +88,10 @@ jobs:

  ci_test_compilers:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    strategy:
      matrix:
-        compiler: [g++-4.8, g++-4.9, g++-5, g++-6, g++-7, g++-8, g++-9, g++-10, clang++-3.5, clang++-3.6, clang++-3.7, clang++-3.8, clang++-3.9, clang++-4.0, clang++-5.0, clang++-6.0, clang++-7, clang++-8, clang++-9, clang++-10, clang++-11, clang++-12, clang++-13, clang++-14]
+        compiler: [g++-4.8, g++-4.9, g++-5, g++-6, g++-7, g++-8, g++-9, g++-10, g++-11, clang++-3.5, clang++-3.6, clang++-3.7, clang++-3.8, clang++-3.9, clang++-4.0, clang++-5.0, clang++-6.0, clang++-7, clang++-8, clang++-9, clang++-10, clang++-11, clang++-12, clang++-13, clang++-14]
    steps:
      - uses: actions/checkout@v3
      - name: cmake
@ -91,7 +101,7 @@ jobs:

  ci_test_standards:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    strategy:
      matrix:
        standard: [11, 14, 17, 20]
@ -105,10 +115,22 @@ jobs:

  ci_cuda_example:
    runs-on: ubuntu-latest
-    container: ghcr.io/nlohmann/json-ci:v2.3.0
+    container: ghcr.io/nlohmann/json-ci:v2.4.0
    steps:
      - uses: actions/checkout@v3
      - name: cmake
        run: cmake -S . -B build -DJSON_CI=On
      - name: build
        run: cmake --build build --target ci_cuda_example
+
+  ci_icpc:
+    runs-on: ubuntu-latest
+    container: ghcr.io/nlohmann/json-ci:v2.2.0
+    steps:
+      - uses: actions/checkout@v2
+      - name: cmake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: build
+        run: |
+          . /opt/intel/oneapi/setvars.sh
+          cmake --build build --target ci_icpc
--- a/.gitignore
+++ b/.gitignore
@ -19,6 +19,10 @@
 # build directories (vscode-cmake-tools, user-defined, ...)
 /build*/

+# fuzzers
+/tests/parse_*_fuzzer
+/tests/corpus_*
+
 /docs/mkdocs/docs/examples/
 /docs/mkdocs/docs/__pycache__/
 /docs/mkdocs/site/
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -37,13 +37,15 @@ if(${MAIN_PROJECT} AND (${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION}
 else()
    set(JSON_BuildTests_INIT OFF)
 endif()
-option(JSON_BuildTests          "Build the unit tests when BUILD_TESTING is enabled." ${JSON_BuildTests_INIT})
-option(JSON_CI                  "Enable CI build targets." OFF)
-option(JSON_Diagnostics         "Use extended diagnostic messages." OFF)
-option(JSON_ImplicitConversions "Enable implicit conversions." ON)
-option(JSON_Install             "Install CMake targets during install step." ${MAIN_PROJECT})
-option(JSON_MultipleHeaders     "Use non-amalgamated version of the library." OFF)
-option(JSON_SystemInclude       "Include as system headers (skip for clang-tidy)." OFF)
+option(JSON_BuildTests                     "Build the unit tests when BUILD_TESTING is enabled." ${JSON_BuildTests_INIT})
+option(JSON_CI                             "Enable CI build targets." OFF)
+option(JSON_Diagnostics                    "Use extended diagnostic messages." OFF)
+option(JSON_ImplicitConversions            "Enable implicit conversions." ON)
+option(JSON_DisableEnumSerialization       "Disable default integer enum serialization." OFF)
+option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value comparison." OFF)           
+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)

 if (JSON_CI)
    include(ci)
@ -77,6 +79,14 @@ if (NOT JSON_ImplicitConversions)
    message(STATUS "Implicit conversions are disabled")
 endif()

+if (JSON_DisableEnumSerialization)
+    message(STATUS "Enum integer serialization is disabled")
+endif()
+
+if (JSON_LegacyDiscardedValueComparison)
+    message(STATUS "Legacy discarded value comparison enabled")
+endif()
+
 if (JSON_Diagnostics)
    message(STATUS "Diagnostics enabled")
 endif()
@ -100,8 +110,10 @@ endif()
 target_compile_definitions(
    ${NLOHMANN_JSON_TARGET_NAME}
    INTERFACE
-    JSON_USE_IMPLICIT_CONVERSIONS=$<BOOL:${JSON_ImplicitConversions}>
-    JSON_DIAGNOSTICS=$<BOOL:${JSON_Diagnostics}>
+    $<$<NOT:$<BOOL:${JSON_ImplicitConversions}>>:JSON_USE_IMPLICIT_CONVERSIONS=0>
+    $<$<BOOL:${JSON_DisableEnumSerialization}>:JSON_DISABLE_ENUM_SERIALIZATION=1>
+    $<$<BOOL:${JSON_Diagnostics}>:JSON_DIAGNOSTICS=1>
+    $<$<BOOL:${JSON_LegacyDiscardedValueComparison}>:JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1>
 )

 target_include_directories(
--- a/README.md
+++ b/README.md
@ -54,7 +54,7 @@ There are myriads of [JSON](https://json.org) libraries out there, and each may

 - **Trivial integration**. Our whole code consists of a single header file [`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp). That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.

- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).
+- **Serious testing**. Our code is heavily [unit-tested](https://github.com/nlohmann/json/tree/develop/tests/src) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no memory leaks. [Google OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/json) additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the [Core Infrastructure Initiative (CII) best practices](https://bestpractices.coreinfrastructure.org/projects/289).

 Other aspects were not so important to us:

@ -69,6 +69,10 @@ See the [contribution guidelines](https://github.com/nlohmann/json/blob/master/.

 You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nlohmann).

+### :office: Corporate Sponsor
+
+[![](https://upload.wikimedia.org/wikipedia/commons/thumb/9/9e/Codacy-logo-black.svg/320px-Codacy-logo-black.svg.png)](https://github.com/codacy)
+
 ### :label: Named Sponsors

 - [Michael Hartmann](https://github.com/reFX-Mike)
@ -1083,18 +1087,11 @@ The following compilers are currently used in continuous integration at [AppVeyo
 | Apple Clang 12.0.0 (clang-1200.0.32.27); Xcode 12.2                                                    | macOS 10.15.7      | GitHub Actions |
 | Apple Clang 12.0.0 (clang-1200.0.32.28); Xcode 12.3                                                    | macOS 10.15.7      | GitHub Actions |
 | Apple Clang 12.0.0 (clang-1200.0.32.29); Xcode 12.4                                                    | macOS 10.15.7      | GitHub Actions |
-| GCC 4.8.5 (Ubuntu 4.8.5-4ubuntu2)                                                                      | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 4.9.3 (Ubuntu 4.9.3-13ubuntu2)                                                                     | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 5.4.0 (Ubuntu 5.4.0-6ubuntu1~16.04.12)                                                             | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 6.4.0 (Ubuntu 6.4.0-17ubuntu1)                                                                     | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 7.5.0 (Ubuntu 7.5.0-6ubuntu2)                                                                      | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 8.1.0 (x86_64-posix-seh-rev0, Built by MinGW-W64 project)                                          | Windows-10.0.17763 | GitHub Actions |
-| GCC 8.1.0 (i686-posix-dwarf-rev0, Built by MinGW-W64 project)                                          | Windows-10.0.17763 | GitHub Actions |
-| GCC 8.4.0 (Ubuntu 8.4.0-3ubuntu2)                                                                      | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04)                                                               | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 10.2.0 (Ubuntu 10.2.0-5ubuntu1~20.04)                                                              | Ubuntu 20.04.3 LTS | GitHub Actions |
-| GCC 11.1.0                                                                                             | Ubuntu (aarch64)   | Drone CI       |
-| GCC 12.0.0 20211219 (experimental)                                                                     | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Apple Clang 13.0.0 (clang-1300.0.29.3); Xcode 13.1                                                     | macOS 12.3.1       | GitHub Actions |
+| Apple Clang 13.0.0 (clang-1300.0.29.30); Xcode 13.2                                                    | macOS 12.3.1       | GitHub Actions |
+| Apple Clang 13.0.0 (clang-1300.0.29.30); Xcode 13.2.1                                                  | macOS 12.3.1       | GitHub Actions |
+| Apple Clang 13.1.6 (clang-1316.0.21.2); Xcode 13.3                                                     | macOS 12.3.1       | GitHub Actions |
+| Apple Clang 13.1.6 (clang-1316.0.21.2.3); Xcode 13.3.1                                                 | macOS 12.3.1       | GitHub Actions |
 | Clang 3.5.2 (3.5.2-3ubuntu1)                                                                           | Ubuntu 20.04.3 LTS | GitHub Actions |
 | Clang 3.6.2 (3.6.2-3ubuntu2)                                                                           | Ubuntu 20.04.3 LTS | GitHub Actions |
 | Clang 3.7.1 (3.7.1-2ubuntu2)                                                                           | Ubuntu 20.04.3 LTS | GitHub Actions |
@ -1113,8 +1110,22 @@ The following compilers are currently used in continuous integration at [AppVeyo
 | Clang 11.0.0 (11.0.0-2~ubuntu20.04.1)                                                                  | Ubuntu 20.04.3 LTS | GitHub Actions |
 | Clang 12.0.0 (12.0.0-3ubuntu1~20.04.3)                                                                 | Ubuntu 20.04.3 LTS | GitHub Actions |
 | Clang 13.0.1 (13.0.1-++20211015123032+cf15ccdeb6d5-1exp120211015003613.5)                              | Ubuntu 20.04.3 LTS | GitHub Actions |
-| Clang 14.0.0 (14.0.0-++20211221052852+55c71c9eac9b-1exp120211221172954.95)                             | Ubuntu 20.04.3 LTS | GitHub Actions |
-| Clang 15.0.0 (15.0.0-++20220403052648+896770c9a92e-1~exp1~20220403172744.209)                          | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 14.0.5-++20220603124341+2f0a69c32a4c-1~exp1~20220603124352.149                                   | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Clang 15.0.0 (15.0.0-++20220530052901+b7d2b160c3ba-1~exp1~20220530172952.268)                          | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 4.8.5 (Ubuntu 4.8.5-4ubuntu2)                                                                      | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 4.9.3 (Ubuntu 4.9.3-13ubuntu2)                                                                     | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 5.4.0 (Ubuntu 5.4.0-6ubuntu1~16.04.12)                                                             | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 6.4.0 (Ubuntu 6.4.0-17ubuntu1)                                                                     | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 7.5.0 (Ubuntu 7.5.0-6ubuntu2)                                                                      | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 8.1.0 (i686-posix-dwarf-rev0, Built by MinGW-W64 project)                                          | Windows-10.0.17763 | GitHub Actions |
+| GCC 8.1.0 (x86_64-posix-seh-rev0, Built by MinGW-W64 project)                                          | Windows-10.0.17763 | GitHub Actions |
+| GCC 8.4.0 (Ubuntu 8.4.0-3ubuntu2)                                                                      | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04)                                                               | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 10.2.0 (Ubuntu 10.2.0-5ubuntu1~20.04)                                                              | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 11.1.0                                                                                             | Ubuntu (aarch64)   | Drone CI       |
+| GCC 11.1.0 (Ubuntu 11.1.0-1ubuntu1~20.04)                                                              | Ubuntu 20.04.3 LTS | GitHub Actions |
+| GCC 13.0.0 13.0.0 20220605 (experimental)                                                              | Ubuntu 20.04.3 LTS | GitHub Actions |
+| Intel C++ Compiler 2021.5.0.20211109                                                                   | Ubuntu 20.04.3 LTS | GitHub Actions |
 | NVCC 11.0.221                                                                                          | Ubuntu 20.04.3 LTS | GitHub Actions |
 | Visual Studio 14 2015 MSVC 19.0.24241.7 (Build Engine version 14.0.25420.1)                            | Windows-6.3.9600   | AppVeyor       |
 | Visual Studio 15 2017 MSVC 19.16.27035.0 (Build Engine version 15.9.21+g9802d43bc3 for .NET Framework) | Windows-10.0.14393 | AppVeyor       |
@ -1598,6 +1609,21 @@ I deeply appreciate the help of the following people.
 - [Dirk Stolle](https://github.com/striezel) fixed typos in documentation.
 - [Daniel Albuschat](https://github.com/daniel-kun) corrected the parameter name in the `parse` documentation.
 - [Prince Mendiratta](https://github.com/Prince-Mendiratta) fixed a link to the FAQ.
+- [Florian Albrechtskirchinger](https://github.com/falbrechtskirchinger) implemented `std::string_view` support for object keys and made dozens of other improvements.
+- [Qianqian Fang](https://github.com/fangq) implemented the Binary JData (BJData) format.
+- [pketelsen](https://github.com/pketelsen) added macros `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT` and `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`.
+- [DarkZeros](https://github.com/DarkZeros) adjusted to code to not clash with Arduino defines.
+- [flagarde](https://github.com/flagarde) fixed the output of `meta()` for MSVC.
+- [Giovanni Cerretani](https://github.com/gcerretani) fixed a check for `std::filesystem`.
+- [Dimitris Apostolou](https://github.com/rex4539) fixed a typo.
+- [Ferry Huberts](https://github.com/fhuberts) fixed a typo.
+- [Michael Nosthoff](https://github.com/heinemml) fixed a typo.
+- [JungHoon Lee](https://github.com/jhnlee) fixed a typo.
+- [Faruk D.](https://github.com/fdiblen) fixed the CITATION.CFF file.
+- [Andrea Cocito](https://github.com/puffetto) added a clarification on macro usage to the documentation.
+- [Krzysiek Karbowiak](https://github.com/kkarbowiak) refactored the tests to use `CHECK_THROWS_WITH_AS`.
+- [Chaoqi Zhang](https://github.com/prncoprs) fixed a typo.
+- [ivanovmp](https://github.com/ivanovmp) fixed a whitespace error.

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

@ -1612,7 +1638,7 @@ The library itself consists of a single header file licensed under the MIT licen
 - [**Artistic Style**](http://astyle.sourceforge.net) for automatic source code indentation
 - [**Clang**](https://clang.llvm.org) for compilation with code sanitizers
 - [**CMake**](https://cmake.org) for build automation
- [**Codacity**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
+- [**Codacy**](https://www.codacy.com) for further [code analysis](https://www.codacy.com/app/nlohmann/json)
 - [**Coveralls**](https://coveralls.io) to measure [code coverage](https://coveralls.io/github/nlohmann/json)
 - [**Coverity Scan**](https://scan.coverity.com) for [static analysis](https://scan.coverity.com/projects/nlohmann-json)
 - [**cppcheck**](http://cppcheck.sourceforge.net) for static analysis
@ -1632,7 +1658,7 @@ The library itself consists of a single header file licensed under the MIT licen

 ## Projects using JSON for Modern C++

-The library is currently used in Apple macOS Sierra and iOS 10. I am not sure what they are using the library for, but I am happy that it runs on so many devices.
+The library is currently used in Apple macOS Sierra-Monterey and iOS 10-15. I am not sure what they are using the library for, but I am happy that it runs on so many devices.


 ## Notes
--- a/cmake/ci.cmake
+++ b/cmake/ci.cmake
@ -111,7 +111,7 @@ set(CLANG_CXXFLAGS
    -Wno-reserved-identifier
 )

-# Warning flags determined for GCC 12.0 (experimental) with https://github.com/nlohmann/gcc_flags:
+# Warning flags determined for GCC 13.0 (experimental) with https://github.com/nlohmann/gcc_flags:
 # Ignored GCC warnings:
 # -Wno-abi-tag                    We do not care about ABI tags.
 # -Wno-aggregate-return           The library uses aggregate returns.
@ -161,10 +161,13 @@ set(GCC_CXXFLAGS
    -Wanalyzer-use-after-free
    -Wanalyzer-use-of-pointer-in-stale-stack-frame
    -Wanalyzer-use-of-uninitialized-value
+    -Wanalyzer-va-arg-type-mismatch
+    -Wanalyzer-va-list-exhausted
+    -Wanalyzer-va-list-leak
+    -Wanalyzer-va-list-use-after-va-end
    -Wanalyzer-write-to-const
    -Wanalyzer-write-to-string-literal
    -Warith-conversion
-    -Warray-bounds
    -Warray-bounds=2
    -Warray-compare
    -Warray-parameter=2
@ -209,6 +212,7 @@ set(GCC_CXXFLAGS
    -Wctad-maybe-unsupported
    -Wctor-dtor-privacy
    -Wdangling-else
+    -Wdangling-pointer=2
    -Wdate-time
    -Wdelete-incomplete
    -Wdelete-non-virtual-dtor
@ -279,6 +283,7 @@ set(GCC_CXXFLAGS
    -Wmissing-include-dirs
    -Wmissing-profile
    -Wmissing-requires
+    -Wmissing-template-keyword
    -Wmultichar
    -Wmultiple-inheritance
    -Wmultistatement-macros
@ -340,11 +345,9 @@ set(GCC_CXXFLAGS
    -Wsizeof-pointer-div
    -Wsizeof-pointer-memaccess
    -Wstack-protector
-    -Wstrict-aliasing
    -Wstrict-aliasing=3
    -Wstrict-null-sentinel
-    -Wstrict-overflow
-    -Wstrict-overflow=5
+    -Wno-strict-overflow
    -Wstring-compare
    -Wstringop-overflow=4
    -Wstringop-overread
@ -373,6 +376,7 @@ set(GCC_CXXFLAGS
    -Wterminate
    -Wtrampolines
    -Wtrigraphs
+    -Wtrivial-auto-var-init
    -Wtsan
    -Wtype-limits
    -Wundef
@ -392,6 +396,7 @@ set(GCC_CXXFLAGS
    -Wunused-result
    -Wunused-value
    -Wunused-variable
+    -Wuse-after-free=3
    -Wuseless-cast
    -Wvarargs
    -Wvariadic-macros
@ -411,7 +416,7 @@ set(GCC_CXXFLAGS
 add_custom_target(ci_test_gcc
    COMMAND CXX=${GCC_TOOL} CXXFLAGS="${GCC_CXXFLAGS}" ${CMAKE_COMMAND}
        -DCMAKE_BUILD_TYPE=Debug -GNinja
-        -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
+        -DJSON_BuildTests=ON
        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_gcc
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_gcc
    COMMAND cd ${PROJECT_BINARY_DIR}/build_gcc && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -421,7 +426,7 @@ add_custom_target(ci_test_gcc
 add_custom_target(ci_test_clang
    COMMAND CXX=${CLANG_TOOL} CXXFLAGS="${CLANG_CXXFLAGS}" ${CMAKE_COMMAND}
        -DCMAKE_BUILD_TYPE=Debug -GNinja
-        -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
+        -DJSON_BuildTests=ON
        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_clang
    COMMAND cd ${PROJECT_BINARY_DIR}/build_clang && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -463,7 +468,7 @@ endforeach()
 add_custom_target(ci_test_noexceptions
    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
    -DCMAKE_BUILD_TYPE=Debug -GNinja
-    -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON -DCMAKE_CXX_FLAGS=-DJSON_NOEXCEPTION -DDOCTEST_TEST_FILTER=--no-throw
+    -DJSON_BuildTests=ON -DCMAKE_CXX_FLAGS=-DJSON_NOEXCEPTION -DDOCTEST_TEST_FILTER=--no-throw
    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_noexceptions
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_noexceptions
    COMMAND cd ${PROJECT_BINARY_DIR}/build_noexceptions && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -477,7 +482,7 @@ add_custom_target(ci_test_noexceptions
 add_custom_target(ci_test_noimplicitconversions
    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
    -DCMAKE_BUILD_TYPE=Debug -GNinja
-    -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON -DJSON_ImplicitConversions=OFF
+    -DJSON_BuildTests=ON -DJSON_ImplicitConversions=OFF
    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_noimplicitconversions
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_noimplicitconversions
    COMMAND cd ${PROJECT_BINARY_DIR}/build_noimplicitconversions && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
@ -491,13 +496,27 @@ add_custom_target(ci_test_noimplicitconversions
 add_custom_target(ci_test_diagnostics
    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
    -DCMAKE_BUILD_TYPE=Debug -GNinja
-    -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON -DJSON_Diagnostics=ON
+    -DJSON_BuildTests=ON -DJSON_Diagnostics=ON
    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_diagnostics
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_diagnostics
    COMMAND cd ${PROJECT_BINARY_DIR}/build_diagnostics && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
    COMMENT "Compile and test with improved diagnostics enabled"
 )

+###############################################################################
+# Enable legacy discarded value comparison.
+###############################################################################
+
+add_custom_target(ci_test_legacycomparison
+    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_LegacyDiscardedValueComparison=ON
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_legacycomparison
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_legacycomparison
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_legacycomparison && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test with legacy discarded value comparison enabled"
+)
+
 ###############################################################################
 # Coverage.
 ###############################################################################
@ -505,11 +524,18 @@ add_custom_target(ci_test_diagnostics
 add_custom_target(ci_test_coverage
    COMMAND CXX=g++ ${CMAKE_COMMAND}
        -DCMAKE_BUILD_TYPE=Debug -GNinja -DCMAKE_CXX_FLAGS="--coverage;-fprofile-arcs;-ftest-coverage"
-        -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
+        -DJSON_BuildTests=ON
        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_coverage
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_coverage
    COMMAND cd ${PROJECT_BINARY_DIR}/build_coverage && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure

+    COMMAND CXX=g++ ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug -GNinja -DCMAKE_CXX_FLAGS="-m32;--coverage;-fprofile-arcs;-ftest-coverage"
+        -DJSON_BuildTests=ON -DJSON_32bitTest=ONLY
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_coverage32
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_coverage32
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_coverage32 && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+
    COMMAND ${LCOV_TOOL} --directory . --capture --output-file json.info --rc lcov_branch_coverage=1
    COMMAND ${LCOV_TOOL} -e json.info ${SRC_FILES} --output-file json.info.filtered --rc lcov_branch_coverage=1
    COMMAND ${CMAKE_SOURCE_DIR}/tests/thirdparty/imapdl/filterbr.py json.info.filtered > json.info.filtered.noexcept
@ -562,6 +588,20 @@ add_custom_target(ci_test_amalgamation
    COMMENT "Check amalgamation and indentation"
 )

+###############################################################################
+# Build and test using the amalgamated header
+###############################################################################
+
+add_custom_target(ci_test_single_header
+    COMMAND CXX=${GCC_TOOL} CXXFLAGS="${GCC_CXXFLAGS}" ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug -GNinja
+        -DJSON_BuildTests=ON -DJSON_MultipleHeader=OFF -DJSON_FastTests=ON
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_single_header
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_single_header
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_single_header && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test single-header version"
+)
+
 ###############################################################################
 # Valgrind.
 ###############################################################################
@ -645,7 +685,7 @@ add_custom_target(ci_clang_tidy
    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
        -DCMAKE_BUILD_TYPE=Debug -GNinja
        -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_CLANG_TIDY=${CLANG_TIDY_TOOL}
-        -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
+        -DJSON_BuildTests=ON
        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_clang_tidy
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_clang_tidy
    COMMENT "Check code with Clang-Tidy"
@ -672,7 +712,7 @@ add_custom_target(ci_pvs_studio

 add_custom_target(ci_infer
    COMMAND mkdir -p ${PROJECT_BINARY_DIR}/build_infer
-    COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} compile -- ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Debug ${PROJECT_SOURCE_DIR} -DJSON_BuildTests=ON -DJSON_MultipleHeaders=ON
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} compile -- ${CMAKE_COMMAND} -DCMAKE_BUILD_TYPE=Debug ${PROJECT_SOURCE_DIR} -DJSON_BuildTests=ON
    COMMAND cd ${PROJECT_BINARY_DIR}/build_infer && ${INFER_TOOL} run -- make
    COMMENT "Check code with Infer"
 )
@ -698,6 +738,7 @@ add_custom_target(ci_offline_testdata
 ###############################################################################

 add_custom_target(ci_non_git_tests
+    COMMAND git config --global --add safe.directory ${PROJECT_SOURCE_DIR}
    COMMAND mkdir -p ${PROJECT_BINARY_DIR}/build_non_git_tests/sources
    COMMAND cd ${PROJECT_SOURCE_DIR} && for FILE in `${GIT_TOOL} ls-tree --name-only HEAD`\; do cp -r $$FILE ${PROJECT_BINARY_DIR}/build_non_git_tests/sources \; done
    COMMAND ${CMAKE_COMMAND}
@ -797,8 +838,9 @@ endfunction()
 ci_get_cmake(3.1.0 CMAKE_3_1_0_BINARY)
 ci_get_cmake(3.13.0 CMAKE_3_13_0_BINARY)

-set(JSON_CMAKE_FLAGS_3_1_0 "JSON_Install;JSON_MultipleHeaders;JSON_ImplicitConversions;JSON_Valgrind;JSON_Diagnostics;JSON_SystemInclude")
-set(JSON_CMAKE_FLAGS_3_13_0 "JSON_BuildTests")
+set(JSON_CMAKE_FLAGS_3_1_0 JSON_Diagnostics JSON_ImplicitConversions JSON_DisableEnumSerialization 
+    JSON_LegacyDiscardedValueComparison JSON_Install JSON_MultipleHeaders JSON_SystemInclude JSON_Valgrind)
+set(JSON_CMAKE_FLAGS_3_13_0 JSON_BuildTests)

 function(ci_add_cmake_flags_targets flag min_version)
    string(TOLOWER "ci_cmake_flag_${flag}" flag_target)
@ -841,7 +883,7 @@ add_custom_target(ci_cmake_flags
 # Use more installed compilers.
 ###############################################################################

-foreach(COMPILER g++-4.8 g++-4.9 g++-5 g++-6 g++-7 g++-8 g++-9 g++-10 clang++-3.5 clang++-3.6 clang++-3.7 clang++-3.8 clang++-3.9 clang++-4.0 clang++-5.0 clang++-6.0 clang++-7 clang++-8 clang++-9 clang++-10 clang++-11 clang++-12 clang++-13 clang++-14)
+foreach(COMPILER g++-4.8 g++-4.9 g++-5 g++-6 g++-7 g++-8 g++-9 g++-10 g++-11 clang++-3.5 clang++-3.6 clang++-3.7 clang++-3.8 clang++-3.9 clang++-4.0 clang++-5.0 clang++-6.0 clang++-7 clang++-8 clang++-9 clang++-10 clang++-11 clang++-12 clang++-13 clang++-14)
    find_program(COMPILER_TOOL NAMES ${COMPILER})
    if (COMPILER_TOOL)
        if ("${COMPILER}" STREQUAL "clang++-9")
@ -877,6 +919,21 @@ add_custom_target(ci_cuda_example
    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_cuda_example
 )

+###############################################################################
+# Intel C++ Compiler
+###############################################################################
+
+add_custom_target(ci_icpc
+    COMMAND ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug -GNinja
+        -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc
+        -DJSON_BuildTests=ON -DJSON_FastTests=ON
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_icpc
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_icpc
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_icpc && ${CMAKE_CTEST_COMMAND} --parallel ${N} --exclude-regex "test-unicode" --output-on-failure
+    COMMENT "Compile and test with ICPC"
+)
+
 ###############################################################################
 # Clean up all generated files.
 ###############################################################################
--- a/cmake/test.cmake
+++ b/cmake/test.cmake
@ -156,6 +156,7 @@ endfunction()
 #############################################################################
 # json_test_add_test_for(
 #     <file>
+#     [NAME <name>]
 #     MAIN <main>
 #     [CXX_STANDARDS <version_number>...] [FORCE])
 #
@ -165,6 +166,7 @@ endfunction()
 #
 # if C++ standard <version_number> is supported by the compiler and the
 # source file contains JSON_HAS_CPP_<version_number>.
+# Use NAME <name> to override the filename-derived test name.
 # Use FORCE to create the test regardless of the file containing
 # JSON_HAS_CPP_<version_number>.
 # Test targets are linked against <main>.
@ -172,15 +174,22 @@ endfunction()
 #############################################################################

 function(json_test_add_test_for file)
-    cmake_parse_arguments(args "FORCE" "MAIN" "CXX_STANDARDS" ${ARGN})
-
-    get_filename_component(file_basename ${file} NAME_WE)
-    string(REGEX REPLACE "unit-([^$]+)" "test-\\1" test_name ${file_basename})
+    cmake_parse_arguments(args "FORCE" "MAIN;NAME" "CXX_STANDARDS" ${ARGN})

    if("${args_MAIN}" STREQUAL "")
        message(FATAL_ERROR "Required argument MAIN <main> missing.")
    endif()

+    if("${args_NAME}" STREQUAL "")
+        get_filename_component(file_basename ${file} NAME_WE)
+        string(REGEX REPLACE "unit-([^$]+)" "test-\\1" test_name ${file_basename})
+    else()
+        set(test_name ${args_NAME})
+        if(NOT test_name MATCHES "test-[^$]+")
+            message(FATAL_ERROR "Test name must start with 'test-'.")
+        endif()
+    endif()
+
    if("${args_CXX_STANDARDS}" STREQUAL "")
        set(args_CXX_STANDARDS 11)
    endif()
@ -202,3 +211,32 @@ function(json_test_add_test_for file)
        _json_test_add_test(${test_name} ${file} ${args_MAIN} ${cxx_standard})
    endforeach()
 endfunction()
+
+#############################################################################
+# json_test_should_build_32bit_test(
+#     <build_32bit_var> <build_32bit_only_var> <input>)
+#
+# Check if the 32bit unit test should be built based on the value of <input>
+# and store the result in the variables <build_32bit_var> and
+# <build_32bit_only_var>.
+#############################################################################
+
+function(json_test_should_build_32bit_test build_32bit_var build_32bit_only_var input)
+    set(${build_32bit_only_var} OFF PARENT_SCOPE)
+    string(TOUPPER "${input}" ${build_32bit_var})
+    if("${${build_32bit_var}}" STREQUAL AUTO)
+        # check if compiler is targeting 32bit by default
+        include(CheckTypeSize)
+        check_type_size("size_t" sizeof_size_t LANGUAGE CXX)
+        if(sizeof_size_t AND ${sizeof_size_t} EQUAL 4)
+            message(STATUS "Auto-enabling 32bit unit test.")
+            set(${build_32bit_var} ON)
+        else()
+            set(${build_32bit_var} OFF)
+        endif()
+    elseif("${${build_32bit_var}}" STREQUAL ONLY)
+        set(${build_32bit_only_var} ON PARENT_SCOPE)
+    endif()
+
+    set(${build_32bit_var} "${${build_32bit_var}}" PARENT_SCOPE)
+endfunction()
--- a/docs/docset/docSet.sql
+++ b/docs/docset/docSet.sql
@ -140,6 +140,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('SAX Interface', 'Guide', 'fea
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_ASSERT', 'Macro', 'features/macros/index.html#json_assertx');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_CATCH_USER', 'Macro', 'features/macros/index.html#json_catch_userexception');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DIAGNOSTICS', 'Macro', 'features/macros/index.html#json_diagnostics');
+INSERT INTO searchIndex(name, type, path) VALUES ('JSON_DISABLE_ENUM_SERIALIZATION', 'Macro', 'features/macros/index.html#json_disable_enum_serialization');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_11', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_14', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_HAS_CPP_17', 'Macro', 'features/macros/index.html#json_has_cpp_11-json_has_cpp_14-json_has_cpp_17-json_has_cpp_20');
--- a/docs/examples/byte_container_with_subtype__byte_container_with_subtype.cpp
+++ b/docs/examples/byte_container_with_subtype__byte_container_with_subtype.cpp
@ -0,0 +1,23 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+using json = nlohmann::json;
+
+int main()
+{
+    // (1) create empty container
+    auto c1 = byte_container_with_subtype();
+
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // (2) create container
+    auto c2 = byte_container_with_subtype(bytes);
+
+    // (3) create container with subtype
+    auto c3 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << json(c1) << "\n" << json(c2) << "\n" << json(c3) << std::endl;
+}
--- a/docs/examples/byte_container_with_subtype__byte_container_with_subtype.output
+++ b/docs/examples/byte_container_with_subtype__byte_container_with_subtype.output
@ -0,0 +1,3 @@
+{"bytes":[],"subtype":null}
+{"bytes":[202,254,186,190],"subtype":null}
+{"bytes":[202,254,186,190],"subtype":42}
--- a/docs/examples/byte_container_with_subtype__clear_subtype.cpp
+++ b/docs/examples/byte_container_with_subtype__clear_subtype.cpp
@ -0,0 +1,21 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container with subtype
+    auto c1 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << "before calling clear_subtype(): " << json(c1) << '\n';
+
+    c1.clear_subtype();
+
+    std::cout << "after calling clear_subtype(): " << json(c1) << '\n';
+}
--- a/docs/examples/byte_container_with_subtype__clear_subtype.output
+++ b/docs/examples/byte_container_with_subtype__clear_subtype.output
@ -0,0 +1,2 @@
+before calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":42}
+after calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":null}
--- a/docs/examples/byte_container_with_subtype__has_subtype.cpp
+++ b/docs/examples/byte_container_with_subtype__has_subtype.cpp
@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container
+    auto c1 = byte_container_with_subtype(bytes);
+
+    // create container with subtype
+    auto c2 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << std::boolalpha << "c1.has_subtype() = " << c1.has_subtype()
+              << "\nc2.has_subtype() = " << c2.has_subtype() << std::endl;
+}
--- a/docs/examples/byte_container_with_subtype__has_subtype.output
+++ b/docs/examples/byte_container_with_subtype__has_subtype.output
@ -0,0 +1,2 @@
+c1.has_subtype() = false
+c2.has_subtype() = true
--- a/docs/examples/byte_container_with_subtype__set_subtype.cpp
+++ b/docs/examples/byte_container_with_subtype__set_subtype.cpp
@ -0,0 +1,22 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container without subtype
+    auto c = byte_container_with_subtype(bytes);
+
+    std::cout << "before calling set_subtype(42): " << json(c) << '\n';
+
+    // set the subtype
+    c.set_subtype(42);
+
+    std::cout << "after calling set_subtype(42): " << json(c) << '\n';
+}
--- a/docs/examples/byte_container_with_subtype__set_subtype.output
+++ b/docs/examples/byte_container_with_subtype__set_subtype.output
@ -0,0 +1,2 @@
+before calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":null}
+after calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":42}
--- a/docs/examples/byte_container_with_subtype__subtype.cpp
+++ b/docs/examples/byte_container_with_subtype__subtype.cpp
@ -0,0 +1,22 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container
+    auto c1 = byte_container_with_subtype(bytes);
+
+    // create container with subtype
+    auto c2 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << "c1.subtype() = " << c1.subtype()
+              << "\nc2.subtype() = " << c2.subtype() << std::endl;
+
+    // in case no subtype is set, return special value
+    assert(c1.subtype() == static_cast<byte_container_with_subtype::subtype_type>(-1));
+}
--- a/docs/examples/byte_container_with_subtype__subtype.output
+++ b/docs/examples/byte_container_with_subtype__subtype.output
@ -0,0 +1,2 @@
+c1.subtype() = 18446744073709551615
+c2.subtype() = 42
--- a/docs/examples/cbor_tag_handler_t.cpp
+++ b/docs/examples/cbor_tag_handler_t.cpp
@ -0,0 +1,28 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // tagged byte string
+    std::vector<std::uint8_t> vec = {{0xd8, 0x42, 0x44, 0xcA, 0xfe, 0xba, 0xbe}};
+
+    // cbor_tag_handler_t::error throws
+    try
+    {
+        auto b_throw_on_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::error);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    // cbor_tag_handler_t::ignore ignores the tag
+    auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
+    std::cout << b_ignore_tag << std::endl;
+
+    // cbor_tag_handler_t::store stores the tag as binary subtype
+    auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
+    std::cout << b_store_tag << std::endl;
+}
--- a/docs/examples/cbor_tag_handler_t.output
+++ b/docs/examples/cbor_tag_handler_t.output
@ -0,0 +1,3 @@
+[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8
+{"bytes":[202,254,186,190],"subtype":null}
+{"bytes":[202,254,186,190],"subtype":66}
--- a/docs/examples/default_object_comparator_t.cpp
+++ b/docs/examples/default_object_comparator_t.cpp
@ -0,0 +1,11 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << "one < two : " << json::default_object_comparator_t{}("one", "two") << "\n"
+              << "three < four : " << json::default_object_comparator_t{}("three", "four") << std::endl;
+}
--- a/docs/examples/default_object_comparator_t.output
+++ b/docs/examples/default_object_comparator_t.output
@ -0,0 +1,2 @@
+one < two : true
+three < four : false
--- a/docs/examples/error_handler_t.cpp
+++ b/docs/examples/error_handler_t.cpp
@ -0,0 +1,24 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON value with invalid UTF-8 byte sequence
+    json j_invalid = "ä\xA9ü";
+    try
+    {
+        std::cout << j_invalid.dump() << std::endl;
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    std::cout << "string with replaced invalid characters: "
+              << j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
+              << "\nstring with ignored invalid characters: "
+              << j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
+              << '\n';
+}
--- a/docs/examples/error_handler_t.output
+++ b/docs/examples/error_handler_t.output
@ -0,0 +1,3 @@
+[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
+string with replaced invalid characters: "ä<>ü"
+string with ignored invalid characters: "äü"
--- a/docs/examples/from_bjdata.cpp
+++ b/docs/examples/from_bjdata.cpp
@ -0,0 +1,20 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create byte vector
+    std::vector<std::uint8_t> v = {0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61,
+                                   0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68,
+                                   0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D
+                                  };
+
+    // deserialize it with BJData
+    json j = json::from_bjdata(v);
+
+    // print the deserialized JSON value
+    std::cout << std::setw(2) << j << std::endl;
+}
--- a/docs/examples/from_bjdata.output
+++ b/docs/examples/from_bjdata.output
@ -0,0 +1,4 @@
+{
+  "compact": true,
+  "schema": 0
+}
--- a/docs/examples/get_allocator.cpp
+++ b/docs/examples/get_allocator.cpp
@ -0,0 +1,18 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    auto alloc = json::get_allocator();
+    using traits_t = std::allocator_traits<decltype(alloc)>;
+
+    json* j = traits_t::allocate(alloc, 1);
+    traits_t::construct(alloc, j, "Hello, world!");
+
+    std::cout << *j << std::endl;
+
+    traits_t::destroy(alloc, j);
+    traits_t::deallocate(alloc, j, 1);
+}
--- a/docs/examples/get_allocator.output
+++ b/docs/examples/get_allocator.output
@ -0,0 +1 @@
+"Hello, world!"
--- a/docs/examples/iterator_wrapper.cpp
+++ b/docs/examples/iterator_wrapper.cpp
@ -1,29 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create JSON values
-    json j_object = {{"one", 1}, {"two", 2}};
-    json j_array = {1, 2, 4, 8, 16};
-
-    //////////////////////////////////////////////////////////////////////////
-    // The static function iterator_wrapper was deprecated in version 3.1.0
-    // and will be removed in version 4.0.0. Please replace all occurrences
-    // of iterator_wrapper(j) with j.items().
-    //////////////////////////////////////////////////////////////////////////
-
-    // example for an object
-    for (auto& x : json::iterator_wrapper(j_object))
-    {
-        std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
-    }
-
-    // example for an array
-    for (auto& x : json::iterator_wrapper(j_array))
-    {
-        std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
-    }
-}
--- a/docs/examples/iterator_wrapper.output
+++ b/docs/examples/iterator_wrapper.output
@ -1,7 +0,0 @@
-key: one, value: 1
-key: two, value: 2
-key: 0, value: 1
-key: 1, value: 2
-key: 2, value: 4
-key: 3, value: 8
-key: 4, value: 16
--- a/docs/examples/json_pointer__operator_string.cpp
+++ b/docs/examples/json_pointer__operator_string.cpp
@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // different JSON Pointers
+    json::json_pointer ptr1("/foo/0");
+    json::json_pointer ptr2("/a~1b");
+
+    // implicit conversion to string
+    std::string s;
+    s += ptr1;
+    s += "\n";
+    s += ptr2;
+
+    std::cout << s << std::endl;
+}
--- a/docs/examples/json_pointer__operator_string.output
+++ b/docs/examples/json_pointer__operator_string.output
@ -0,0 +1,2 @@
+/foo/0
+/a~1b
--- a/docs/examples/json_pointer__string_t.cpp
+++ b/docs/examples/json_pointer__string_t.cpp
@ -0,0 +1,13 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json::json_pointer::string_t s = "This is a string.";
+
+    std::cout << s << std::endl;
+
+    std::cout << std::boolalpha << std::is_same<json::json_pointer::string_t, json::string_t>::value << std::endl;
+}
--- a/docs/examples/json_pointer__string_t.output
+++ b/docs/examples/json_pointer__string_t.output
@ -0,0 +1,2 @@
+This is a string.
+true
--- a/docs/examples/json_pointer__to_string.cpp
+++ b/docs/examples/json_pointer__to_string.cpp
@ -19,7 +19,6 @@ int main()
    json::json_pointer ptr11("/ ");
    json::json_pointer ptr12("/m~0n");

-
    std::cout << ptr1.to_string() << '\n'
              << ptr2.to_string() << '\n'
              << ptr3.to_string() << '\n'
--- a/docs/examples/nlohmann_json_version.cpp
+++ b/docs/examples/nlohmann_json_version.cpp
@ -0,0 +1,12 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << "JSON for Modern C++ version "
+              << NLOHMANN_JSON_VERSION_MAJOR << "."
+              << NLOHMANN_JSON_VERSION_MINOR << "."
+              << NLOHMANN_JSON_VERSION_PATCH << std::endl;
+}
--- a/docs/examples/nlohmann_json_version.output
+++ b/docs/examples/nlohmann_json_version.output
@ -0,0 +1 @@
+JSON for Modern C++ version 3.10.5
--- a/docs/examples/object_comparator_t.cpp
+++ b/docs/examples/object_comparator_t.cpp
@ -0,0 +1,11 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << "json::object_comparator_t(\"one\", \"two\") = " << json::object_comparator_t{}("one", "two") << "\n"
+              << "json::object_comparator_t(\"three\", \"four\") = " << json::object_comparator_t{}("three", "four") << std::endl;
+}
--- a/docs/examples/object_comparator_t.output
+++ b/docs/examples/object_comparator_t.output
@ -0,0 +1,2 @@
+json::object_comparator_t("one", "two") = true
+json::object_comparator_t("three", "four") = false
--- a/docs/examples/ordered_json.cpp
+++ b/docs/examples/ordered_json.cpp
@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using ordered_json = nlohmann::ordered_json;
+
+int main()
+{
+    ordered_json j;
+    j["one"] = 1;
+    j["two"] = 2;
+    j["three"] = 3;
+
+    std::cout << j.dump(2) << '\n';
+}
--- a/docs/examples/ordered_json.output
+++ b/docs/examples/ordered_json.output
@ -0,0 +1,5 @@
+{
+  "one": 1,
+  "two": 2,
+  "three": 3
+}
--- a/docs/examples/sax_parse.cpp
+++ b/docs/examples/sax_parse.cpp
@ -6,7 +6,7 @@
 using json = nlohmann::json;

 // a simple event consumer that collects string representations of the passed
-// values; not inheriting from json::json_sax_t is not required, but can
+// values; note inheriting from json::json_sax_t is not required, but can
 // help not to forget a required function
 class sax_event_consumer : public json::json_sax_t
 {
@ -15,79 +15,79 @@ class sax_event_consumer : public json::json_sax_t

    bool null() override
    {
-        events.push_back("value: null");
+        events.push_back("null()");
        return true;
    }

    bool boolean(bool val) override
    {
-        events.push_back("value: " + std::string(val ? "true" : "false"));
+        events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
        return true;
    }

    bool number_integer(number_integer_t val) override
    {
-        events.push_back("value: " + std::to_string(val));
+        events.push_back("number_integer(val=" + std::to_string(val) + ")");
        return true;
    }

    bool number_unsigned(number_unsigned_t val) override
    {
-        events.push_back("value: " + std::to_string(val));
+        events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
        return true;
    }

    bool number_float(number_float_t val, const string_t& s) override
    {
-        events.push_back("value: " + s);
+        events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
        return true;
    }

    bool string(string_t& val) override
    {
-        events.push_back("value: " + val);
+        events.push_back("string(val=" + val + ")");
        return true;
    }

    bool start_object(std::size_t elements) override
    {
-        events.push_back("start: object");
+        events.push_back("start_object(elements=" + std::to_string(elements) + ")");
        return true;
    }

    bool end_object() override
    {
-        events.push_back("end: object");
+        events.push_back("end_object()");
        return true;
    }

    bool start_array(std::size_t elements) override
    {
-        events.push_back("start: array");
+        events.push_back("start_array(elements=" + std::to_string(elements) + ")");
        return true;
    }

    bool end_array() override
    {
-        events.push_back("end: array");
+        events.push_back("end_array()");
        return true;
    }

    bool key(string_t& val) override
    {
-        events.push_back("key: " + val);
+        events.push_back("key(val=" + val + ")");
        return true;
    }

    bool binary(json::binary_t& val) override
    {
-        events.push_back("binary");
+        events.push_back("binary(val=[...])");
        return true;
    }

    bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
    {
-        events.push_back("error: " + std::string(ex.what()));
+        events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n            ex=" + std::string(ex.what()) + ")");
        return false;
    }
 };
@ -107,22 +107,23 @@ int main()
                "Width":  100
            },
            "Animated" : false,
-            "IDs": [116, 943, 234, 38793],
+            "IDs": [116, 943, 234, -38793],
+            "DeletionDate": null,
            "Distance": 12.723374634
        }
-    }
+    }]
    )";

    // create a SAX event consumer object
    sax_event_consumer sec;

-    // parse and serialize JSON
+    // parse JSON
    bool result = json::sax_parse(text, &sec);

    // output the recorded events
    for (auto& event : sec.events)
    {
-        std::cout << "(" << event << ") ";
+        std::cout << event << "\n";
    }

    // output the result of sax_parse
--- a/docs/examples/sax_parse.output
+++ b/docs/examples/sax_parse.output
@ -1,2 +1,37 @@
-(start: object) (key: Image) (start: object) (key: Width) (value: 800) (key: Height) (value: 600) (key: Title) (value: View from 15th Floor) (key: Thumbnail) (start: object) (key: Url) (value: http://www.example.com/image/481989943) (key: Height) (value: 125) (key: Width) (value: 100) (end: object) (key: Animated) (value: false) (key: IDs) (start: array) (value: 116) (value: 943) (value: 234) (value: 38793) (end: array) (key: Distance) (value: 12.723374634) (end: object) (end: object) 
-result: true
+start_object(elements=18446744073709551615)
+key(val=Image)
+start_object(elements=18446744073709551615)
+key(val=Width)
+number_unsigned(val=800)
+key(val=Height)
+number_unsigned(val=600)
+key(val=Title)
+string(val=View from 15th Floor)
+key(val=Thumbnail)
+start_object(elements=18446744073709551615)
+key(val=Url)
+string(val=http://www.example.com/image/481989943)
+key(val=Height)
+number_unsigned(val=125)
+key(val=Width)
+number_unsigned(val=100)
+end_object()
+key(val=Animated)
+boolean(val=false)
+key(val=IDs)
+start_array(elements=18446744073709551615)
+number_unsigned(val=116)
+number_unsigned(val=943)
+number_unsigned(val=234)
+number_integer(val=-38793)
+end_array()
+key(val=DeletionDate)
+null()
+key(val=Distance)
+number_float(val=12.723375, s=12.723374634)
+end_object()
+end_object()
+parse_error(position=460, last_token=12.723374634<U+000A>        }<U+000A>    }],
+            ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
+
+result: false
--- a/docs/examples/sax_parse__binary.cpp
+++ b/docs/examples/sax_parse__binary.cpp
@ -0,0 +1,114 @@
+#include <iostream>
+#include <iomanip>
+#include <sstream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+// a simple event consumer that collects string representations of the passed
+// values; note inheriting from json::json_sax_t is not required, but can
+// help not to forget a required function
+class sax_event_consumer : public json::json_sax_t
+{
+  public:
+    std::vector<std::string> events;
+
+    bool null() override
+    {
+        events.push_back("null()");
+        return true;
+    }
+
+    bool boolean(bool val) override
+    {
+        events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
+        return true;
+    }
+
+    bool number_integer(number_integer_t val) override
+    {
+        events.push_back("number_integer(val=" + std::to_string(val) + ")");
+        return true;
+    }
+
+    bool number_unsigned(number_unsigned_t val) override
+    {
+        events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
+        return true;
+    }
+
+    bool number_float(number_float_t val, const string_t& s) override
+    {
+        events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
+        return true;
+    }
+
+    bool string(string_t& val) override
+    {
+        events.push_back("string(val=" + val + ")");
+        return true;
+    }
+
+    bool start_object(std::size_t elements) override
+    {
+        events.push_back("start_object(elements=" + std::to_string(elements) + ")");
+        return true;
+    }
+
+    bool end_object() override
+    {
+        events.push_back("end_object()");
+        return true;
+    }
+
+    bool start_array(std::size_t elements) override
+    {
+        events.push_back("start_array(elements=" + std::to_string(elements) + ")");
+        return true;
+    }
+
+    bool end_array() override
+    {
+        events.push_back("end_array()");
+        return true;
+    }
+
+    bool key(string_t& val) override
+    {
+        events.push_back("key(val=" + val + ")");
+        return true;
+    }
+
+    bool binary(json::binary_t& val) override
+    {
+        events.push_back("binary(val=[...])");
+        return true;
+    }
+
+    bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
+    {
+        events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n            ex=" + std::string(ex.what()) + ")");
+        return false;
+    }
+};
+
+int main()
+{
+    // CBOR byte string
+    std::vector<std::uint8_t> vec = {{0x44, 0xcA, 0xfe, 0xba, 0xbe}};
+
+    // create a SAX event consumer object
+    sax_event_consumer sec;
+
+    // parse CBOR
+    bool result = json::sax_parse(vec, &sec, json::input_format_t::cbor);
+
+    // output the recorded events
+    for (auto& event : sec.events)
+    {
+        std::cout << event << "\n";
+    }
+
+    // output the result of sax_parse
+    std::cout << "\nresult: " << std::boolalpha << result << std::endl;
+}
--- a/docs/examples/sax_parse__binary.output
+++ b/docs/examples/sax_parse__binary.output
@ -0,0 +1,3 @@
+binary(val=[...])
+
+result: true
--- a/docs/examples/to_bjdata.cpp
+++ b/docs/examples/to_bjdata.cpp
@ -0,0 +1,63 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+// function to print BJData's diagnostic format
+void print_byte(uint8_t byte)
+{
+    if (32 < byte and byte < 128)
+    {
+        std::cout << (char)byte;
+    }
+    else
+    {
+        std::cout << (int)byte;
+    }
+}
+
+int main()
+{
+    // create a JSON value
+    json j = R"({"compact": true, "schema": false})"_json;
+
+    // serialize it to BJData
+    std::vector<std::uint8_t> v = json::to_bjdata(j);
+
+    // print the vector content
+    for (auto& byte : v)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+
+    // create an array of numbers
+    json array = {1, 2, 3, 4, 5, 6, 7, 8};
+
+    // serialize it to BJData using default representation
+    std::vector<std::uint8_t> v_array = json::to_bjdata(array);
+    // serialize it to BJData using size optimization
+    std::vector<std::uint8_t> v_array_size = json::to_bjdata(array, true);
+    // serialize it to BJData using type optimization
+    std::vector<std::uint8_t> v_array_size_and_type = json::to_bjdata(array, true, true);
+
+    // print the vector contents
+    for (auto& byte : v_array)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+
+    for (auto& byte : v_array_size)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+
+    for (auto& byte : v_array_size_and_type)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+}
--- a/docs/examples/to_bjdata.output
+++ b/docs/examples/to_bjdata.output
@ -0,0 +1,4 @@
+{i7compactTi6schemaF}
+[i1i2i3i4i5i6i7i8]
+[#i8i1i2i3i4i5i6i7i8
+[$i#i812345678
--- a/docs/mkdocs/docs/api/basic_json/at.md
+++ b/docs/mkdocs/docs/api/basic_json/at.md
@ -184,6 +184,7 @@ Strong exception safety: if an exception occurs, the original value stays intact

 ## See also

+- documentation on [checked access](../../features/element_access/checked_access.md)
 - see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
 - see [`value`](value.md) for access with default value

--- a/docs/mkdocs/docs/api/basic_json/basic_json.md
+++ b/docs/mkdocs/docs/api/basic_json/basic_json.md
@ -241,7 +241,7 @@ basic_json(basic_json&& other) noexcept;

 - Overload 5:

-    !!! note
+    !!! note "Empty initializer list"

        When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
        function, yielding the JSON `#!json null` value.
--- a/docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
+++ b/docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
@ -20,6 +20,23 @@ ignore
 store
 :   store tagged values as binary container with subtype (for bytes 0xd8..0xdb)

+## Examples
+
+??? example
+
+    The example below shows how the different values of the `cbor_tag_handler_t` influence the behavior of
+    [`from_cbor`](from_cbor.md) when reading a tagged byte string.
+
+    ```cpp
+    --8<-- "examples/cbor_tag_handler_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/cbor_tag_handler_t.output"
+    ```
+
 ## Version history

 - Added in version 3.9.0. Added value `store` in 3.10.0.
--- a/docs/mkdocs/docs/api/basic_json/contains.md
+++ b/docs/mkdocs/docs/api/basic_json/contains.md
@ -60,8 +60,8 @@ Logarithmic in the size of the JSON object.

 ## Notes

-1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
-2. This method can be executed on any JSON value type.
+- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+- This method can be executed on any JSON value type.

 !!! info "Postconditions"

--- a/docs/mkdocs/docs/api/basic_json/default_object_comparator_t.md
+++ b/docs/mkdocs/docs/api/basic_json/default_object_comparator_t.md
@ -14,6 +14,22 @@ when looking up a key in an object.
 The actual comparator used depends on [`object_t`](object_t.md) and can be obtained via
 [`object_comparator_t`](object_comparator_t.md).

+## Examples
+
+??? example
+
+    The example below demonstrates the default comparator.
+
+    ```cpp
+    --8<-- "examples/default_object_comparator_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/default_object_comparator_t.output"
+    ```
+
 ## Version history

 - Added in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/error_handler_t.md
+++ b/docs/mkdocs/docs/api/basic_json/error_handler_t.md
@ -20,6 +20,23 @@ replace
 ignore
 :   ignore invalid UTF-8 sequences; all bytes are copied to the output unchanged

+## Examples
+
+??? example
+
+    The example below shows how the different values of the `error_handler_t` influence the behavior of
+    [`dump`](dump.md) when reading serializing an invalid UTF-8 sequence.
+
+    ```cpp
+    --8<-- "examples/error_handler_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/error_handler_t.output"
+    ```
+
 ## Version history

 - Added in version 3.4.0.
--- a/docs/mkdocs/docs/api/basic_json/from_bjdata.md
+++ b/docs/mkdocs/docs/api/basic_json/from_bjdata.md
@ -0,0 +1,93 @@
+# <small>nlohmann::basic_json::</small>from_bjdata
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_bjdata(InputType&& i,
+                              const bool strict = true,
+                              const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType>
+static basic_json from_bjdata(IteratorType first, IteratorType last,
+                              const bool strict = true,
+                              const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the BJData (Binary JData) serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range.
+
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
+
+## Template parameters
+
+`InputType`
+:   A compatible input, for instance:
+
+    - an `std::istream` object
+    - a `FILE` pointer
+    - a C-style array of characters
+    - a pointer to a null-terminated string of single byte characters
+    - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
+
+`IteratorType`
+:   a compatible iterator type
+
+## Parameters
+
+`i` (in)
+:   an input in BJData format convertible to an input adapter
+
+`first` (in)
+:   iterator to start of the input
+
+`last` (in)
+:   iterator to end of the input
+
+`strict` (in)
+:   whether to expect the input to be consumed until EOF (`#!cpp true` by default)
+
+`allow_exceptions` (in)
+:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+## Return value
+
+deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
+`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
+  successfully
+
+## Complexity
+
+Linear in the size of the input.
+
+## Examples
+
+??? example
+
+    The example shows the deserialization of a byte vector in BJData format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_bjdata.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_bjdata.output"
+    ```
+
+## Version history
+
+- Added in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/get_allocator.md
+++ b/docs/mkdocs/docs/api/basic_json/get_allocator.md
@ -10,10 +10,22 @@ Returns the allocator associated with the container.

 associated allocator

+## Examples
+
+??? example
+
+    The example shows how `get_allocator()` is used to created `json` values.
+    
+    ```cpp
+    --8<-- "examples/get_allocator.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_allocator.output"
+    ```
+
 ## Version history

- Unknown.
-
-!!! note
-
-    This documentation page is a stub.
+- Added in version 1.0.0.
--- a/docs/mkdocs/docs/api/basic_json/index.md
+++ b/docs/mkdocs/docs/api/basic_json/index.md
@ -233,9 +233,10 @@ Access to the JSON value
 - [**operator==**](operator_eq.md) - comparison: equal
 - [**operator!=**](operator_ne.md) - comparison: not equal
 - [**operator<**](operator_lt.md) - comparison: less than
- [**operator<=**](operator_le.md) - comparison: less than or equal
 - [**operator>**](operator_gt.md) - comparison: greater than
+- [**operator<=**](operator_le.md) - comparison: less than or equal
 - [**operator>=**](operator_ge.md) - comparison: greater than or equal
+- [**operator<=>**](operator_spaceship.md) - comparison: 3-way

 ### Serialization / Dumping

@ -268,11 +269,13 @@ Access to the JSON value

 ### Binary formats

+- [**from_bjdata**](from_bjdata.md) (_static_) - create a JSON value from an input in BJData format
 - [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
 - [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
 - [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
 - [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
 - [**to_bon8**](to_bon8.md) (static) - create a BON8 serialization of a given JSON value
+- [**to_bjdata**](to_bjdata.md) (_static_) - create a BJData serialization of a given JSON value
 - [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
 - [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
 - [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value
--- a/docs/mkdocs/docs/api/basic_json/input_format_t.md
+++ b/docs/mkdocs/docs/api/basic_json/input_format_t.md
@ -6,7 +6,8 @@ enum class input_format_t {
    cbor,
    msgpack,
    ubjson,
-    bson
+    bson,
+    bjdata
 };
 ```

@ -27,6 +28,25 @@ ubjson
 bson
 :   BSON (Binary JSON)

+bjdata
+:   BJData (Binary JData)
+
+## Examples
+
+??? example
+
+    The example below shows how an `input_format_t` enum value is passed to `sax_parse` to set the input format to CBOR.
+
+    ```cpp
+    --8<-- "examples/sax_parse__binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse__binary.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/basic_json/object_comparator_t.md
+++ b/docs/mkdocs/docs/api/basic_json/object_comparator_t.md
@ -1,6 +1,5 @@
 # <small>nlohmann::basic_json::</small>object_comparator_t

-
 ```cpp
 using object_comparator_t = typename object_t::key_compare;
 // or
@ -10,6 +9,22 @@ using object_comparator_t = default_object_comparator_t;
 The comparator used by [`object_t`](object_t.md). Defined as `#!cpp typename object_t::key_compare` if available,
 and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.

+## Examples
+
+??? example
+
+    The example below demonstrates the used object comparator.
+
+    ```cpp
+    --8<-- "examples/object_comparator_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/object_comparator_t.output"
+    ```
+
 ## Version history

 - Added in version 3.0.0.
--- a/docs/mkdocs/docs/api/basic_json/operator+=.md
+++ b/docs/mkdocs/docs/api/basic_json/operator+=.md
@ -41,12 +41,9 @@ reference operator+=(initializer_list_t init);

 ## Exceptions

-1. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON array or null; example: `"cannot use operator+=() with number"`
-2. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON object or null; example: `"cannot use operator+=() with number"`
+All functions can throw the following exception:
+  - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
+    JSON array or null; example: `"cannot use operator+=() with number"`

 ## Complexity

--- a/docs/mkdocs/docs/api/basic_json/operator[].md
+++ b/docs/mkdocs/docs/api/basic_json/operator[].md
@ -198,6 +198,8 @@ Strong exception safety: if an exception occurs, the original value stays intact

 ## See also

+- documentation on [unchecked access](../../features/element_access/unchecked_access.md)
+- documentation on [runtime assertions](../../features/assertions.md)
 - see [`at`](at.md) for access by reference with range checking
 - see [`value`](value.md) for access with default value

--- a/docs/mkdocs/docs/api/basic_json/operator_ValueType.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_ValueType.md
@ -56,7 +56,6 @@ Linear in the size of the JSON value.
    [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0` and replace any implicit
    conversions with calls to [`get`](../basic_json/get.md).

-
 ## Examples

 ??? example
--- a/docs/mkdocs/docs/api/basic_json/operator_eq.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_eq.md
@ -1,21 +1,31 @@
 # <small>nlohmann::basic_json::</small>operator==

 ```cpp
-bool operator==(const_reference lhs, const_reference rhs) noexcept;
+// until C++20
+bool operator==(const_reference lhs, const_reference rhs) noexcept;   // (1)

 template<typename ScalarType>
-bool operator==(const_reference lhs, const ScalarType rhs) noexcept;
+bool operator==(const_reference lhs, const ScalarType rhs) noexcept;  // (2)

 template<typename ScalarType>
-bool operator==(ScalarType lhs, const const_reference rhs) noexcept;
+bool operator==(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
+
+// since C++20
+class basic_json {
+    bool operator==(const_reference rhs) const noexcept;              // (1)
+
+    template<typename ScalarType>
+    bool operator==(ScalarType rhs) const noexcept;                   // (2)
+};
 ```

-Compares two JSON values for equality according to the following rules:
+1. Compares two JSON values for equality according to the following rules:
+    - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same
+      type and their stored values are the same according to their respective `operator==`.
+    - Integer and floating-point numbers are automatically converted before comparison.

- Two JSON values are equal if (1) they are not discarded, (2) they are from the same type, and (3) their stored values
-  are the same according to their respective `operator==`.
- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
-  treated as unequal.
+2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the
+   scalar to a JSON value and comparing both JSON values according to 1.

 ## Template parameters

@ -32,7 +42,7 @@ Compares two JSON values for equality according to the following rules:

 ## Return value

-whether the values `lhs` and `rhs` are equal
+whether the values `lhs`/`*this` and `rhs` are equal

 ## Exception safety

@ -44,13 +54,17 @@ Linear.

 ## Notes

-!!! note
+!!! note "Comparing special values"

-    - NaN values never compare equal to themselves or to other NaN values.
+    - `NaN` values are unordered within the domain of numbers.
+      The following comparisons all yield `#!cpp false`:
+        1. Comparing a `NaN` with itself.
+        2. Comparing a `NaN` with another `NaN`.
+        3. Comparing a `NaN` and any other number.
    - JSON `#!cpp null` values are all equal.
    - Discarded values never compare equal to themselves.

-!!! note
+!!! note "Comparing floating-point numbers"

    Floating-point numbers inside JSON values numbers are compared with `json::number_float_t::operator==` which is
    `double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative
@ -117,4 +131,5 @@ Linear.

 ## Version history

- Added in version 1.0.0.
+1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
+2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/operator_ge.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_ge.md
@ -1,17 +1,25 @@
 # <small>nlohmann::basic_json::</small>operator>=

 ```cpp
-bool operator>=(const_reference lhs, const_reference rhs) noexcept,
+// until C++20
+bool operator>=(const_reference lhs, const_reference rhs) noexcept;   // (1)

 template<typename ScalarType>
-bool operator>=(const_reference lhs, const ScalarType rhs) noexcept;
+bool operator>=(const_reference lhs, const ScalarType rhs) noexcept;  // (2)

 template<typename ScalarType>
-bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;
+bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 ```

-Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` by calculating
-`#!cpp !(lhs < rhs)`.
+1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs`
+   according to the following rules:
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
+      operand is `NaN` and the other operand is either `NaN` or any other number.
+    - Otherwise, returns the result of `#!cpp !(lhs < rhs)`.
+
+2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or
+   equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values
+   according to 1.

 ## Template parameters

@ -38,6 +46,21 @@ No-throw guarantee: this function never throws exceptions.

 Linear.

+## Notes
+
+!!! note "Comparing `NaN`"
+
+    `NaN` values are unordered within the domain of numbers.
+    The following comparisons all yield `#!cpp false`:
+      1. Comparing a `NaN` with itself.
+      2. Comparing a `NaN` with another `NaN`.
+      3. Comparing a `NaN` and any other number.
+
+!!! note "Operator overload resolution"
+
+    Since C++20 overload resolution will consider the _rewritten candidate_ generated from
+    [`operator<=>`](operator_spaceship.md).
+
 ## Examples

 ??? example
@ -54,6 +77,11 @@ Linear.
    --8<-- "examples/operator__greaterequal.output"
    ```

+## See also
+
+- [**operator<=>**](operator_spaceship.md) comparison: 3-way
+
 ## Version history

- Added in version 1.0.0.
+1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
+2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/operator_gt.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_gt.md
@ -1,16 +1,24 @@
 # <small>nlohmann::basic_json::</small>operator>

 ```cpp
-bool operator>(const_reference lhs, const_reference rhs) noexcept,
+// until C++20
+bool operator>(const_reference lhs, const_reference rhs) noexcept;   // (1)

 template<typename ScalarType>
-bool operator>(const_reference lhs, const ScalarType rhs) noexcept;
+bool operator>(const_reference lhs, const ScalarType rhs) noexcept;  // (2)

 template<typename ScalarType>
-bool operator>(ScalarType lhs, const const_reference rhs) noexcept;
+bool operator>(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 ```

-Compares whether one JSON value `lhs` is greater than another JSON value `rhs` by calculating `#!cpp !(lhs <= rhs)`.
+1. Compares whether one JSON value `lhs` is greater than another JSON value `rhs` according to the
+  following rules:
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
+      operand is `NaN` and the other operand is either `NaN` or any other number.
+    - Otherwise, returns the result of `#!cpp !(lhs <= rhs)`.
+
+2. Compares wether a JSON value is greater than a scalar or a scalar is greater than a JSON value by
+   converting the scalar to a JSON value and comparing both JSON values according to 1.

 ## Template parameters

@ -37,6 +45,21 @@ No-throw guarantee: this function never throws exceptions.

 Linear.

+## Notes
+
+!!! note "Comparing `NaN`"
+
+    `NaN` values are unordered within the domain of numbers.
+    The following comparisons all yield `#!cpp false`:
+      1. Comparing a `NaN` with itself.
+      2. Comparing a `NaN` with another `NaN`.
+      3. Comparing a `NaN` and any other number.
+
+!!! note "Operator overload resolution"
+
+    Since C++20 overload resolution will consider the _rewritten candidate_ generated from
+    [`operator<=>`](operator_spaceship.md).
+
 ## Examples

 ??? example
@ -53,6 +76,11 @@ Linear.
    --8<-- "examples/operator__greater.output"
    ```

+## See also
+
+- [**operator<=>**](operator_spaceship.md) comparison: 3-way
+
 ## Version history

- Added in version 1.0.0.
+1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
+2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/operator_le.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_le.md
@ -1,17 +1,25 @@
 # <small>nlohmann::basic_json::</small>operator<=

 ```cpp
-bool operator<=(const_reference lhs, const_reference rhs) noexcept,
+// until C++20
+bool operator<=(const_reference lhs, const_reference rhs) noexcept;   // (1)

 template<typename ScalarType>
-bool operator<=(const_reference lhs, const ScalarType rhs) noexcept;
+bool operator<=(const_reference lhs, const ScalarType rhs) noexcept;  // (2)

 template<typename ScalarType>
-bool operator<=(ScalarType lhs, const const_reference rhs) noexcept;
+bool operator<=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 ```

-Compares whether one JSON value `lhs` is less than or equal to another JSON value `rhs` by calculating
-`#cpp !(rhs < lhs)`.
+1. Compares whether one JSON value `lhs` is less than or equal to another JSON value `rhs`
+   according to the following rules:
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
+      operand is `NaN` and the other operand is either `NaN` or any other number.
+    - Otherwise, returns the result of `#!cpp !(rhs < lhs)`.
+
+1. Compares wether a JSON value is less than or equal to a scalar or a scalar is less than or equal
+   to a JSON value by converting the scalar to a JSON value and comparing both JSON values according
+   to 1.

 ## Template parameters

@ -38,6 +46,21 @@ No-throw guarantee: this function never throws exceptions.

 Linear.

+## Notes
+
+!!! note "Comparing `NaN`"
+
+    `NaN` values are unordered within the domain of numbers.
+    The following comparisons all yield `#!cpp false`:
+      1. Comparing a `NaN` with itself.
+      2. Comparing a `NaN` with another `NaN`.
+      3. Comparing a `NaN` and any other number.
+
+!!! note "Operator overload resolution"
+
+    Since C++20 overload resolution will consider the _rewritten candidate_ generated from
+    [`operator<=>`](operator_spaceship.md).
+
 ## Examples

 ??? example
@ -54,6 +77,11 @@ Linear.
    --8<-- "examples/operator__lessequal.output"
    ```

+## See also
+
+- [**operator<=>**](operator_spaceship.md) comparison: 3-way
+
 ## Version history

- Added in version 1.0.0.
+1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
+2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/operator_lt.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_lt.md
@ -1,31 +1,34 @@
 # <small>nlohmann::basic_json::</small>operator<

 ```cpp
-bool operator<(const_reference lhs, const_reference rhs) noexcept;
+// until C++20
+bool operator<(const_reference lhs, const_reference rhs) noexcept;   // (1)

 template<typename ScalarType>
-bool operator<(const_reference lhs, const ScalarType rhs) noexcept;
+bool operator<(const_reference lhs, const ScalarType rhs) noexcept;  // (2)

 template<typename ScalarType>
-bool operator<(ScalarType lhs, const const_reference rhs) noexcept;
+bool operator<(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 ```

-Compares whether one JSON value `lhs` is less than another JSON value `rhs` according to the following rules:
+1. Compares whether one JSON value `lhs` is less than another JSON value `rhs` according to the
+  following rules:
+    - If either operand is discarded, the comparison yields `#!cpp false`.
+    - If both operands have the same type, the values are compared using their respective `operator<`.
+    - Integer and floating-point numbers are automatically converted before comparison.
+    - In case `lhs` and `rhs` have different types, the values are ignored and the order of the types
+      is considered, which is:
+        1. null
+        2. boolean
+        3. number (all types)
+        4. object
+        5. array
+        6. string
+        7. binary
+      For instance, any boolean value is considered less than any string.

- If `lhs` and `rhs` have the same type, the values are compared using the default `<` operator.
- Integer and floating-point numbers are automatically converted before comparison
- Discarded values a
- In case `lhs` and `rhs` have different types, the values are ignored and the order of the types is considered, which
-  is:
-    1. null
-    2. boolean
-    3. number (all types)
-    4. object
-    5. array
-    6. string
-    7. binary
-
-    For instance, any boolean value is considered less than any string.
+2. Compares wether a JSON value is less than a scalar or a scalar is less than a JSON value by converting
+   the scalar to a JSON value and comparing both JSON values according to 1.

 ## Template parameters

@ -52,6 +55,21 @@ No-throw guarantee: this function never throws exceptions.

 Linear.

+## Notes
+
+!!! note "Comparing `NaN`"
+
+    `NaN` values are unordered within the domain of numbers.
+    The following comparisons all yield `#!cpp false`:
+      1. Comparing a `NaN` with itself.
+      2. Comparing a `NaN` with another `NaN`.
+      3. Comparing a `NaN` and any other number.
+
+!!! note "Operator overload resolution"
+
+    Since C++20 overload resolution will consider the _rewritten candidate_ generated from
+    [`operator<=>`](operator_spaceship.md).
+
 ## Examples

 ??? example
@ -68,6 +86,11 @@ Linear.
    --8<-- "examples/operator__less.output"
    ```

+## See also
+
+- [**operator<=>**](operator_spaceship.md) comparison: 3-way
+
 ## Version history

- Added in version 1.0.0.
+1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
+2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/operator_ne.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_ne.md
@ -1,16 +1,32 @@
 # <small>nlohmann::basic_json::</small>operator!=

 ```cpp
-bool operator!=(const_reference lhs, const_reference rhs) noexcept;
+// until C++20
+bool operator!=(const_reference lhs, const_reference rhs) noexcept;   // (1)

 template<typename ScalarType>
-bool operator!=(const_reference lhs, const ScalarType rhs) noexcept;
+bool operator!=(const_reference lhs, const ScalarType rhs) noexcept;  // (2)

 template<typename ScalarType>
-bool operator!=(ScalarType lhs, const const_reference rhs) noexcept;
+bool operator!=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
+
+// since C++20
+class basic_json {
+    bool operator!=(const_reference rhs) const noexcept;              // (1)
+
+    template<typename ScalarType>
+    bool operator!=(ScalarType rhs) const noexcept;                   // (2)
+};
 ```

-Compares two JSON values for inequality by calculating `#!cpp !(lhs == rhs)`.
+1. Compares two JSON values for inequality according to the following rules:
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
+      operand is `NaN` and the other operand is either `NaN` or any other number.
+    - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or
+      `#!cpp !(*this == rhs)` (since C++20).
+
+2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the
+   scalar to a JSON value and comparing both JSON values according to 1.

 ## Template parameters

@ -27,7 +43,7 @@ Compares two JSON values for inequality by calculating `#!cpp !(lhs == rhs)`.

 ## Return value

-whether the values `lhs` and `rhs` are not equal
+whether the values `lhs`/`*this` and `rhs` are not equal

 ## Exception safety

@ -37,6 +53,16 @@ No-throw guarantee: this function never throws exceptions.

 Linear.

+## Notes
+
+!!! note "Comparing `NaN`"
+
+    `NaN` values are unordered within the domain of numbers.
+    The following comparisons all yield `#!cpp false`:
+      1. Comparing a `NaN` with itself.
+      2. Comparing a `NaN` with another `NaN`.
+      3. Comparing a `NaN` and any other number.
+
 ## Examples

 ??? example
@ -69,4 +95,5 @@ Linear.

 ## Version history

- Added in version 1.0.0.
+1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
+2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/operator_spaceship.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_spaceship.md
@ -0,0 +1,70 @@
+# <small>nlohmann::basic_json::</small>operator<=>
+
+```cpp
+// since C++20
+class basic_json {
+    std::partial_ordering operator<=>(const_reference rhs) const noexcept;  // (1)
+
+    template<typename ScalarType>
+    std::partial_ordering operator<=>(const ScalarType rhs) const noexcept; // (2)
+};
+```
+
+1. 3-way compares two JSON values producing a result of type `std::partial_ordering` according to the following rules:
+    - Two JSON values compare with a result of `std::partial_ordering::unordered` if either value is discarded.
+    - If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using their
+      respective `operator<=>`.
+    - Integer and floating-point numbers are converted to their common type and then 3-way compared using their respective
+      `operator<=>`.
+      For instance, comparing an integer and a floating-point value will 3-way compare the first value convertered to
+      floating-point with the second value.
+    - Otherwise, yields a result by comparing the type (see [`value_t`](value_t.md)).
+  
+2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and 3-way
+   comparing both JSON values (see 1).
+
+## Template parameters
+
+`ScalarType`
+:   a scalar type according to `std::is_scalar<ScalarType>::value`
+
+## Parameters
+
+`rhs` (in)
+:   second value to consider 
+
+## Return value
+
+the `std::partial_ordering` of the 3-way comparison of `*this` and `rhs`
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Linear.
+
+## Notes
+
+!!! note "Comparing `NaN`"
+
+    - `NaN` values are unordered within the domain of numbers.
+      The following comparisons all yield `std::partial_ordering::unordered`:
+        1. Comparing a `NaN` with itself.
+        2. Comparing a `NaN` with another `NaN`.
+        3. Comparing a `NaN` and any other number.
+
+## See also
+
+- [**operator==**](operator_eq.md) - comparison: equal
+- [**operator!=**](operator_ne.md) - comparison: not equal
+- [**operator<**](operator_lt.md) - comparison: less than
+- [**operator<=**](operator_le.md) - comparison: less than or equal
+- [**operator>**](operator_gt.md) - comparison: greater than
+- [**operator>=**](operator_ge.md) - comparison: greater than or equal
+
+## Version history
+
+1. Added in version 3.11.0.
+2. Added in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/push_back.md
+++ b/docs/mkdocs/docs/api/basic_json/push_back.md
@ -37,12 +37,9 @@ void push_back(initializer_list_t init);

 ## Exceptions

-1. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON array or null; example: `"cannot use push_back() with number"`
-2. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON object or null; example: `"cannot use push_back() with number"`
+All functions can throw the following exception:
+  - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
+    JSON array or null; example: `"cannot use push_back() with number"`

 ## Complexity

--- a/docs/mkdocs/docs/api/basic_json/to_bjdata.md
+++ b/docs/mkdocs/docs/api/basic_json/to_bjdata.md
@ -0,0 +1,70 @@
+# <small>nlohmann::basic_json::</small>to_bjdata
+
+```cpp
+// (1)
+static std::vector<std::uint8_t> to_bjdata(const basic_json& j,
+                                           const bool use_size = false,
+                                           const bool use_type = false);
+
+// (2)
+static void to_bjdata(const basic_json& j, detail::output_adapter<std::uint8_t> o,
+                      const bool use_size = false, const bool use_type = false);
+static void to_bjdata(const basic_json& j, detail::output_adapter<char> o,
+                      const bool use_size = false, const bool use_type = false);
+```
+
+Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData
+aims to be more compact than JSON itself, yet more efficient to parse.
+
+1. Returns a byte vector containing the BJData serialization.
+2. Writes the BJData serialization to an output adapter.
+
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
+
+## Parameters
+
+`j` (in)
+:   JSON value to serialize
+
+`o` (in)
+:   output adapter to write serialization to
+
+`use_size` (in)
+:   whether to add size annotations to container types; optional, `#!cpp false` by default.
+
+`use_type` (in)
+:   whether to add type annotations to container types (must be combined with `#!cpp use_size = true`); optional,
+`#!cpp false` by default.
+
+## Return value
+
+1. BJData serialization as byte vector
+2. (none)
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of the JSON value `j`.
+
+## Examples
+
+??? example
+
+    The example shows the serialization of a JSON value to a byte vector in BJData format.
+     
+    ```cpp
+    --8<-- "examples/to_bjdata.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_bjdata.output"
+    ```
+
+## Version history
+
+- Added in version 3.11.0.
--- a/docs/mkdocs/docs/api/basic_json/value_t.md
+++ b/docs/mkdocs/docs/api/basic_json/value_t.md
@ -24,10 +24,57 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_

 ## Notes

-There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library
-distinguishes these three types for numbers: [`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
-[`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
-for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
+!!! note "Ordering"
+
+    The order of types is as follows:
+
+    1. `null`
+    2. `boolean`
+    3. `number_integer`, `number_unsigned`, `number_float`
+    4. `object`
+    5. `array`
+    6. `string`
+    7. `binary`
+
+    `discarded` is unordered.
+
+!!! note "Types of numbers"
+
+    There are three enumerators for numbers (`number_integer`, `number_unsigned`, and `number_float`) to distinguish
+    between different types of numbers:
+
+      - [`number_unsigned_t`](number_unsigned_t.md) for unsigned integers
+      - [`number_integer_t`](number_integer_t.md) for signed integers
+      - [`number_float_t`](number_float_t.md) for floating-point numbers or to approximate integers which do not fit
+        into the limits of their respective type
+
+!!! warning "Comparison operators"
+
+    `operator<` and `operator<=>` (since C++20) are overloaded and compare according to the ordering described above.
+    Until C++20 all other relational and equality operators yield results according to the integer value of each
+    enumerator.
+    Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during overload
+    resolution, while others do not.
+    For predictable and portable behavior use:
+
+      - `operator<` or `operator<=>` when wanting to compare according to the order described above
+      - `operator==` or `operator!=` when wanting to compare according to each enumerators integer value
+
+## Examples
+
+??? example
+
+    The following code how `type()` queries the `value_t` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/type.output"
+    ```

 ## Version history

--- a/docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md
+++ b/docs/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md
@ -25,6 +25,22 @@ byte_container_with_subtype(container_type&& container, subtype_type subtype);
 `subtype` (in)
 :   subtype

+## Examples
+
+??? example
+
+    The example below demonstrates how byte containers can be created.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__byte_container_with_subtype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/byte_container_with_subtype__byte_container_with_subtype.output"
+    ```
+
 ## Version history

 Since version 3.8.0.
--- a/docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md
+++ b/docs/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md
@ -15,6 +15,22 @@ No-throw guarantee: this function never throws exceptions.

 Constant.

+## Examples
+
+??? example
+
+    The example below demonstrates how `clear_subtype` can remove subtypes.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__clear_subtype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/byte_container_with_subtype__clear_subtype.output"
+    ```
+
 ## Version history

 Since version 3.8.0.
--- a/docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md
+++ b/docs/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md
@ -18,6 +18,22 @@ No-throw guarantee: this function never throws exceptions.

 Constant.

+## Examples
+
+??? example
+
+    The example below demonstrates how `has_subtype` can check whether a subtype was set.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__has_subtype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/byte_container_with_subtype__has_subtype.output"
+    ```
+
 ## Version history

 Since version 3.8.0.
--- a/docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md
+++ b/docs/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md
@ -20,6 +20,22 @@ No-throw guarantee: this function never throws exceptions.

 Constant.

+## Examples
+
+??? example
+
+    The example below demonstrates how a subtype can be set with `set_subtype`.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__set_subtype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/byte_container_with_subtype__set_subtype.output"
+    ```
+
 ## Version history

 Since version 3.8.0.
--- a/docs/mkdocs/docs/api/byte_container_with_subtype/subtype.md
+++ b/docs/mkdocs/docs/api/byte_container_with_subtype/subtype.md
@ -19,6 +19,23 @@ No-throw guarantee: this function never throws exceptions.

 Constant.

+## Examples
+
+??? example
+
+    The example below demonstrates how the subtype can be retrieved with `subtype`. Note how `subtype_type(-1)` is
+    returned for container `c1`.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__subtype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/byte_container_with_subtype__subtype.output"
+    ```
+
 ## Version history

 - Added in version 3.8.0
--- a/docs/mkdocs/docs/api/json.md
+++ b/docs/mkdocs/docs/api/json.md
@ -7,6 +7,22 @@ using json = basic_json<>;
 This type is the default specialization of the [basic_json](basic_json/index.md) class which uses the standard template
 types.

+## Examples
+
+??? example
+
+    The example below demonstrates how to use the type `nlohmann::json`.
+
+    ```cpp
+    --8<-- "examples/README.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/README.output"
+    ```
+
 ## Version history

 Since version 1.0.0.
--- a/docs/mkdocs/docs/api/json_pointer/index.md
+++ b/docs/mkdocs/docs/api/json_pointer/index.md
@ -14,11 +14,11 @@ are the base for JSON patches.
 `RefStringType`
 :   the string type used for the reference tokens making up the JSON pointer

-## Notes
+!!! warning "Deprecation"

-For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md) in
-which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is deprecated
-and may be removed in a future major version.
+    For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md)
+    in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is
+    deprecated and may be removed in a future major version.

 ## Member types

--- a/docs/mkdocs/docs/api/json_pointer/operator_string.md
+++ b/docs/mkdocs/docs/api/json_pointer/operator_string.md
@ -19,6 +19,22 @@ operator string_t() const
 }
 ```

+## Examples
+
+??? example
+
+    The example shows how JSON Pointers can be implicitly converted to strings.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__operator_string.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__operator_string.output"
+    ```
+
 ## Version history

 - Since version 2.0.0.
--- a/docs/mkdocs/docs/api/json_pointer/string_t.md
+++ b/docs/mkdocs/docs/api/json_pointer/string_t.md
@ -7,6 +7,22 @@ The string type used for the reference tokens making up the JSON pointer.

 See [`basic_json::string_t`](../basic_json/string_t.md) for more information.

+## Examples
+
+??? example
+
+    The example shows the type `string_t` and its relation to `basic_json::string_t`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__string_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__string_t.output"
+    ```
+
 ## Version history

 - Added in version 3.11.0.
--- a/docs/mkdocs/docs/api/json_sax/binary.md
+++ b/docs/mkdocs/docs/api/json_sax/binary.md
@ -19,6 +19,22 @@ Whether parsing should proceed.

 It is safe to move the passed binary value.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse__binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse__binary.output"
+    ```
+
 ## Version history

 - Added in version 3.8.0.
--- a/docs/mkdocs/docs/api/json_sax/boolean.md
+++ b/docs/mkdocs/docs/api/json_sax/boolean.md
@ -15,6 +15,22 @@ A boolean value was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/end_array.md
+++ b/docs/mkdocs/docs/api/json_sax/end_array.md
@ -10,6 +10,22 @@ The end of an array was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/end_object.md
+++ b/docs/mkdocs/docs/api/json_sax/end_object.md
@ -10,6 +10,22 @@ The end of an object was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/key.md
+++ b/docs/mkdocs/docs/api/json_sax/key.md
@ -19,6 +19,22 @@ Whether parsing should proceed.

 It is safe to move the passed object key value.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/null.md
+++ b/docs/mkdocs/docs/api/json_sax/null.md
@ -10,6 +10,22 @@ A null value was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/number_float.md
+++ b/docs/mkdocs/docs/api/json_sax/number_float.md
@ -18,6 +18,22 @@ A floating-point number was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/number_integer.md
+++ b/docs/mkdocs/docs/api/json_sax/number_integer.md
@ -15,6 +15,22 @@ An integer number was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/number_unsigned.md
+++ b/docs/mkdocs/docs/api/json_sax/number_unsigned.md
@ -15,6 +15,22 @@ An unsigned integer number was read.

 Whether parsing should proceed.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/parse_error.md
+++ b/docs/mkdocs/docs/api/json_sax/parse_error.md
@ -23,6 +23,22 @@ A parse error occurred.

 Whether parsing should proceed (**must return `#!cpp false`**).

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/start_array.md
+++ b/docs/mkdocs/docs/api/json_sax/start_array.md
@ -19,6 +19,22 @@ Whether parsing should proceed.

 Binary formats may report the number of elements.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/start_object.md
+++ b/docs/mkdocs/docs/api/json_sax/start_object.md
@ -19,6 +19,22 @@ Whether parsing should proceed.

 Binary formats may report the number of elements.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/json_sax/string.md
+++ b/docs/mkdocs/docs/api/json_sax/string.md
@ -19,6 +19,22 @@ Whether parsing should proceed.

 It is safe to move the passed string value.

+## Examples
+
+??? example
+
+    .The example below shows how the SAX interface is used.
+
+    ```cpp
+    --8<-- "examples/sax_parse.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse.output"
+    ```
+
 ## Version history

 - Added in version 3.2.0.
--- a/docs/mkdocs/docs/api/macros/index.md
+++ b/docs/mkdocs/docs/api/macros/index.md
@ -17,6 +17,8 @@ header. See also the [macro overview page](../../features/macros.md).

 - [**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
 - [**JSON_HAS_FILESYSTEM**<br>**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support
+- [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support
+- [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers

@ -27,8 +29,15 @@ header. See also the [macro overview page](../../features/macros.md).

 ## Type conversions

+- [**JSON_DISABLE_ENUM_SERIALIZATION**](json_disable_enum_serialization.md) - switch off default serialization/deserialization functions for enums
 - [**JSON_USE_IMPLICIT_CONVERSIONS**](json_use_implicit_conversions.md) - control implicit conversions

+<!-- comment-->
+## Comparison behavior
+
+- [**JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON**](json_use_legacy_discarded_value_comparison.md) -
+  control comparison of discarded values
+
 ## Serialization/deserialization macros

 - [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_intrusive.md) - serialization/deserialization of types _with_ access to private variables
--- a/docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md
+++ b/docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md
@ -0,0 +1,135 @@
+# JSON_DISABLE_ENUM_SERIALIZATION
+
+```cpp
+#define JSON_DISABLE_ENUM_SERIALIZATION
+```
+
+When defined, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see [arbitrary type conversions](../../features/arbitrary_types.md) for more details).
+
+Parsing or serializing an enum will result in a compiler error.
+
+This works for both unscoped and scoped enums.
+
+## Default definition
+
+By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
+
+```cpp
+#undef JSON_DISABLE_ENUM_SERIALIZATION
+```
+
+## Examples
+
+??? example "Example 1: Disabled behavior"
+
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below **does not** compile.
+
+    ```cpp
+    #define JSON_DISABLE_ENUM_SERIALIZATION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    enum class Choice
+    {
+        first,
+        second,
+    };
+    
+    int main()
+    {
+        // normally invokes to_json serialization function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
+        const json j = Choice::first; 
+
+        // normally invokes from_json parse function but with JSON_DISABLE_ENUM_SERIALIZATION defined, it does not
+        Choice ch = j.get<Choice>();
+    }
+    ```
+
+??? example "Example 2: Serialize enum macro"
+
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
+
+    ```cpp
+    #define JSON_DISABLE_ENUM_SERIALIZATION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    enum class Choice
+    {
+        first,
+        second,
+    };
+
+    NLOHMANN_JSON_SERIALIZE_ENUM(Choice,
+    {
+        { Choice::first, "first" },
+        { Choice::second, "second" },
+    })
+    
+    int main()
+    {
+        // uses user-defined to_json function defined by macro
+        const json j = Choice::first; 
+
+        // uses user-defined from_json function defined by macro
+        Choice ch = j.get<Choice>();
+    }
+    ```
+
+??? example "Example 3: User-defined serialization/deserialization functions"
+
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined functions to parse and serialize the enum.
+
+    ```cpp
+    #define JSON_DISABLE_ENUM_SERIALIZATION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    enum class Choice
+    {
+        first,
+        second,
+    };
+
+    void from_json(const json& j, Choice& ch)
+    {
+        auto value = j.get<std::string>();
+        if (value == "first")
+        {
+            ch = Choice::first;
+        }
+        else if (value == "second")
+        {
+            ch = Choice::second;
+        }
+    }
+
+    void to_json(json& j, const Choice& ch)
+    {
+        auto value = j.get<std::string>();
+        if (value == "first")
+        {
+            ch = Choice::first;
+        }
+        else if (value == "second")
+        {
+            ch = Choice::second;
+        }
+    }
+    
+    int main()
+    {
+        // uses user-defined to_json function
+        const json j = Choice::first; 
+
+        // uses user-defined from_json function
+        Choice ch = j.get<Choice>();
+    }
+    ```
+
+## See also
+
+- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md)
--- a/docs/mkdocs/docs/api/macros/json_has_cpp_11.md
+++ b/docs/mkdocs/docs/api/macros/json_has_cpp_11.md
@ -23,6 +23,19 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu
 - `#!cpp JSON_HAS_CPP_11` is always defined.
 - All macros are undefined outside the library.

+## Examples
+
+??? example
+
+    The code below forces the library to use the C++14 standard:
+
+    ```cpp
+    #define JSON_HAS_CPP_14 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history

 - Added in version 3.10.5.
--- a/docs/mkdocs/docs/api/macros/json_has_filesystem.md
+++ b/docs/mkdocs/docs/api/macros/json_has_filesystem.md
@ -25,6 +25,19 @@ The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_
  filesystem support.
 - Both macros are undefined outside the library.

+## Examples
+
+??? example
+
+    The code below forces the library to use the header `<experimental/filesystem>`.
+
+    ```cpp
+    #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history

 - Added in version 3.10.5.
--- a/docs/mkdocs/docs/api/macros/json_has_ranges.md
+++ b/docs/mkdocs/docs/api/macros/json_has_ranges.md
@ -0,0 +1,18 @@
+# JSON_HAS_RANGES
+
+```cpp
+#define JSON_HAS_RANGES /* value */
+```
+
+This macro indicates whether the standard library has any support for ranges. Implies support for concepts.
+Possible values are `1` when supported or `0` when unsupported.
+
+## Default definition
+
+The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_ranges`.
+
+When the macro is not defined, the library will define it to its default value.
+
+## Version history
+
+- Added in version 3.11.0.
--- a/docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md
+++ b/docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md
@ -0,0 +1,19 @@
+# JSON_HAS_THREE_WAY_COMPARISON
+
+```cpp
+#define JSON_HAS_THREE_WAY_COMPARISON /* value */
+```
+
+This macro indicates whether the compiler and standard library support 3-way comparison.
+Possible values are `1` when supported or `0` when unsupported.
+
+## Default definition
+
+The default value is detected based on the preprocessor macros `#!cpp __cpp_impl_three_way_comparison`
+and `#!cpp __cpp_lib_three_way_comparison`.
+
+When the macro is not defined, the library will define it to its default value.
+
+## Version history
+
+- Added in version 3.11.0.
--- a/Show More
+++ b/Show More