♻️ adjust write_u_escape signature

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

.cirrus.yml

@@ -3,15 +3,15 @@ arm_container:
 
 check_task:
   check_script:
-  - wget https://github.com/Kitware/CMake/releases/download/v3.20.2/cmake-3.20.2.tar.gz
-  - tar xfz cmake-3.20.2.tar.gz
-  - cd cmake-3.20.2
-  - ./configure
-  - make cmake ctest -j4
-  - cd ..
+  # the gcc image ships an outdated CMake, so fetch a recent prebuilt binary
+  # instead of compiling CMake from source
+  - wget -q https://github.com/Kitware/CMake/releases/download/v4.3.4/cmake-4.3.4-linux-aarch64.tar.gz
+  - tar xfz cmake-4.3.4-linux-aarch64.tar.gz
+  - export PATH="$(pwd)/cmake-4.3.4-linux-aarch64/bin:$PATH"
+  - cmake --version
   - mkdir build
   - cd build
-  - ../cmake-3.20.2/bin/cmake .. -DJSON_FastTests=ON
+  - cmake .. -DJSON_FastTests=ON
   - make -j4
   - cd tests
-  - ../../cmake-3.20.2/bin/ctest -j4
+  - ctest -j4

.clang-tidy

@@ -1,4 +1,5 @@
 # TODO: The first three checks are only removed to get the CI going. They have to be addressed at some point.
+# TODO: portability-avoid-pragma-once: should be fixed eventually
 
 Checks: '*,
 
@@ -21,6 +22,7 @@ Checks: '*,
          -cppcoreguidelines-avoid-magic-numbers,
          -cppcoreguidelines-avoid-non-const-global-variables,
          -cppcoreguidelines-macro-usage,
+         -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
          -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
          -cppcoreguidelines-pro-bounds-constant-array-index,
          -cppcoreguidelines-pro-bounds-pointer-arithmetic,
@@ -33,6 +35,7 @@ Checks: '*,
          -fuchsia-overloaded-operator,
          -google-explicit-constructor,
          -google-readability-function-size,
+         -google-runtime-float,
          -google-runtime-int,
          -google-runtime-references,
          -hicpp-avoid-goto,
@@ -44,6 +47,8 @@ Checks: '*,
          -hicpp-uppercase-literal-suffix,
          -llvm-header-guard,
          -llvm-include-order,
+         -llvm-prefer-static-over-anonymous-namespace,
+         -llvm-use-ranges,
          -llvmlibc-*,
          -misc-use-anonymous-namespace,
          -misc-confusable-identifiers,
@@ -59,13 +64,16 @@ Checks: '*,
          -modernize-use-std-numbers,
          -modernize-use-trailing-return-type,
          -performance-enum-size,
+         -portability-avoid-pragma-once,
          -readability-function-cognitive-complexity,
          -readability-function-size,
          -readability-identifier-length,
          -readability-magic-numbers,
          -readability-redundant-access-specifiers,
+         -readability-redundant-parentheses,
          -readability-simplify-boolean-expr,
-         -readability-uppercase-literal-suffix'
+         -readability-uppercase-literal-suffix,
+         -readability-use-concise-preprocessor-directives'
 
 CheckOptions:
   - key: hicpp-special-member-functions.AllowSoleDefaultDtor

.github/CONTRIBUTING.md

@@ -153,6 +153,9 @@ files directly; instead, modify the include/nlohmann sources and regenerate the
 make amalgamate
 ```
 
+Running `make amalgamate` will also apply automatic formatting to the source files using
+[`Artistic Style`](https://astyle.sourceforge.net/). This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.
+
 ## Recommended documentation
 
 - The library’s [README file](https://github.com/nlohmann/json/blob/master/README.md) is an excellent starting point to

.github/ISSUE_TEMPLATE/bug.yaml

@@ -14,6 +14,8 @@ body:
         Note that this form is for bug reports only. Please
         [open a discussion](https://github.com/nlohmann/json/discussions/new)
         for questions, feature requests, or support requests.
+        **Please check the [FAQ](https://json.nlohmann.me/home/faq/) before
+        reporting an issue.** Common questions are answered there.        
   - type: textarea
     id: summary
     attributes:

.github/config.yml

@@ -13,7 +13,7 @@ sentimentBotReplyComment: >
 
 # *Required* Comment to reply with
 requestInfoReplyComment: >
-  We would appreciate it if you could provide us with more info about this issue or pull request! Please check the [issue template](https://github.com/nlohmann/json/blob/develop/.github/ISSUE_TEMPLATE.md) and the [pull request template](https://github.com/nlohmann/json/blob/develop/.github/PULL_REQUEST_TEMPLATE.md).
+  We would appreciate it if you could provide us with more info about this issue or pull request! Please check the [issue template](https://github.com/nlohmann/json/issues/new/choose) and the [pull request template](https://github.com/nlohmann/json/blob/develop/.github/PULL_REQUEST_TEMPLATE.md).
 
 # *OPTIONAL* Label to be added to Issues and Pull Requests with insufficient information given
 requestInfoLabelToAdd: "state: needs more info"

.github/dependabot.yml

@@ -4,6 +4,10 @@ updates:
     directory: /
     schedule:
       interval: daily
+    groups:
+      codeql-action:
+        patterns:
+          - "github/codeql-action/*"
 
   - package-ecosystem: pip
     directory: /docs/mkdocs

.github/labeler.yml

@@ -23,11 +23,11 @@ labels:
 
 - label: "CI"
   files:
-    - "github/workflows/.*"
+    - ".github/workflows/.*"
 
 - label: "CI"
   files:
-    - "github/external_ci/.*"
+    - ".github/external_ci/.*"
 
 - label: "S"
   size-below: 10

.github/workflows/check_amalgamation.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
@@ -20,7 +20,7 @@ jobs:
           mkdir -p ./pr
           echo ${{ github.event.number }} > ./pr/number
           echo ${{ github.event.pull_request.user.login }} > ./pr/author
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: pr
           path: pr/
@@ -34,43 +34,65 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
       - name: Checkout pull request
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           path: main
           ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
 
       - name: Checkout tools
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           path: tools
           ref: develop
+          persist-credentials: false
 
       - name: Install astyle
         run: |
           python3 -mvenv venv
           venv/bin/pip3 install -r $MAIN_DIR/tools/astyle/requirements.txt
 
-      - name: Check amalgamation
+      - name: Regenerate amalgamation and formatting
         run: |
           cd $MAIN_DIR
 
-          rm -fr $INCLUDE_DIR/json.hpp~ $INCLUDE_DIR/json_fwd.hpp~
-          cp $INCLUDE_DIR/json.hpp $INCLUDE_DIR/json.hpp~
-          cp $INCLUDE_DIR/json_fwd.hpp $INCLUDE_DIR/json_fwd.hpp~
-
           python3 $TOOL_DIR/amalgamate.py -c $TOOL_DIR/config_json.json -s .
           python3 $TOOL_DIR/amalgamate.py -c $TOOL_DIR/config_json_fwd.json -s .
-          echo "Format (1)"
-          ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet $INCLUDE_DIR/json.hpp $INCLUDE_DIR/json_fwd.hpp
 
-          diff $INCLUDE_DIR/json.hpp~ $INCLUDE_DIR/json.hpp
-          diff $INCLUDE_DIR/json_fwd.hpp~ $INCLUDE_DIR/json_fwd.hpp
+          ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet \
+            $INCLUDE_DIR/json.hpp $INCLUDE_DIR/json_fwd.hpp
 
-          ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=orig $(find docs/examples include tests -type f \( -name '*.hpp' -o -name '*.cpp' -o -name '*.cu' \) -not -path 'tests/thirdparty/*' -not -path 'tests/abi/include/nlohmann/*' | sort)
-          echo Check
-          find $MAIN_DIR -name '*.orig' -exec false {} \+
+          ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet \
+            $(find docs/examples include tests -type f \( -name '*.hpp' -o -name '*.cpp' -o -name '*.cu' \) -not -path 'tests/thirdparty/*' -not -path 'tests/abi/include/nlohmann/*' | sort)
+
+      - name: Build patch and check for differences
+        id: diff
+        run: |
+          cd $MAIN_DIR
+          mkdir -p ${{ github.workspace }}/patch
+          git diff --patch --no-color > ${{ github.workspace }}/patch/amalgamation.patch
+          if [ -s ${{ github.workspace }}/patch/amalgamation.patch ]; then
+            echo "The source code has not been amalgamated/formatted correctly. Diff:"
+            cat ${{ github.workspace }}/patch/amalgamation.patch
+            echo "has_diff=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_diff=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Uploaded so contributors can fix their PR with `git apply amalgamation.patch`
+      # instead of installing the pinned astyle version locally.
+      - name: Upload patch
+        if: steps.diff.outputs.has_diff == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: amalgamation-patch
+          path: patch/amalgamation.patch
+
+      - name: Fail if not amalgamated/formatted
+        if: steps.diff.outputs.has_diff == 'true'
+        run: exit 1

.github/workflows/cifuzz.yml

@@ -6,29 +6,32 @@ permissions:
 
 jobs:
   Fuzzing:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
     - name: Harden Runner
-      uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
       with:
         egress-policy: audit
 
+    # The OSS-Fuzz CIFuzz actions are referenced via @master as recommended by
+    # the OSS-Fuzz documentation; the project does not publish tags or releases
+    # to pin to. See https://google.github.io/oss-fuzz/getting-started/continuous-integration/
     - name: Build Fuzzers
       id: build
-      uses: google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@57fe4475324c5506adbfecdcdd2917f65c86ee9e # master
+      uses: google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master
       with:
         oss-fuzz-project-name: 'json'
         dry-run: false
         language: c++
     - name: Run Fuzzers
-      uses: google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@57fe4475324c5506adbfecdcdd2917f65c86ee9e # master
+      uses: google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@master
       with:
         oss-fuzz-project-name: 'json'
         fuzz-seconds: 300
         dry-run: false
         language: c++
     - name: Upload Crash
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
       if: failure() && steps.build.outcome == 'success'
       with:
         name: artifacts

.github/workflows/codeql-analysis.yml

@@ -27,23 +27,25 @@ jobs:
 
     steps:
     - name: Harden Runner
-      uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+      uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
       with:
         egress-policy: audit
 
     - name: Checkout repository
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      with:
+        persist-credentials: false
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+      uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
       with:
         languages: c-cpp
 
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+      uses: github/codeql-action/autobuild@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+      uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3

.github/workflows/comment_check_amalgamation.yml

@@ -19,12 +19,13 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
       - name: 'Download artifact'
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        id: download
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
@@ -43,16 +44,33 @@ jobs:
             });
             var fs = require('fs');
             fs.writeFileSync('${{github.workspace}}/pr.zip', Buffer.from(download.data));
-      - run: unzip pr.zip
+
+            var hasPatch = artifacts.data.artifacts.some((artifact) => artifact.name == "amalgamation-patch");
+            core.setOutput('has_patch', String(hasPatch));
+      # Extract the untrusted PR artifact into a dedicated empty directory and
+      # read only the two expected files by fixed path afterwards. This avoids a
+      # malicious archive overwriting workspace files or escaping via ../ paths.
+      - run: unzip -o pr.zip -d ./pr_artifact
 
       - name: 'Comment on PR'
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             var fs = require('fs');
-            const author = fs.readFileSync('./author')
-            const issue_number = Number(fs.readFileSync('./number'));
+            // Both values come from a fork-triggered workflow and are therefore
+            // attacker-controlled. Validate them strictly before use to prevent
+            // Markdown/mention injection and bogus REST API filters.
+            const author = fs.readFileSync('./pr_artifact/author', 'utf8').trim();
+            if (!/^[A-Za-z0-9-]{1,39}$/.test(author)) {
+              core.setFailed(`Refusing to proceed: untrusted author value '${author}' is not a valid GitHub username.`);
+              return;
+            }
+            const issue_number = Number(fs.readFileSync('./pr_artifact/number', 'utf8').trim());
+            if (!Number.isInteger(issue_number) || issue_number <= 0) {
+              core.setFailed('Refusing to proceed: untrusted PR number is not a positive integer.');
+              return;
+            }
             const opts = github.rest.issues.listForRepo.endpoint.merge({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -70,12 +88,20 @@ jobs:
                 break
               }
             }
+            const hasPatch = '${{ steps.download.outputs.has_patch }}' === 'true';
+            const runUrl = '${{ github.event.workflow_run.html_url }}';
+
             await github.rest.issues.createComment({
               issue_number: issue_number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: '## 🔴 Amalgamation check failed! 🔴\nThe source code has not been amalgamated.'
-                    + (first ? ' @' + author + ' Please read and follow the [Contribution Guidelines]'
+              body: '## 🔴 Amalgamation check failed! 🔴\nThe source code has not been amalgamated and/or formatted correctly.'
+                    + (hasPatch ? '\n\n📎 A ready-to-apply patch is attached to the [failed workflow run](' + runUrl + ') as the `amalgamation-patch` artifact.'
+                                  + ' Download it, then apply it locally from the repository root with:'
+                                  + '\n\n```shell\ngit apply amalgamation.patch\n```\n\n'
+                                  + 'This does not require installing astyle yourself.'
+                                : '')
+                    + (first ? '\n\n@' + author + ' Please read and follow the [Contribution Guidelines]'
                                + '(https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#files-to-change).'
                              : '')
               })

.github/workflows/dependency-review.yml

@@ -17,11 +17,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
       - name: 'Checkout Repository'
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@da24556b548a50705dd671f47852072ea4c105d9 # v4.7.1
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0

.github/workflows/flawfinder.yml

@@ -0,0 +1,48 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: flawfinder
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ "develop" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "develop" ]
+  schedule:
+    - cron: '41 14 * * 3'
+
+jobs:
+  flawfinder:
+    name: Flawfinder
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: flawfinder_scan
+        uses: david-a-wheeler/flawfinder@c4216b74cf2639ffa98503768bd6e4299b5440c9 # v2.0.20
+        with:
+          arguments: '--sarif ./'
+          output: 'flawfinder_results.sarif'
+
+      - name: Upload analysis results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        with:
+          sarif_file: ${{github.workspace}}/flawfinder_results.sarif

.github/workflows/labeler.yml

@@ -17,10 +17,10 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
-      - uses: srvaroa/labeler@e7bef2249506ba9cbbd3ca5cee256abd9f930b04 # master
+      - uses: srvaroa/labeler@bf262763a8a8e191f5847873aecc0f29df84f957 # v1.14.0
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/macos.yml

@@ -17,69 +17,18 @@ permissions:
   contents: read
 
 jobs:
-# macos-11 is deprecated
-#  macos-11:
-#    runs-on: macos-11
-#    strategy:
-#      matrix:
-#        xcode: ['11.7', '12.4', '12.5.1', '13.0']
-#    env:
-#      DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
-#
-#    steps:
-#      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-#      - name: Run 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
-
-# macos-12 is deprecated (https://github.com/actions/runner-images/issues/10721)
-#  macos-12:
-#    runs-on: macos-12 # https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md
-#    strategy:
-#      matrix:
-#        xcode: ['13.1', '13.2.1', '13.3.1', '13.4.1', '14.0', '14.0.1', '14.1']
-#    env:
-#      DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
-#
-#    steps:
-#      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-#      - name: Run 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
-
-  macos-13:
-    runs-on: macos-13 # https://github.com/actions/runner-images/blob/main/images/macos/macos-13-Readme.md
-    strategy:
-      matrix:
-        xcode: ['14.1', '14.2', '14.3', '14.3.1', '15.0.1', '15.1', '15.2']
-    env:
-      DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - name: Run 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
-
   macos-14:
     runs-on: macos-14 # https://github.com/actions/runner-images/blob/main/images/macos/macos-14-Readme.md
     strategy:
       matrix:
-        xcode: ['15.3', '15.4']
+        xcode: ['15.0.1', '15.1', '15.2', '15.3', '15.4']
     env:
       DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -D CMAKE_BUILD_TYPE=Debug -DJSON_BuildTests=On -DJSON_FastTests=ON
       - name: Build
@@ -91,12 +40,14 @@ jobs:
     runs-on: macos-15 # https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md
     strategy:
       matrix:
-        xcode: ['16.0', '16.1', '16.2']
+        xcode: ['16.0', '16.1', '16.2', '16.3', '16.4', '26.0.1']
     env:
       DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -D CMAKE_BUILD_TYPE=Debug -DJSON_BuildTests=On -DJSON_FastTests=ON
       - name: Build
@@ -111,7 +62,9 @@ jobs:
         standard: [11, 14, 17, 20, 23, 26]
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -D CMAKE_BUILD_TYPE=Debug -DJSON_BuildTests=On -DJSON_TestStandards=${{ matrix.standard }}
       - name: Build

.github/workflows/publish_documentation.yml

@@ -27,11 +27,11 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Install virtual environment
         run: make install_venv -C docs/mkdocs
@@ -40,7 +40,7 @@ jobs:
         run: make build -C docs/mkdocs
 
       - name: Deploy documentation
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/mkdocs/site

.github/workflows/scorecards.yml

@@ -36,17 +36,17 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
       - name: "Checkout code"
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
       - name: "Run analysis"
-        uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
         with:
           results_file: results.sarif
           results_format: sarif
@@ -68,7 +68,7 @@ jobs:
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
       # format to the repository Actions tab.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: SARIF file
           path: results.sarif
@@ -76,6 +76,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
         with:
           sarif_file: results.sarif

.github/workflows/semgrep.yml

@@ -0,0 +1,67 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# This workflow file requires a free account on Semgrep.dev to
+# manage rules, file ignores, notifications, and more.
+#
+# See https://semgrep.dev/docs
+
+name: Semgrep
+
+on:
+  push:
+    branches: [ "develop" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "develop" ]
+  schedule:
+    - cron: '23 2 * * 4'
+
+permissions:
+  contents: read
+
+jobs:
+  semgrep:
+    permissions:
+      contents: read # for actions/checkout to fetch code
+      security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
+      actions: read # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status
+    name: Scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
+        with:
+          egress-policy: audit
+
+      # Checkout project source
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      # The former returntocorp/semgrep-action is deprecated (the org was renamed
+      # to semgrep/*); the maintained approach is to install the CLI and invoke
+      # it directly. We use `semgrep scan` (not `semgrep ci`, which requires a
+      # login token): with no SEMGREP_APP_TOKEN configured this is exactly what
+      # the old action fell back to, running community rules with no token.
+      # SEMGREP_APP_TOKEN is still passed through so registry auth works if a
+      # token is ever added.
+      - name: Install Semgrep
+        run: python3 -m pip install --user semgrep
+
+      # `semgrep scan --sarif` always exits 0 even with findings; continue-on-error
+      # is a safety net so the SARIF upload still runs if the scan itself errors.
+      - name: Run Semgrep
+        run: semgrep scan --config auto --sarif --output=semgrep.sarif
+        continue-on-error: true
+        env:
+          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+
+      # Upload SARIF file generated in previous step
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+        with:
+          sarif_file: semgrep.sarif
+        if: always()

.github/workflows/stale.yml

@@ -16,11 +16,11 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
-      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.0
+      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
         with:
           stale-issue-label: 'state: stale'
           stale-pr-label: 'state: stale'

.github/workflows/ubuntu.yml

@@ -21,9 +21,11 @@ jobs:
     runs-on: ubuntu-latest
     container: gcc:latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -33,7 +35,9 @@ jobs:
     runs-on: ubuntu-latest
     container: ghcr.io/nlohmann/json-ci:v2.4.0
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -46,15 +50,17 @@ jobs:
         target: [ci_test_amalgamation, ci_test_single_header, ci_cppcheck, ci_cpplint, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_reuse_compliance, ci_test_valgrind]
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
       - name: Install Valgrind
         run: sudo apt-get update ; sudo apt-get install -y valgrind
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -69,9 +75,11 @@ jobs:
     steps:
       - name: Install git, clang-tools, iwyu (ci_single_binaries), and unzip
         run: apt-get update ; apt-get install -y git clang-tools iwyu unzip
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -86,9 +94,11 @@ jobs:
     steps:
       - name: Install build-essential
         run: apt-get update ; apt-get install -y build-essential unzip wget git libssl-dev
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -98,11 +108,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Install dependencies and de_DE locale
         run: |
           sudo apt-get clean
@@ -115,15 +127,16 @@ jobs:
       - name: Build
         run: cmake --build build --target ci_test_coverage
       - name: Archive coverage report
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: code-coverage-report
           path: ${{ github.workspace }}/build/html
       - name: Publish report to Coveralls
-        uses: coverallsapp/github-action@648a8eb78e6d50909eff900e4ec85cab4524a45b # v2.3.6
+        uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e # v2.3.7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           path-to-lcov: ${{ github.workspace }}/build/json.info.filtered.noexcept
+          fail-on-error: false
 
   ci_test_compilers_gcc_old:
     runs-on: ubuntu-latest
@@ -132,7 +145,9 @@ jobs:
         compiler: ['4.8', '4.9', '5', '6']
     container: ghcr.io/nlohmann/json-ci:v2.4.0
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: CXX=g++-${{ matrix.compiler }} cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -146,9 +161,11 @@ jobs:
         compiler: ['7', '8', '9', '10', '11', '12', '13', '14', '15', 'latest']
     container: gcc:${{ matrix.compiler }}
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -161,11 +178,11 @@ jobs:
         compiler: ['3.4', '3.5', '3.6', '3.7', '3.8', '3.9', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15-bullseye', '16', '17', '18', '19', '20', 'latest']
     container: silkeh/clang:${{ matrix.compiler }}
     steps:
-      - name: Install unzip and git
-        run: apt-get update ; apt-get install -y unzip git
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Set env FORCE_STDCPPFS_FLAG for clang 7 / 8 / 9 / 10
         run: echo "JSON_FORCED_GLOBAL_COMPILE_OPTIONS=-DJSON_HAS_FILESYSTEM=0;-DJSON_HAS_EXPERIMENTAL_FILESYSTEM=0" >> "$GITHUB_ENV"
         if: ${{ matrix.compiler == '7' || matrix.compiler == '8' || matrix.compiler == '9' || matrix.compiler == '10' }}
@@ -181,9 +198,11 @@ jobs:
       matrix:
         standard: [11, 14, 17, 20, 23, 26]
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -199,9 +218,11 @@ jobs:
     steps:
       - name: Install git and unzip
         run: apt-get update ; apt-get install -y git unzip
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build with libc++
@@ -215,7 +236,9 @@ jobs:
     runs-on: ubuntu-latest
     container: ghcr.io/nlohmann/json-ci:v2.4.0
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -228,9 +251,24 @@ jobs:
     runs-on: ubuntu-latest
     container: ${{ matrix.container }}
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      # The module test uses `import std;`, which needs CMake's experimental
+      # import-std support. Its opt-in token is CMake-version-specific, so pin
+      # CMake to the version whose token is set in tests/module_cpp20/CMakeLists.txt.
+      - name: Get pinned CMake and ninja
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
+        with:
+          cmakeVersion: 4.3.4
+      # Clang: the std library module is provided by libc++ (the image's libstdc++
+      # ships none), and the image's libc++ module manifest has a broken relative
+      # path — repoint it at the real module sources.
+      - name: Use libc++ and fix its module manifest path (Clang)
+        if: matrix.container == 'silkeh/clang:latest'
+        run: |
+          echo "CXXFLAGS=-stdlib=libc++" >> "$GITHUB_ENV"
+          mkdir -p /usr/lib/share && ln -sf /usr/lib/llvm-*/share/libc++ /usr/lib/share/libc++
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -240,7 +278,9 @@ jobs:
     runs-on: ubuntu-latest
     container: ghcr.io/nlohmann/json-ci:v2.2.0
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
@@ -248,19 +288,45 @@ jobs:
           . /opt/intel/oneapi/setvars.sh
           cmake --build build --target ci_icpc
 
+  ci_icpx:
+    runs-on: ubuntu-latest
+    container: intel/oneapi-hpckit:latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_icpx
+
+  ci_nvhpc:
+    runs-on: ubuntu-latest
+    container: nvcr.io/nvidia/nvhpc:25.5-devel-cuda12.9-ubuntu22.04
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_nvhpc
+
   ci_emscripten:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
       - name: Install emscripten
-        uses: mymindstorm/setup-emsdk@v14
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: mymindstorm/setup-emsdk@4528d102f7230f0e7b276855c01ea1159be0e984 # v16
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@ea004816823209b8d1211e47b216185caee12cc5 # v4.02
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
       - name: Run CMake
         run: cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -GNinja
       - name: Build
@@ -273,11 +339,13 @@ jobs:
         target: [ci_test_examples, ci_test_build_documentation]
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build

.github/workflows/windows.yml

@@ -18,15 +18,17 @@ concurrency:
 
 jobs:
   mingw:
-    runs-on: windows-2019
+    runs-on: windows-2022
     strategy:
       matrix:
         architecture: [x64, x86]
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Set up MinGW
-        uses: egor-tensin/setup-mingw@84c781b557efd538dec66bde06988d81cd3138cf # v2.2.0
+        uses: egor-tensin/setup-mingw@41b837e47d7f85214629d255b9c4bc3fcbe9fd63 # v3.0
         with:
           platform: ${{ matrix.architecture }}
           version: 12.2.0 # https://github.com/egor-tensin/setup-mingw/issues/14
@@ -40,24 +42,16 @@ jobs:
   msvc:
     strategy:
       matrix:
-        runs_on: [windows-2019, windows-2022]
         build_type: [Debug, Release]
         architecture: [Win32, x64]
         std_version: [default, latest]
 
-    runs-on: ${{ matrix.runs_on }}
+    runs-on: windows-2022
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - name: Set generator
-        id: generator
-        run: |
-          if [ "${{ matrix.runs_on }}" = "windows-2019" ]; then
-            echo "generator=Visual Studio 16 2019" >> $GITHUB_ENV
-          else
-            echo "generator=Visual Studio 17 2022" >> $GITHUB_ENV
-          fi
-        shell: bash
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Set extra CXX_FLAGS for latest std_version
         id: cxxflags
         run: |
@@ -68,11 +62,73 @@ jobs:
           fi
         shell: bash
       - name: Run CMake (Release)
-        run: cmake -S . -B build -G "$env:generator" -A ${{ matrix.architecture }} -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="$env:flags"
+        run: cmake -S . -B build -G "Visual Studio 17 2022" -A ${{ matrix.architecture }} -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="$env:flags"
         if: matrix.build_type == 'Release'
         shell: pwsh
       - name: Run CMake (Debug)
-        run: cmake -S . -B build -G "$env:generator" -A ${{ matrix.architecture }} -DJSON_BuildTests=On -DJSON_FastTests=ON -DCMAKE_CXX_FLAGS="$env:flags"
+        run: cmake -S . -B build -G "Visual Studio 17 2022" -A ${{ matrix.architecture }} -DJSON_BuildTests=On -DJSON_FastTests=ON -DCMAKE_CXX_FLAGS="$env:flags"
+        if: matrix.build_type == 'Debug'
+        shell: pwsh
+      - name: Build
+        run: cmake --build build --config ${{ matrix.build_type }} --parallel 10
+      - name: Test
+        run: cd build ; ctest -j 10 -C ${{ matrix.build_type }} --output-on-failure
+
+  # Visual Studio 2026 (v145 toolset) on the windows-2025 image. The "Visual Studio
+  # 18 2026" generator requires CMake 4.2+, so a recent CMake is fetched explicitly.
+  msvc-vs2026:
+    strategy:
+      matrix:
+        build_type: [Debug, Release]
+        architecture: [Win32, x64]
+        std_version: [default, latest]
+
+    runs-on: windows-2025
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
+      - name: Set extra CXX_FLAGS for latest std_version
+        # /wd5285 silences C5285 emitted by the bundled third-party doctest.h, which
+        # specializes std::tuple (newly diagnosed by the VS2026 v145 toolset)
+        run: |
+          if [ "${{ matrix.std_version }}" = "latest" ]; then
+            echo "flags=/permissive- /std:c++latest /utf-8 /W4 /WX /wd5285" >> $GITHUB_ENV
+          else
+            echo "flags=/W4 /WX /wd5285" >> $GITHUB_ENV
+          fi
+        shell: bash
+      - name: Run CMake (Release)
+        run: cmake -S . -B build -G "Visual Studio 18 2026" -A ${{ matrix.architecture }} -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="$env:flags"
+        if: matrix.build_type == 'Release'
+        shell: pwsh
+      - name: Run CMake (Debug)
+        run: cmake -S . -B build -G "Visual Studio 18 2026" -A ${{ matrix.architecture }} -DJSON_BuildTests=On -DJSON_FastTests=ON -DCMAKE_CXX_FLAGS="$env:flags"
+        if: matrix.build_type == 'Debug'
+        shell: pwsh
+      - name: Build
+        run: cmake --build build --config ${{ matrix.build_type }} --parallel 10
+      - name: Test
+        run: cd build ; ctest -j 10 -C ${{ matrix.build_type }} --output-on-failure
+
+  # Native ARM64 Windows runner with the MSVC ARM64 toolset. The windows-11-arm
+  # label is only available for public repositories.
+  msvc-arm64:
+    strategy:
+      matrix:
+        build_type: [Debug, Release]
+
+    runs-on: windows-11-arm
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Run CMake (Release)
+        run: cmake -S . -B build -G "Visual Studio 17 2022" -A ARM64 -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="/W4 /WX"
+        if: matrix.build_type == 'Release'
+        shell: pwsh
+      - name: Run CMake (Debug)
+        run: cmake -S . -B build -G "Visual Studio 17 2022" -A ARM64 -DJSON_BuildTests=On -DJSON_FastTests=ON -DCMAKE_CXX_FLAGS="/W4 /WX"
         if: matrix.build_type == 'Debug'
         shell: pwsh
       - name: Build
@@ -81,33 +137,67 @@ jobs:
         run: cd build ; ctest -j 10 -C ${{ matrix.build_type }} --output-on-failure
 
   clang:
-    runs-on: windows-2019
+    runs-on: windows-2022
     strategy:
       matrix:
-        version: [11, 12, 13, 14, 15]
+        version: [11.0.1, 12.0.1, 13.0.1, 14.0.6, 15.0.7, 16.0.6, 18.1.8, 19.1.7, 20.1.8]
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Install Clang
-        run: curl -fsSL -o LLVM${{ matrix.version }}.exe https://github.com/llvm/llvm-project/releases/download/llvmorg-${{ matrix.version }}.0.0/LLVM-${{ matrix.version }}.0.0-win64.exe ; 7z x LLVM${{ matrix.version }}.exe -y -o"C:/Program Files/LLVM"
+        run: curl -fsSL -o LLVM${{ matrix.version }}.exe https://github.com/llvm/llvm-project/releases/download/llvmorg-${{ matrix.version }}/LLVM-${{ matrix.version }}-win64.exe ; 7z x LLVM${{ matrix.version }}.exe -y -o"C:/Program Files/LLVM"
+      - name: Set up MinGW
+        uses: egor-tensin/setup-mingw@41b837e47d7f85214629d255b9c4bc3fcbe9fd63 # v3.0
+        with:
+          platform: x64
+          version: 12.2.0 # https://github.com/egor-tensin/setup-mingw/issues/14
       - name: Run CMake
-        run: cmake -S . -B build -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang++.exe" -G"MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug -DJSON_BuildTests=On
+        run: cmake -S . -B build ^
+             -DCMAKE_CXX_COMPILER="C:/Program Files/LLVM/bin/clang++.exe" ^
+             -DCMAKE_CXX_FLAGS="--target=x86_64-w64-mingw32 -stdlib=libstdc++ -pthread" ^
+             -DCMAKE_EXE_LINKER_FLAGS="-lwinpthread" ^
+             -G"MinGW Makefiles" ^
+             -DCMAKE_BUILD_TYPE=Debug ^
+             -DJSON_BuildTests=On
       - name: Build
         run: cmake --build build --parallel 10
       - name: Test
         run: cd build ; ctest -j 10 -C Debug --exclude-regex "test-unicode" --output-on-failure
 
   clang-cl-12:
-    runs-on: windows-2019
+    runs-on: windows-2022
     strategy:
       matrix:
         architecture: [Win32, x64]
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Run CMake
-        run: cmake -S . -B build -G "Visual Studio 16 2019" -A ${{ matrix.architecture }} -T ClangCL -DJSON_BuildTests=On
+        run: cmake -S . -B build -G "Visual Studio 17 2022" -A ${{ matrix.architecture }} -T ClangCL -DJSON_BuildTests=On
       - name: Build
         run: cmake --build build --config Debug --parallel 10
       - name: Test
         run: cd build ; ctest -j 10 -C Debug --exclude-regex "test-unicode" --output-on-failure
+
+  ci_module_cpp20:
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      # The module test uses `import std;`, which needs CMake's experimental
+      # import-std support. Its opt-in token is CMake-version-specific, so pin
+      # CMake to the version whose token is set in tests/module_cpp20/CMakeLists.txt.
+      - name: Get pinned CMake and ninja
+        uses: lukka/get-cmake@f5b8fbb4d77cec1acc5a5f9f0df4beffaf5d98d9 # v4.3.4
+        with:
+          cmakeVersion: 4.3.4
+      - name: Run CMake (Debug)
+        run: cmake -S . -B build -G "Visual Studio 17 2022" -DJSON_CI=ON -DCMAKE_CXX_FLAGS="/permissive- /std:c++latest /utf-8 /W4 /WX"
+      - name: Build
+        run: cmake --build build --config Debug --target ci_module_cpp20
+        

.reuse/dep5

@@ -4,7 +4,7 @@ Upstream-Contact: Niels Lohmann <mail@nlohmann.me>
 Source: https://github.com/nlohmann/json
 
 Files: *
-Copyright: 2013-2025 Niels Lohmann <https://nlohmann.me>
+Copyright: 2013-2026 Niels Lohmann <https://nlohmann.me>
 License: MIT
 
 Files: include/nlohmann/thirdparty/hedley.hpp

CMakeLists.txt

@@ -20,18 +20,29 @@ endif()
 ##
 ##
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake ${CMAKE_MODULE_PATH})
-include(ExternalProject)
-
-##
-## OPTIONS
-##
 
 if (POLICY CMP0077)
     # Allow CMake 3.13+ to override options when using FetchContent / add_subdirectory.
     cmake_policy(SET CMP0077 NEW)
 endif ()
 
-# VERSION_GREATER_EQUAL is not available in CMake 3.1
+# ---- C++ Modules Support (optional) ----
+option(NLOHMANN_JSON_BUILD_MODULES "Build C++ modules support" OFF)
+
+if(NLOHMANN_JSON_BUILD_MODULES)
+    if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.28)
+        message(STATUS "Building nlohmann.json C++ module")
+        add_subdirectory(src/modules)
+    else()
+        message(WARNING "Skipping nlohmann.json C++ module (requires CMake 3.28+, found ${CMAKE_VERSION})")
+    endif()
+endif()
+
+##
+## OPTIONS
+##
+
+# VERSION_GREATER_EQUAL is not available in older CMake (< 3.7)
 if(${MAIN_PROJECT} AND (${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION} VERSION_GREATER 3.13))
     set(JSON_BuildTests_INIT ON)
 else()
@@ -86,7 +97,7 @@ if (NOT JSON_ImplicitConversions)
 endif()
 
 if (JSON_DisableEnumSerialization)
-    message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=0)")
+    message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=1)")
 endif()
 
 if (JSON_LegacyDiscardedValueComparison)
@@ -152,7 +163,7 @@ if (MSVC)
 endif()
 
 # Install a pkg-config file, so other tools can find this.
-CONFIGURE_FILE(
+configure_file(
     "${CMAKE_CURRENT_SOURCE_DIR}/cmake/pkg-config.pc.in"
     "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc"
     @ONLY
@@ -162,9 +173,11 @@ CONFIGURE_FILE(
 ## TESTS
 ## create and configure the unit test target
 ##
-if (JSON_BuildTests)
+# Only build tests when JSON_BuildTests is set and testing has not been
+# disabled by a parent project via BUILD_TESTING (see the CTest module, which
+# also calls enable_testing()).
+if (JSON_BuildTests AND (NOT DEFINED BUILD_TESTING OR BUILD_TESTING))
     include(CTest)
-    enable_testing()
     add_subdirectory(tests)
 endif()
 
@@ -200,7 +213,7 @@ if(JSON_Install)
         install(
             FILES ${NLOHMANN_NATVIS_FILE}
             DESTINATION .
-    )
+        )
     endif()
     export(
         TARGETS ${NLOHMANN_JSON_TARGET_NAME}

FILES.md

@@ -9,6 +9,30 @@ This file describes the source for supporting files; that is, files that are not
 
 ## Continuous Integration
 
+### `.github/workflows`
+
+The [GitHub Actions](https://docs.github.com/en/actions) workflows that build, test, and analyze the library. Each file in this folder defines one workflow:
+
+- `ubuntu.yml`, `macos.yml`, `windows.yml` — build and run the test suite on Linux, macOS, and Windows.
+- `check_amalgamation.yml` — verify that the single-header amalgamation in `single_include` is up to date on pull requests.
+- `comment_check_amalgamation.yml` — comment on a pull request when the amalgamation check failed.
+- `cifuzz.yml` — run short fuzzing sessions via [OSS-Fuzz CIFuzz](https://google.github.io/oss-fuzz/getting-started/continuous-integration/) on pull requests.
+- `codeql-analysis.yml` — run [CodeQL](https://codeql.github.com) code scanning.
+- `flawfinder.yml` — run the [Flawfinder](https://dwheeler.com/flawfinder/) static analysis.
+- `semgrep.yml` — run [Semgrep](https://semgrep.dev) static analysis.
+- `scorecards.yml` — run the [OpenSSF Scorecard](https://securityscorecards.dev) supply-chain security checks.
+- `dependency-review.yml` — scan dependency changes in pull requests for known vulnerabilities.
+- `labeler.yml` — the "Pull Request Labeler" workflow (see `.github/labeler.yml`).
+- `stale.yml` — comment on and close stale issues and pull requests.
+- `publish_documentation.yml` — build and publish the documentation on every merge to the `develop` branch.
+
+Further documentation:
+
+- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
+
+> [!IMPORTANT]
+> The folder `.github/workflows` is predetermined by GitHub.
+
 ### `.cirrus.yml`
 
 Configuration file for the pipeline at [Cirrus CI](https://cirrus-ci.com/github/nlohmann/json).
@@ -123,7 +147,7 @@ Further documentation:
 > [!IMPORTANT]
 > The folder `.github/ISSUE_TEMPLATE` is predetermined by GitHub.
 
-### `.github/ISSUE_TEMPLATE/config.yaml`
+### `.github/ISSUE_TEMPLATE/config.yml`
 
 Issue template chooser configuration. The file is used to configure the dialog when a new issue is created.
 
@@ -132,7 +156,7 @@ Further documentation:
 - [Configuring issue templates for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
 
 > [!IMPORTANT]
-> The filename `.github/ISSUE_TEMPLATE/config.yaml` is predetermined by GitHub.
+> The filename `.github/ISSUE_TEMPLATE/config.yml` is predetermined by GitHub.
 
 ### `.github/labeler.yml`
 
@@ -165,7 +189,7 @@ Further documentation:
 - [Adding a security policy to your repository](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)
 
 > [!IMPORTANT]
-> The filename `.github/SECURITY.yml` is predetermined by GitHub.
+> The filename `.github/SECURITY.md` is predetermined by GitHub.
 
 > [!NOTE]
 > The file is part of the documentation and is included in `docs/mkdocs/docs/community/security_policy.md`.
@@ -234,6 +258,16 @@ make BUILD.bazel
 
 ### `meson.build`
 
+The build definition for the [Meson](https://mesonbuild.com) build system.
+
 ### `Package.swift`
 
-### `WORKSPACE.bazel`
+The package manifest for the [Swift Package Manager](https://www.swift.org/package-manager/).
+
+### `MODULE.bazel`
+
+The module definition for [Bazel](https://bazel.build)'s [Bzlmod](https://bazel.build/external/module) dependency system. It complements `BUILD.bazel` and replaces the previously used `WORKSPACE.bazel`.
+
+Further documentation:
+
+- [Bazel modules](https://bazel.build/external/module)

LICENSE.MIT

@@ -1,6 +1,6 @@
 MIT License 
 
-Copyright (c) 2013-2025 Niels Lohmann
+Copyright (c) 2013-2026 Niels Lohmann
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSES/CC0-1.0.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

Makefile

@@ -205,7 +205,7 @@ json.tar.xz:
 # We use `-X` to make the resulting ZIP file reproducible, see
 # <https://content.pivotal.io/blog/barriers-to-deterministic-reproducible-zip-files>.
 include.zip: BUILD.bazel
-	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) BUILD.bazel WORKSPACE.bazel meson.build LICENSE.MIT
+	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
 
 # Create the files for a release and add signatures and hashes.
 release: include.zip json.tar.xz
@@ -258,8 +258,8 @@ serve_header:
 ##########################################################################
 
 reuse:
-	pipx run reuse annotate --recursive single_include include -tjson --license MIT --copyright "Niels Lohmann <https://nlohmann.me>" --year "2013-2025" --merge-copyrights
-	pipx run reuse annotate $(TESTS_SRCS) -tjson_support --license MIT --copyright "Niels Lohmann <https://nlohmann.me>" --year "2013-2025" --merge-copyrights
+	pipx run reuse annotate --recursive single_include include -tjson --license MIT --copyright "Niels Lohmann <https://nlohmann.me>" --year "2013-2026" --merge-copyrights
+	pipx run reuse annotate $(TESTS_SRCS) -tjson_support --license MIT --copyright "Niels Lohmann <https://nlohmann.me>" --year "2013-2026" --merge-copyrights
 	pipx run reuse lint
 
 spdx:

README.md

@@ -11,7 +11,7 @@
 [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/json.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:json)
 [![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://wandbox.org/permlink/1mp10JbaANo6FUc7)
 [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://json.nlohmann.me)
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/nlohmann/json/master/LICENSE.MIT)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/nlohmann/json/develop/LICENSE.MIT)
 [![GitHub Releases](https://img.shields.io/github/release/nlohmann/json.svg)](https://github.com/nlohmann/json/releases)
 [![Packaging status](https://repology.org/badge/tiny-repos/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
 [![GitHub Downloads](https://img.shields.io/github/downloads/nlohmann/json/total)](https://github.com/nlohmann/json/releases)
@@ -19,6 +19,7 @@
 [![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/nlohmann/json.svg)](https://isitmaintained.com/project/nlohmann/json "Average time to resolve an issue")
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/289/badge)](https://bestpractices.coreinfrastructure.org/projects/289)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/nlohmann/json/badge)](https://scorecard.dev/viewer/?uri=github.com/nlohmann/json)
+[![Backup Status](https://app.cloudback.it/badge/nlohmann/json)](https://cloudback.it)
 [![GitHub Sponsors](https://img.shields.io/badge/GitHub-Sponsors-ff69b4)](https://github.com/sponsors/nlohmann)
 [![REUSE status](https://api.reuse.software/badge/github.com/nlohmann/json)](https://api.reuse.software/info/github.com/nlohmann/json)
 [![Discord](https://img.shields.io/discord/1003743314341793913)](https://discord.gg/6mrGXKvX7y)
@@ -69,7 +70,7 @@ Other aspects were not so important to us:
 
 - **Speed**. There are certainly [faster JSON libraries](https://github.com/miloyip/nativejson-benchmark#parsing-time) out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a `std::vector` or `std::map`, you are already set.
 
-See the [contribution guidelines](https://github.com/nlohmann/json/blob/master/.github/CONTRIBUTING.md#please-dont) for more information.
+See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#please-dont) for more information.
 
 ## Sponsors
 
@@ -79,6 +80,8 @@ You can sponsor this library at [GitHub Sponsors](https://github.com/sponsors/nl
 
 - [Martti Laine](https://github.com/codeclown)
 - [Paul Harrington](https://github.com/phrrngtn)
+- [Mercedes-Benz Group](https://github.com/mercedes-benz)
+- [Ryan McCaffery](https://github.com/mccaffers)
 
 ### :label: Named Sponsors
 
@@ -157,9 +160,22 @@ std::ifstream f("example.json");
 json data = json::parse(f);
 ```
 
+If using modules (enabled with `NLOHMANN_JSON_BUILD_MODULES`), this example becomes:
+```cpp
+import std;
+import nlohmann.json;
+
+using json = nlohmann::json;
+
+// ...
+
+std::ifstream f("example.json");
+json data = json::parse(f);
+```
+
 ### Creating `json` objects from JSON literals
 
-Assume you want to create hard-code this literal JSON value in a file, as a `json` object:
+Assume you want to hard-code this literal JSON value as a `json` object:
 
 ```json
 {
@@ -331,7 +347,7 @@ Note the difference between serialization and assignment:
 json j_string = "this is a string";
 
 // retrieve the string value
-auto cpp_string = j_string.template get<std::string>();
+auto cpp_string = j_string.get<std::string>();
 // retrieve the string value (alternative when a variable already exists)
 std::string cpp_string2;
 j_string.get_to(cpp_string2);
@@ -340,7 +356,7 @@ j_string.get_to(cpp_string2);
 std::string serialized_string = j_string.dump();
 
 // output of original string
-std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.template get<std::string>() << '\n';
+std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::string>() << '\n';
 // output of serialized value
 std::cout << j_string << " == " << serialized_string << std::endl;
 ```
@@ -413,6 +429,8 @@ struct MyIterator {
     using reference = const char&;
     using iterator_category = std::input_iterator_tag;
 
+    explicit MyIterator(MyContainer* tgt = nullptr) : target(tgt) {}
+
     MyIterator& operator++() {
         target->advance();
         return *this;
@@ -434,12 +452,12 @@ MyIterator begin(MyContainer& tgt) {
 }
 
 MyIterator end(const MyContainer&) {
-    return {};
+    return MyIterator{};
 }
 
 void foo() {
     MyContainer c;
-    json j = json::parse(c);
+    json j = json::parse(begin(c), end(c));
 }
 ```
 
@@ -513,7 +531,7 @@ for (auto& element : j) {
 }
 
 // getter/setter
-const auto tmp = j[0].template get<std::string>();
+const auto tmp = j[0].get<std::string>();
 j[1] = 42;
 bool foo = j.at(2);
 
@@ -720,7 +738,7 @@ You can switch off implicit conversions by defining `JSON_USE_IMPLICIT_CONVERSIO
 // strings
 std::string s1 = "Hello, world!";
 json js = s1;
-auto s2 = js.template get<std::string>();
+auto s2 = js.get<std::string>();
 // NOT RECOMMENDED
 std::string s3 = js;
 std::string s4;
@@ -729,7 +747,7 @@ s4 = js;
 // Booleans
 bool b1 = true;
 json jb = b1;
-auto b2 = jb.template get<bool>();
+auto b2 = jb.get<bool>();
 // NOT RECOMMENDED
 bool b3 = jb;
 bool b4;
@@ -738,11 +756,11 @@ b4 = jb;
 // numbers
 int i = 42;
 json jn = i;
-auto f = jn.template get<double>();
+auto f = jn.get<double>();
 // NOT RECOMMENDED
-double f2 = jb;
+double f2 = jn;
 double f3;
-f3 = jb;
+f3 = jn;
 
 // etc.
 ```
@@ -781,9 +799,9 @@ j["age"] = p.age;
 
 // convert from JSON: copy each value from the JSON object
 ns::person p {
-    j["name"].template get<std::string>(),
-    j["address"].template get<std::string>(),
-    j["age"].template get<int>()
+    j["name"].get<std::string>(),
+    j["address"].get<std::string>(),
+    j["age"].get<int>()
 };
 ```
 
@@ -800,7 +818,7 @@ std::cout << j << std::endl;
 // {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
 
 // conversion: json -> person
-auto p2 = j.template get<ns::person>();
+auto p2 = j.get<ns::person>();
 
 // that's it
 assert(p == p2);
@@ -827,21 +845,21 @@ namespace ns {
 ```
 
 That's all! When calling the `json` constructor with your type, your custom `to_json` method will be automatically called.
-Likewise, when calling `template get<your_type>()` or `get_to(your_type&)`, the `from_json` method will be called.
+Likewise, when calling `get<your_type>()` or `get_to(your_type&)`, the `from_json` method will be called.
 
 Some important things:
 
 - Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined).
 - Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [issue 1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
-- When using `template get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
+- When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
 - In function `from_json`, use function [`at()`](https://json.nlohmann.me/api/basic_json/at/) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
 - You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
 
 #### Simplify your life with macros
 
-If you just want to serialize/deserialize some structs, the `to_json`/`from_json` functions can be a lot of boilerplate. There are [**several macros**](https://json.nlohmann.me/features/arbitrary_types/#simplify-your-life-with-macros) to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object.
+If you just want to serialize/deserialize some structs, the `to_json`/`from_json` functions can be a lot of boilerplate. There are [**several macros**](https://json.nlohmann.me/api/macros/#serializationdeserialization-macros) to make your life easier as long as you want to use a JSON object as serialization.
 
-Which macro to choose depends on whether private member variables need to be accessed, a deserialization is needed, missing values should yield an error or should be replaced by default values, and if derived classes are used. See [this overview to choose the right one for your use case](https://json.nlohmann.me/api/macros/#serializationdeserialization-macros).
+Which macro to choose depends on whether private member variables need to be accessed, a deserialization is needed, missing values should yield an error or should be replaced by default values, and if derived classes are used. See [this overview to choose the right one for your use case](https://json.nlohmann.me/features/arbitrary_types/#simplify-your-life-with-macros).
 
 ##### Example usage of macros
 
@@ -853,6 +871,18 @@ namespace ns {
 }
 ```
 
+If you want to inherit the `person` struct and add a field to it, it can be done with:
+
+```cpp
+namespace ns {
+    struct person_derived : person {
+        std::string email;
+    };
+    
+    NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(person_derived, person, email)
+}
+```
+
 Here is another example with private members, where [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](https://json.nlohmann.me/api/macros/nlohmann_define_type_intrusive/) is needed:
 
 ```cpp
@@ -869,6 +899,24 @@ namespace ns {
 }
 ```
 
+Or in case if you use some naming convention that you do not want to expose to JSON:
+
+```cpp
+namespace ns {
+    class address {
+      private:
+        std::string m_street;
+        int m_housenumber;
+        int m_postcode;
+
+      public:
+        NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES(address, "street", m_street,
+                                                           "housenumber", m_housenumber,
+                                                           "postcode", m_postcode)
+    };
+}
+```
+
 #### How do I convert third-party types?
 
 This requires a bit more advanced technique. But first, let's see how this conversion mechanism works:
@@ -913,8 +961,8 @@ namespace nlohmann {
             if (j.is_null()) {
                 opt = boost::none;
             } else {
-                opt = j.template get<T>(); // same as above, but with
-                                           // adl_serializer<T>::from_json
+                opt = j.get<T>(); // same as above, but with
+                                  // adl_serializer<T>::from_json
             }
         }
     };
@@ -941,7 +989,7 @@ namespace nlohmann {
         // note: the return type is no longer 'void', and the method only takes
         // one argument
         static move_only_type from_json(const json& j) {
-            return {j.template get<int>()};
+            return {j.get<int>()};
         }
 
         // Here's the catch! You must provide a to_json method! Otherwise, you
@@ -1005,7 +1053,7 @@ struct bad_serializer
     static void to_json(const BasicJsonType& j, T& value) {
       // this calls BasicJsonType::json_serializer<T>::from_json(j, value)
       // if BasicJsonType::json_serializer == bad_serializer ... oops!
-      value = j.template get<T>(); // oops!
+      value = j.get<T>(); // oops!
     }
 };
 ```
@@ -1045,11 +1093,11 @@ assert(j == "stopped");
 
 // json string to enum
 json j3 = "running";
-assert(j3.template get<TaskState>() == TS_RUNNING);
+assert(j3.get<TaskState>() == TS_RUNNING);
 
 // undefined json value to enum (where the first map entry above is the default)
 json jPi = 3.14;
-assert(jPi.template get<TaskState>() == TS_INVALID);
+assert(jPi.get<TaskState>() == TS_INVALID);
 ```
 
 Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
@@ -1059,7 +1107,7 @@ Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
 
 Other Important points:
 
-- When using `template get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
+- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully. If you desire an exception in this circumstance use `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT()` which behaves identically except for throwing an exception on unrecognized values.
 - If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
 
 ### Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)
@@ -1141,7 +1189,7 @@ The library is used in multiple projects, applications, operating systems, etc.
 
 ## Supported compilers
 
-Though it's 2025 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:
+Though it's 2026 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:
 
 - GCC 4.8 - 14.2 (and possibly later)
 - Clang 3.4 - 21.0 (and possibly later)
@@ -1320,7 +1368,7 @@ pkg-config nlohmann_json --cflags
 
 The class is licensed under the [MIT License](https://opensource.org/licenses/MIT):
 
-Copyright &copy; 2013-2025 [Niels Lohmann](https://nlohmann.me)
+Copyright &copy; 2013-2026 [Niels Lohmann](https://nlohmann.me)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
@@ -1419,7 +1467,7 @@ I deeply appreciate the help of the following people.
 57. [Jared Grubb](https://github.com/jaredgrubb) supported the implementation of user-defined types.
 58. [EnricoBilla](https://github.com/EnricoBilla) noted a typo in an example.
 59. [Martin Hořeňovský](https://github.com/horenmar) found a way for a 2x speedup for the compilation time of the test suite.
-60. [ukhegg](https://github.com/ukhegg) found proposed an improvement for the examples section.
+60. [ukhegg](https://github.com/ukhegg) proposed an improvement for the examples section.
 61. [rswanson-ihi](https://github.com/rswanson-ihi) noted a typo in the README.
 62. [Mihai Stan](https://github.com/stanmihai4) fixed a bug in the comparison with `nullptr`s.
 63. [Tushar Maheshwari](https://github.com/tusharpm) added [cotire](https://github.com/sakra/cotire) support to speed up the compilation.
@@ -1793,7 +1841,7 @@ The library supports **Unicode input** as follows:
 This library does not support comments by default. It does so for three reasons:
 
 1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
-2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
+2. This was not an oversight: Douglas Crockford [wrote on this](https://news.ycombinator.com/item?id=3912149) in May 2012:
   
     > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.  I know that the lack of comments makes some people sad, but it shouldn't.
     >
@@ -1801,7 +1849,7 @@ This library does not support comments by default. It does so for three reasons:
   
 3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
 
-However, you can set set parameter `ignore_comments` to true in the `parse` function to ignore `//` or `/* */` comments. Comments will then be treated as whitespace.
+However, you can set parameter `ignore_comments` to true in the `parse` function to ignore `//` or `/* */` comments. Comments will then be treated as whitespace.
 
 ### Trailing commas
 
@@ -1851,7 +1899,7 @@ ctest --output-on-failure
 
 Note that during the `ctest` stage, several JSON test files are downloaded from an [external repository](https://github.com/nlohmann/json_test_data). If policies forbid downloading artifacts during testing, you can download the files yourself and pass the directory with the test files via `-DJSON_TestDataDirectory=path` to CMake. Then, no Internet connectivity is required. See [issue #2189](https://github.com/nlohmann/json/issues/2189) for more information.
 
-If the test suite is not found, several test suites will fail like this:
+If the testdata is not found, several test suites will fail like this:
 
 ```
 ===============================================================================
@@ -1869,6 +1917,8 @@ json/tests/src/make_test_data_available.hpp:23: FATAL ERROR: REQUIRE( utils::che
 
 In case you have downloaded the library rather than checked out the code via Git, test `cmake_fetch_content_configure` will fail. Please execute `ctest -LE git_required` to skip these tests. See [issue #2189](https://github.com/nlohmann/json/issues/2189) for more information.
 
+Some tests are requiring network to be properly execute. They are labeled as `git_required`. Please execute `ctest -LE git_required` to skip these tests. See [issue #4851](https://github.com/nlohmann/json/issues/4851) for more information.
+
 Some tests change the installed files and hence make the whole process not reproducible. Please execute `ctest -LE not_reproducible` to skip these tests. See [issue #2324](https://github.com/nlohmann/json/issues/2324) for more information. Furthermore, assertions must be switched off to ensure reproducible builds (see [discussion 4494](https://github.com/nlohmann/json/discussions/4494)).
 
 Note you need to call `cmake -LE "not_reproducible|git_required"` to exclude both labels. See [issue #2596](https://github.com/nlohmann/json/issues/2596) for more information.

cmake/ci.cmake

@@ -212,6 +212,21 @@ add_custom_target(ci_test_legacycomparison
     COMMENT "Compile and test with legacy discarded value comparison enabled"
 )
 
+###############################################################################
+# Enable brace-init copy semantics.
+###############################################################################
+
+add_custom_target(ci_test_brace_init_copy_semantics
+    COMMAND ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_FastTests=ON
+    -DCMAKE_CXX_FLAGS=-DJSON_BRACE_INIT_COPY_SEMANTICS=1
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_brace_init_copy_semantics
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_brace_init_copy_semantics
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_brace_init_copy_semantics && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test with brace-init copy semantics enabled"
+)
+
 ###############################################################################
 # Disable global UDLs.
 ###############################################################################
@@ -665,7 +680,8 @@ add_custom_target(ci_cuda_example
 
 add_custom_target(ci_module_cpp20
     COMMAND ${CMAKE_COMMAND}
-        -DCMAKE_BUILD_TYPE=Debug -GNinja
+        -DCMAKE_BUILD_TYPE=Debug -GNinja 
+        -DJSON_CI=ON -DNLOHMANN_JSON_BUILD_MODULES=ON -DJSON_Install=ON
         -S${PROJECT_SOURCE_DIR}/tests/module_cpp20 -B${PROJECT_BINARY_DIR}/ci_module_cpp20
     COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/ci_module_cpp20
 )
@@ -685,6 +701,48 @@ add_custom_target(ci_icpc
     COMMENT "Compile and test with ICPC"
 )
 
+add_custom_target(ci_icpx
+    COMMAND ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug -GNinja
+        -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx
+        -DJSON_BuildTests=ON -DJSON_FastTests=ON
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_icpx
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_icpx
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_icpx && ${CMAKE_CTEST_COMMAND} --parallel ${N} --exclude-regex "test-unicode" --output-on-failure
+    COMMENT "Compile and test with ICPX (Intel oneAPI DPC++/C++)"
+)
+
+###############################################################################
+# NVIDIA HPC SDK C++ Compiler
+###############################################################################
+
+# nvc++ defaults to a relaxed, non-IEEE floating-point model that flushes denormals
+# to zero and does not honor NaN ordering; -Kieee restores strict IEEE 754 behavior
+# (needed for the dtoa/grisu and NaN-comparison code paths).
+#
+# The following tests are excluded as they trigger known nvc++ 25.5 defects (not
+# library bugs); see https://github.com/nlohmann/json for tracking. Only the
+# affected language-standard variants are excluded so coverage is otherwise kept:
+#   - test-comparison_cpp20, test-comparison_legacy_cpp20
+#         miscompiles cross-type/<=> comparison (e.g. `-17 <= null`)
+#   - test-constructor1_cpp11
+#         std::initializer_list lifetime bug -> SIGSEGV
+#   - test-deserialization_cpp20
+#         mangles the UTF-8 u8"" string literal in the char8_t (C++20) section
+add_custom_target(ci_nvhpc
+    COMMAND ${CMAKE_COMMAND}
+        -DCMAKE_BUILD_TYPE=Debug -GNinja
+        -DCMAKE_C_COMPILER=nvc -DCMAKE_CXX_COMPILER=nvc++
+        -DCMAKE_CXX_FLAGS=-Kieee
+        -DJSON_BuildTests=ON -DJSON_FastTests=ON
+        -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_nvhpc
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_nvhpc
+    # the pipes are escaped so the surrounding shell passes them to ctest verbatim
+    # instead of treating them as shell pipe operators
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_nvhpc && ${CMAKE_CTEST_COMMAND} --parallel ${N} --exclude-regex "test-unicode\\|test-comparison_cpp20\\|test-comparison_legacy_cpp20\\|test-constructor1_cpp11\\|test-deserialization_cpp20" --output-on-failure
+    COMMENT "Compile and test with NVIDIA HPC SDK (nvc++)"
+)
+
 ###############################################################################
 # REUSE
 ###############################################################################

cmake/clang_flags.cmake

@@ -6,6 +6,7 @@
 # -Wno-padded                     We do not care about padding warnings.
 # -Wno-covered-switch-default     All switches list all cases and a default case.
 # -Wno-unsafe-buffer-usage        Otherwise Doctest would not compile.
+# -Wno-missing-noreturn           We found no way to silence this warning otherwise, see PR #4871
 
 set(CLANG_CXXFLAGS
     -Werror
@@ -17,4 +18,5 @@ set(CLANG_CXXFLAGS
     -Wno-padded
     -Wno-covered-switch-default
     -Wno-unsafe-buffer-usage
+    -Wno-missing-noreturn
 )

cmake/download_test_data.cmake

@@ -1,32 +1,48 @@
 set(JSON_TEST_DATA_URL     https://github.com/nlohmann/json_test_data)
 set(JSON_TEST_DATA_VERSION 3.1.0)
 
+include(ExternalProject)
+
 # if variable is set, use test data from given directory rather than downloading them
 if(JSON_TestDataDirectory)
     message(STATUS "Using test data in ${JSON_TestDataDirectory}.")
     add_custom_target(download_test_data)
     file(WRITE ${CMAKE_BINARY_DIR}/include/test_data.hpp "#define TEST_DATA_DIRECTORY \"${JSON_TestDataDirectory}\"\n")
 else()
-    find_package(Git)
+    # create a header with the path to the downloaded test data
+    file(WRITE ${CMAKE_BINARY_DIR}/include/test_data.hpp "#define TEST_DATA_DIRECTORY \"${CMAKE_BINARY_DIR}/test_files\"\n")
+
+    # download test data from the GitHub tag source archive
+    ExternalProject_Add(download_test_data_project
+        URL "${JSON_TEST_DATA_URL}/archive/refs/tags/v${JSON_TEST_DATA_VERSION}.zip"
+        SOURCE_DIR "${CMAKE_BINARY_DIR}/test_files"
+        CONFIGURE_COMMAND ""
+        BUILD_COMMAND ""
+        INSTALL_COMMAND ""
+        LOG_DOWNLOAD TRUE
+        DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+        EXCLUDE_FROM_ALL TRUE
+    )
+
     # target to download test data
     add_custom_target(download_test_data
-        COMMAND test -d json_test_data || ${GIT_EXECUTABLE} clone -c advice.detachedHead=false --branch v${JSON_TEST_DATA_VERSION} ${JSON_TEST_DATA_URL}.git --quiet --depth 1
-        COMMENT "Downloading test data from ${JSON_TEST_DATA_URL} (v${JSON_TEST_DATA_VERSION})"
-        WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+        DEPENDS download_test_data_project
     )
-    # create a header with the path to the downloaded test data
-    file(WRITE ${CMAKE_BINARY_DIR}/include/test_data.hpp "#define TEST_DATA_DIRECTORY \"${CMAKE_BINARY_DIR}/json_test_data\"\n")
 endif()
 
 # determine the operating system (for debug and support purposes)
 find_program(UNAME_COMMAND uname)
-find_program(VER_COMMAND ver)
 find_program(LSB_RELEASE_COMMAND lsb_release)
 find_program(SW_VERS_COMMAND sw_vers)
 set(OS_VERSION_STRINGS "${CMAKE_SYSTEM}")
-if (VER_COMMAND)
-    execute_process(COMMAND ${VER_COMMAND} OUTPUT_VARIABLE VER_COMMAND_RESULT OUTPUT_STRIP_TRAILING_WHITESPACE)
-    set(OS_VERSION_STRINGS "${OS_VERSION_STRINGS}; ${VER_COMMAND_RESULT}")
+if (CMAKE_HOST_WIN32)
+    # "ver" is a cmd.exe builtin rather than a standalone executable, so it
+    # cannot be located with find_program and must be invoked through cmd
+    execute_process(COMMAND cmd /c ver OUTPUT_VARIABLE VER_COMMAND_RESULT ERROR_QUIET)
+    string(STRIP "${VER_COMMAND_RESULT}" VER_COMMAND_RESULT)
+    if (VER_COMMAND_RESULT)
+        set(OS_VERSION_STRINGS "${OS_VERSION_STRINGS}; ${VER_COMMAND_RESULT}")
+    endif()
 endif()
 if (SW_VERS_COMMAND)
     execute_process(COMMAND ${SW_VERS_COMMAND} OUTPUT_VARIABLE SW_VERS_COMMAND_RESULT OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
@@ -56,10 +72,14 @@ string(REGEX REPLACE "[ ]*\n" "; " CXX_VERSION_RESULT "${CXX_VERSION_RESULT}")
 message(STATUS "Compiler: ${CXX_VERSION_RESULT}")
 
 # determine used C++ standard library (for debug and support purposes)
+if(CMAKE_CROSSCOMPILING)
+    set(LIBCPP_VERSION_OUTPUT_CACHED "could not be detected due to cross-compiling" CACHE STRING "Detected C++ standard library version")
+endif()
 if(NOT DEFINED LIBCPP_VERSION_OUTPUT_CACHED)
     try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
         "${CMAKE_BINARY_DIR}" SOURCES "${CMAKE_SOURCE_DIR}/cmake/detect_libcpp_version.cpp"
-        RUN_OUTPUT_VARIABLE LIBCPP_VERSION_OUTPUT COMPILE_OUTPUT_VARIABLE LIBCPP_VERSION_COMPILE_OUTPUT
+        RUN_OUTPUT_VARIABLE LIBCPP_VERSION_OUTPUT
+        COMPILE_OUTPUT_VARIABLE LIBCPP_VERSION_COMPILE_OUTPUT
     )
     if(NOT LIBCPP_VERSION_OUTPUT)
         set(LIBCPP_VERSION_OUTPUT "Unknown")

cmake/requirements/requirements-cppcheck.txt

@@ -1 +1 @@
-cppcheck==1.5.0
+cppcheck==1.5.1

cmake/requirements/requirements-reuse.txt

@@ -1 +1 @@
-reuse==5.0.2
+reuse==6.2.0

cmake/test.cmake

@@ -35,6 +35,8 @@ foreach(feature ${CMAKE_CXX_COMPILE_FEATURES})
         set(compiler_supports_cpp_20 TRUE)
     elseif (${feature} STREQUAL cxx_std_23)
         set(compiler_supports_cpp_23 TRUE)
+    elseif (${feature} STREQUAL cxx_std_26)
+        set(compiler_supports_cpp_26 TRUE)
     endif()
 endforeach()
 
@@ -92,7 +94,6 @@ function(json_test_set_test_options tests)
             target_compile_options(${test_interface} INTERFACE ${args_COMPILE_OPTIONS})
             target_link_libraries (${test_interface} INTERFACE ${args_LINK_LIBRARIES})
             target_link_options(${test_interface} INTERFACE ${args_LINK_OPTIONS})
-            #set_target_properties(${test_interface} PROPERTIES JSON_TEST_PROPERTIES "${args_TEST_PROPERTIES}")
             set_property(DIRECTORY PROPERTY
                 ${test_interface}_TEST_PROPERTIES "${args_TEST_PROPERTIES}"
             )
@@ -102,7 +103,6 @@ endfunction()
 
 # for internal use by _json_test_add_test()
 function(_json_test_apply_test_properties test_target properties_target)
-    #get_target_property(test_properties ${properties_target} JSON_TEST_PROPERTIES)
     get_property(test_properties DIRECTORY PROPERTY ${properties_target}_TEST_PROPERTIES)
     if(test_properties)
         set_tests_properties(${test_target} PROPERTIES ${test_properties})
@@ -213,10 +213,10 @@ function(json_test_add_test_for file)
 
     if("${args_NAME}" STREQUAL "")
         get_filename_component(file_basename ${file} NAME_WE)
-        string(REGEX REPLACE "unit-([^$]+)" "test-\\1" test_name ${file_basename})
+        string(REGEX REPLACE "unit-(.+)" "test-\\1" test_name ${file_basename})
     else()
         set(test_name ${args_NAME})
-        if(NOT test_name MATCHES "test-[^$]+")
+        if(NOT test_name MATCHES "test-.+")
             message(FATAL_ERROR "Test name must start with 'test-'.")
         endif()
     endif()

docs/README.md

@@ -2,12 +2,12 @@
 
 ## Generate documentation
 
-Note on documentation: The source files contain links to the online documentation at https://json.nlohmann.me. This URL
-contains the most recent documentation and should also be applicable to previous versions; documentation for deprecated
-functions is not removed, but marked deprecated.
+Note on documentation: The source files contain links to the online documentation at https://json.nlohmann.me.  
+This URL provides the most recent documentation and also applies to previous versions. Documentation for deprecated
+functions is not removed; instead, it is marked as deprecated.
 
-If you want to see the documentation for a specific tag or commit hash, you can generate it as follows (here for tag
-`v3.10.2`):
+If you want to view the documentation for a specific tag or commit hash, you can generate it locally as follows (example
+using tag `v3.10.2`):
 
 ```shell
 git clone https://github.com/nlohmann/json.git
@@ -16,5 +16,8 @@ git checkout v3.10.2
 make install_venv serve -C docs/mkdocs
 ```
 
-Open URL <http://127.0.0.1:8000/> in your browser. Replace from any URL from the source code `https://json.nlohmann.me`
-with `http://127.0.0.1:8000` to see the documentation for your tag or commit hash.
+Open <http://127.0.0.1:8000/> in your browser. Replace any URL in the source code that points to
+`https://json.nlohmann.me` with `http://127.0.0.1:8000` to view the documentation for the selected tag or commit hash.
+
+
+

docs/mkdocs/docs/api/adl_serializer/from_json.md

@@ -30,14 +30,15 @@ class (either explicitly or via the conversion operators).
 
 ## Return value
 
-Copy of the JSON value, converted to `ValueType`
+1. (none) -- the converted value is written to the output parameter `val`.
+2. the JSON value `j` converted to `TargetType`
 
 ## Examples
 
 ??? example "Example: (1) Default-constructible type"
 
     The example below shows how a `from_json` function can be implemented for a user-defined type. This function is
-    called by the `adl_serializer` when `template get<ns::person>()` is called.
+    called by the `adl_serializer` when `get<ns::person>()` is called.
         
     ```cpp
     --8<-- "examples/from_json__default_constructible.cpp"

docs/mkdocs/docs/api/basic_json/accept.md

@@ -101,6 +101,7 @@ A UTF-8 byte order mark is silently ignored.
 ## See also
 
 - [parse](parse.md) - deserialize from a compatible input
+- [sax_parse](sax_parse.md) - parse input using the SAX interface
 - [operator>>](../operator_gtgt.md) - deserialize from stream
 
 ## Version history
@@ -108,7 +109,7 @@ A UTF-8 byte order mark is silently ignored.
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
-- Added `ignore_trailing_commas` in version 3.12.1.
+- Added `ignore_trailing_commas` in version 3.12.x.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/array.md

@@ -54,6 +54,7 @@ This function is only needed to express two edge cases that cannot be realized w
 
 - [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
 - [`object`](object.md) - create a JSON object value from an initializer list
+- [Creating JSON values](../../features/creating_values.md) - the article on creating JSON values
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/at.md

@@ -82,6 +82,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
       key of an object which cannot be found. See the example below.
     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
       not be resolved. See the example below.
+    - Throws [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) if an array index in the passed
+      JSON pointer `ptr` exceeds the range of `size_type` (e.g., on 32-bit platforms).
 
 ## Complexity
 

docs/mkdocs/docs/api/basic_json/boolean_t.md

@@ -9,7 +9,7 @@ The type used to store JSON booleans.
 [RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two
 literals `#!json true` and `#!json false`.
 
-To store objects in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.
+To store boolean values in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.
 
 ## Notes
 

docs/mkdocs/docs/api/basic_json/contains.md

@@ -48,11 +48,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 1. The function does not throw exceptions.
 2. The function does not throw exceptions.
-3. The function can throw the following exceptions:
-    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with
-      `0`.
-    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a
-      number.
+3. The function does not throw exceptions.
 
 ## Complexity
 
@@ -111,6 +107,11 @@ Logarithmic in the size of the JSON object.
     --8<-- "examples/contains__json_pointer.output"
     ```
 
+## See also
+
+- [find](find.md) find a value in an object
+- [count](count.md) returns the number of occurrences of a key
+
 ## Version history
 
 1. Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/count.md

@@ -72,6 +72,11 @@ This method always returns `0` when executed on a JSON type that is not an objec
     --8<-- "examples/count__keytype.c++17.output"
     ```
 
+## See also
+
+- [find](find.md) find a value in an object
+- [contains](contains.md) checks whether a key exists
+
 ## Version history
 
 1. Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/crbegin.md

@@ -10,7 +10,7 @@ Returns an iterator to the reverse-beginning; that is, the last element.
 
 ## Return value
 
-reverse iterator to the first element
+reverse iterator to the last element
 
 ## Exception safety
 

docs/mkdocs/docs/api/basic_json/crend.md

@@ -25,7 +25,7 @@ Constant.
 
 ??? example
 
-    The following code shows an example for `eend()`.
+    The following code shows an example for `crend()`.
     
     ```cpp
     --8<-- "examples/crend.cpp"

docs/mkdocs/docs/api/basic_json/diff.md

@@ -56,6 +56,9 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
 ## See also
 
 - [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
+- [patch](patch.md) applies a JSON Patch
+- [patch_inplace](patch_inplace.md) applies a JSON Patch in place
+- [merge_patch](merge_patch.md) applies a JSON Merge Patch
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/dump.md

@@ -26,9 +26,9 @@ and `ensure_ascii` parameters.
 
 `error_handler` (in)
 :   how to react on decoding errors; there are three possible values (see [`error_handler_t`](error_handler_t.md):
-    `strict` (throws and exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
-    with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all bytes are copied to the output
-    unchanged)).
+    `strict` (throws an exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
+    with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the
+    output unchanged, and invalid bytes are dropped)).
     
 ## Return value
 
@@ -71,6 +71,12 @@ Binary values are serialized as an object containing two keys:
     --8<-- "examples/dump.output"
     ```
 
+## See also
+
+- [to_string](to_string.md) returns a string representation of a JSON value
+- [operator<<](../operator_ltlt.md) serialize to stream
+- [Serialization](../../features/serialization.md) - the serialization article
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/emplace.md

@@ -29,6 +29,10 @@ iterators (including the `end()` iterator) and all references to the elements ar
 a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and
 a `#!cpp bool` denoting whether the insertion took place.
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+
 ## Exceptions
 
 Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON
@@ -56,6 +60,12 @@ Logarithmic in the size of the container, O(log(`size()`)).
     --8<-- "examples/emplace.output"
     ```
 
+## See also
+
+- [emplace_back](emplace_back.md) add a value to an array
+- [insert](insert.md) add values to an array/object
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values
+
 ## Version history
 
 - Since version 2.0.8.

docs/mkdocs/docs/api/basic_json/emplace_back.md

@@ -58,6 +58,7 @@ Amortized constant.
 
 - [operator+=](operator+=.md) add a value to an array/object
 - [push_back](push_back.md) add a value to an array/object
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/erase.md

@@ -101,7 +101,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 4. See 3.
 5. The function can throw the following exceptions:
     - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
-      JSON object; example: `"cannot use erase() with null"`
+      JSON array; example: `"cannot use erase() with null"`
     - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
       `"array index 17 is out of range"`
 
@@ -202,6 +202,12 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/erase__size_type.output"
     ```
 
+## See also
+
+- [clear](clear.md) clears the contents
+- [insert](insert.md) add values to an array/object
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values
+
 ## Version history
 
 1. Added in version 1.0.0. Added support for binary types in version 3.8.0.

docs/mkdocs/docs/api/basic_json/error_handler_t.md

@@ -18,7 +18,7 @@ replace
 :   replace invalid UTF-8 sequences with U+FFFD (� REPLACEMENT CHARACTER)
 
 ignore
-:   ignore invalid UTF-8 sequences; all bytes are copied to the output unchanged
+:   ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/find.md

@@ -78,6 +78,7 @@ This method always returns `end()` when executed on a JSON type that is not an o
 
 ## See also
 
+- [count](count.md) returns the number of occurrences of a key
 - [contains](contains.md) checks whether a key exists
 
 ## Version history

docs/mkdocs/docs/api/basic_json/format_as.md

@@ -0,0 +1,95 @@
+# format_as(basic_json)
+
+```cpp
+template <typename BasicJsonType>
+std::string format_as(const BasicJsonType& j);
+```
+
+This function implements the [`format_as`](https://fmt.dev/latest/api/#formatting-user-defined-types)
+customization point used by the [{fmt}](https://github.com/fmtlib/fmt) library (fmtlib). It has no
+dependency on any `fmt` header and no effect at all unless a caller's translation unit also includes
+`fmt` and calls `fmt::format`/`fmt::print` on a JSON value.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](index.md)
+
+## Return value
+
+string containing the serialization of the JSON value (same as [`dump()`](dump.md))
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded
+
+## Complexity
+
+Linear.
+
+## Possible implementation
+
+```cpp
+template <typename BasicJsonType>
+std::string format_as(const BasicJsonType& j)
+{
+    return j.dump();
+}
+```
+
+## Notes
+
+!!! warning "Version-dependent effect on fmt"
+
+    `fmt` only picks up a `format_as` overload that returns a `std::string` in fmt **10.0.0 through
+    11.0.2**. Starting with fmt **11.1.0**, `fmt` restricts automatic `format_as` pickup to overloads that
+    return an arithmetic type, so this function has no effect there (it is simply unused, not a compile
+    error).
+
+    If you use fmt \>= 11.1.0, or want the same pretty-print spec support that
+    [`std::formatter<basic_json>`](std_formatter.md) has (`#!cpp "{:#}"`, a width to set the indent such
+    as `#!cpp "{:2}"`/`#!cpp "{:#2}"`, and fill-and-align to pick the indent character such as
+    `#!cpp "{:.>#}"`), define your own `fmt::formatter` specialization mirroring the same logic:
+
+    ```cpp
+    --8<-- "../../../tests/fmt_formatter/project/main.cpp:formatter_recipe"
+    ```
+
+    This recipe isn't shipped by the library itself, since doing so would make `fmt` a build dependency
+    (see the FAQ entry on
+    [using JSON values with `std::format` or `fmt`](../../home/faq.md#using-json-values-with-stdformat-or-fmt)
+    for more background) — but it *is* compiled and exercised against a real, current `fmt` release as
+    part of the library's own test suite (`tests/fmt_formatter`, via CMake `FetchContent`), so it's kept in
+    sync with `std::formatter<basic_json>` and verified to actually work, not just illustrative.
+
+## Examples
+
+??? example
+
+    The following code shows how the library's `format_as()` function integrates with `fmt::format`,
+    allowing argument-dependent lookup.
+
+    ```cpp
+    --8<-- "examples/format_as.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/format_as.output"
+    ```
+
+## See also
+
+- [dump](dump.md)
+- [std::formatter<basic_json>](std_formatter.md) - the `std::format` (C++20) equivalent
+- [Serialization](../../features/serialization.md) - the serialization article
+
+## Version history
+
+- Added in version 3.12.x.

docs/mkdocs/docs/api/basic_json/from_bjdata.md

@@ -67,6 +67,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - 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
+- Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the size of an optimized container
+  or n-dimensional array cannot be represented by `std::size_t`
 
 ## Complexity
 
@@ -88,6 +90,14 @@ Linear in the size of the input.
     --8<-- "examples/from_bjdata.output"
     ```
 
+## See also
+
+- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
+- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
+- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
+- [from_bson](from_bson.md) create a JSON value from an input in BSON format
+- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/from_bson.md

@@ -62,8 +62,12 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
-Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
-encountered.
+- Throws [`parse_error.110`](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of the input was not reached when `strict` was set to true
+- Throws [`parse_error.112`](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs (e.g., an
+  invalid string or byte array length)
+- Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
+  encountered
 
 ## Complexity
 
@@ -92,6 +96,7 @@ Linear in the size of the input.
 - [from_cbor](from_cbor.md) for the related CBOR format
 - [from_msgpack](from_msgpack.md) for the related MessagePack format
 - [from_ubjson](from_ubjson.md) for the related UBJSON format
+- [from_bjdata](from_bjdata.md) for the related BJData format
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/from_cbor.md

@@ -96,6 +96,14 @@ Linear in the size of the input.
     --8<-- "examples/from_cbor.output"
     ```
 
+## See also
+
+- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
+- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
+- [from_bson](from_bson.md) create a JSON value from an input in BSON format
+- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
+- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+
 ## Version history
 
 - Added in version 2.0.9.

docs/mkdocs/docs/api/basic_json/from_msgpack.md

@@ -89,6 +89,14 @@ Linear in the size of the input.
     --8<-- "examples/from_msgpack.output"
     ```
 
+## See also
+
+- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
+- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
+- [from_bson](from_bson.md) create a JSON value from an input in BSON format
+- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
+- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+
 ## Version history
 
 - Added in version 2.0.9.
@@ -101,7 +109,7 @@ Linear in the size of the input.
     - Overload (2) replaces calls to `from_msgpack` with a pointer and a length as first two parameters, which has been
       deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
       `#!cpp from_msgpack(ptr, len, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
-    - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
+    - Overload (2) replaces calls to `from_msgpack` with a pair of iterators as their first parameter, which has been
       deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
       `#!cpp from_msgpack({ptr, ptr+len}, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
 

docs/mkdocs/docs/api/basic_json/from_ubjson.md

@@ -65,8 +65,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
   the end of the 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 
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
   successfully
+- Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the size of an optimized container
+  or n-dimensional array cannot be represented by `std::size_t`
 
 ## Complexity
 
@@ -88,6 +90,14 @@ Linear in the size of the input.
     --8<-- "examples/from_ubjson.output"
     ```
 
+## See also
+
+- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
+- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
+- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
+- [from_bson](from_bson.md) create a JSON value from an input in BSON format
+- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+
 ## Version history
 
 - Added in version 3.1.0.

docs/mkdocs/docs/api/basic_json/get.md

@@ -88,12 +88,32 @@ constexpr const PointerType get_ptr() const noexcept;
 
 Depends on what `json_serializer<ValueType>` `from_json()` method throws
 
+## Complexity
+
+Depends on the `json_serializer<ValueType>::from_json()` implementation for overloads (1) and (2); constant for
+overload (3).
+
 ## Notes
 
-!!! danger "Undefined behavior"
+!!! danger "Undefined behavior for pointers"
 
     Writing data to the pointee (overload 3) of the result yields an undefined state.
 
+!!! danger "Undefined behavior for numeric conversions"
+
+    Conversions between numeric types are performed by the corresponding
+    `from_json()` implementation using the target C++ type. When converting
+    between numeric types, the library does not check whether the source
+    value is representable by the target type.
+    
+    If the source value is outside the range of the target type, the behavior
+    is the same as the corresponding C++ conversion. In particular, converting
+    a floating-point value to an integer type that cannot represent the value
+    results in undefined behavior.
+
+    See [Number conversion](../../features/types/number_handling.md#number-conversion)
+    for more information.
+
 ## Examples
 
 ??? example
@@ -129,6 +149,14 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
     --8<-- "examples/get__PointerType.output"
     ```
 
+## See also
+
+- [get_to](get_to.md) convert and write into a passed value
+- [get_ptr](get_ptr.md) get a pointer to the stored value
+- [get_ref](get_ref.md) get a reference to the stored value
+- [operator ValueType](operator_ValueType.md) get a value via implicit conversion
+- [Converting values](../../features/conversions.md) - the type conversions article
+
 ## Version history
 
 1. Since version 2.1.0.

docs/mkdocs/docs/api/basic_json/get_binary.md

@@ -40,6 +40,11 @@ Constant.
     --8<-- "examples/get_binary.output"
     ```
 
+## See also
+
+- [get](get.md) get a value (explicit conversion)
+- [get_ref](get_ref.md) get a reference to the stored value
+
 ## Version history
 
 - Added in version 3.8.0.

docs/mkdocs/docs/api/basic_json/get_to.md

@@ -34,6 +34,10 @@ the input parameter, allowing chaining calls
 
 Depends on what `json_serializer<ValueType>` `from_json()` method throws
 
+## Complexity
+
+Depends on the `json_serializer<ValueType>::from_json()` implementation.
+
 ## Examples
 
 ??? example
@@ -53,6 +57,13 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
     --8<-- "examples/get_to.output"
     ```
 
+## See also
+
+- [get](get.md) get a value (explicit conversion)
+- [get_ref](get_ref.md) get a reference to the stored value
+- [get_ptr](get_ptr.md) get a pointer to the stored value
+- [Converting values](../../features/conversions.md) - the type conversions article
+
 ## Version history
 
 - Since version 3.3.0.

docs/mkdocs/docs/api/basic_json/index.md

@@ -301,6 +301,7 @@ Access to the JSON value
 - [**operator<<(std::ostream&)**](../operator_ltlt.md) - serialize to stream
 - [**operator>>(std::istream&)**](../operator_gtgt.md) - deserialize from stream
 - [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
+- [**format_as**](format_as.md) - user-defined `format_as` function for JSON values (fmt support)
 
 ## Literals
 
@@ -308,6 +309,7 @@ Access to the JSON value
 
 ## Helper classes
 
+- [**std::formatter&lt;basic_json&gt;**](std_formatter.md) - make JSON values formattable with `std::format`
 - [**std::hash&lt;basic_json&gt;**](std_hash.md) - return a hash value for a JSON object
 - [**std::swap&lt;basic_json&gt;**](std_swap.md) - exchanges the values of two JSON objects
 

docs/mkdocs/docs/api/basic_json/insert.md

@@ -96,8 +96,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 5. The function can throw the following exceptions:
     - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
       objects; example: `"cannot use insert() with string"`
-    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
-      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if `first` or `last`
+      do not point to an object; example: `"iterators first and last must point to objects"`
     - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
       do not belong to the same JSON value; example: `"iterators do not fit"`
 
@@ -181,6 +181,13 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/insert__range_object.output"
     ```
 
+## See also
+
+- [emplace](emplace.md) add a value to an object
+- [emplace_back](emplace_back.md) add a value to an array
+- [push_back](push_back.md) add a value to an array/object
+- [update](update.md) merges objects
+
 ## Version history
 
 1. Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/invalid_iterator.md

@@ -66,6 +66,7 @@ classDiagram
 
 ## See also
 
+- [`exception`](exception.md) for the base class of all exceptions thrown by the library
 - [List of iterator errors](../../home/exceptions.md#iterator-errors)
 - [`parse_error`](parse_error.md) for exceptions indicating a parse error
 - [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type

docs/mkdocs/docs/api/basic_json/is_discarded.md

@@ -45,11 +45,13 @@ Constant.
 
     When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
     then it is removed when it is part of a structured value. For instance, if the second value of an array is discarded,
-    instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level
-    value is discarded, the return value of the `parse` call is discarded.
+    instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. If the top-level value
+    itself is discarded by the callback, the `parse` call returns a `#!json null` value.
 
-This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
-during parsing, but will be removed when inside a structured value or replaced by null in other cases.
+After a successful parse, this function always returns `#!cpp false`: discarded values can only occur during parsing and
+are either removed when inside a structured value or replaced by `#!json null` at the top level. The exception is parsing
+with `allow_exceptions` set to `#!cpp false`: a parse error then yields a discarded value for which this function returns
+`#!cpp true` (see [`parse`](parse.md)).
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/is_number.md

@@ -9,7 +9,7 @@ unsigned) and floating-point values.
     
 ## Return value
 
-`#!cpp true` if type is number (regardless whether integer, unsigned integer, or floating-type), `#!cpp false` otherwise.
+`#!cpp true` if type is number (regardless whether integer, unsigned integer, or floating-point), `#!cpp false` otherwise.
 
 ## Exception safety
 

docs/mkdocs/docs/api/basic_json/items.md

@@ -84,6 +84,11 @@ When iterating over an array, `key()` will return the index of the element as st
     --8<-- "examples/items.output"
     ```
 
+## See also
+
+- [begin](begin.md) returns an iterator to the first element
+- [end](end.md) returns an iterator to one past the last element
+
 ## Version history
 
 - Added `iterator_wrapper` in version 3.0.0.

docs/mkdocs/docs/api/basic_json/meta.md

@@ -13,7 +13,7 @@ JSON object holding version information
 
 | key         | description                                                                                                                                                                                                                                                                    |
 |-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). |
+| `compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). On HP aCC compilers, `compiler` is instead the plain string `hp`. |
 | `copyright` | The copyright line for the library as string.                                                                                                                                                                                                                                  |
 | `name`      | The name of the library as string.                                                                                                                                                                                                                                             |
 | `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.                                                                                                                                                                             |

docs/mkdocs/docs/api/basic_json/number_integer_t.md

@@ -32,7 +32,6 @@ With the default values for `NumberIntegerType` (`std::int64_t`), the default va
 - The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an
   interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++
   integer literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
-- Not-a-number (NaN) values will be serialized to `null`.
 
 #### Limits
 

docs/mkdocs/docs/api/basic_json/number_unsigned_t.md

@@ -32,7 +32,6 @@ With the default values for `NumberUnsignedType` (`std::uint64_t`), the default
 - The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an
   interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++
   integer  literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
-- Not-a-number (NaN) values will be serialized to `null`.
 
 #### Limits
 
@@ -45,7 +44,7 @@ when used in a constructor. During deserialization, too large or small integer n
 as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
 > interoperable in the sense that implementations will agree exactly on their numeric values.
 
 As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported

docs/mkdocs/docs/api/basic_json/object.md

@@ -57,6 +57,7 @@ the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`
 
 - [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
 - [`array`](array.md) - create a JSON array value from an initializer list
+- [Creating JSON values](../../features/creating_values.md) - the article on creating JSON values
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/operator+=.md

@@ -50,9 +50,12 @@ invalidates all iterators and all references.
 
 ## Exceptions
 
-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"`
+1. 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. 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"`
+3. 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
 

docs/mkdocs/docs/api/basic_json/operator=.md

@@ -5,7 +5,8 @@ basic_json& operator=(basic_json other) noexcept (
     std::is_nothrow_move_constructible<value_t>::value &&
     std::is_nothrow_move_assignable<value_t>::value &&
     std::is_nothrow_move_constructible<json_value>::value &&
-    std::is_nothrow_move_assignable<json_value>::value
+    std::is_nothrow_move_assignable<json_value>::value &&
+    std::is_nothrow_move_assignable<json_base_class_t>::value
 );
 ```
 
@@ -17,6 +18,10 @@ constructor, destructor, and the `swap()` member function.
 `other` (in)
 :   value to copy from
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown while copying `other`, there are no changes to `#!cpp *this`.
+
 ## Complexity
 
 Linear.
@@ -38,6 +43,11 @@ Linear.
     --8<-- "examples/basic_json__copyassignment.output"
     ```
 
+## See also
+
+- [basic_json](basic_json.md) create a JSON value
+- [swap](swap.md) exchanges the contents of two JSON values
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -83,6 +83,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
       in the passed JSON pointer `ptr` for the const version.
     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
       not be resolved.
+    - Throws [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) if an array index in the passed
+      JSON pointer `ptr` exceeds the range of `size_type` (e.g., on 32-bit platforms).
 
 ## Complexity
 
@@ -95,7 +97,10 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 !!! danger "Undefined behavior and runtime assertions"
 
-    1. If the element with key `idx` does not exist, the behavior is undefined.
+    The following cases apply to the **const** overloads; the non-const overloads instead insert the missing element
+    (see the notes below).
+
+    1. If the element at index `idx` does not exist, the behavior is undefined.
     2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a
        [runtime assertion](../../features/assertions.md)**!
 

docs/mkdocs/docs/api/basic_json/operator_ValueType.md

@@ -75,6 +75,11 @@ Linear in the size of the JSON value.
     --8<-- "examples/operator__ValueType.output"
     ```
 
+## See also
+
+- [get](get.md) get a value (explicit conversion)
+- [Converting values](../../features/conversions.md) - the type conversions article
+
 ## Version history
 
 - Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/operator_eq.md

@@ -20,7 +20,7 @@ class basic_json {
 ```
 
 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
+    - Two JSON values are equal if (1) neither value is discarded, and (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.
 
@@ -79,13 +79,13 @@ Linear.
     }
     ```
     
-    Or you can self-defined operator equal function like this:
+    Or you can define your own equality function like this:
     
     ```cpp
     bool my_equal(const_reference lhs, const_reference rhs)
     {
-        const auto lhs_type lhs.type();
-        const auto rhs_type rhs.type();
+        const auto lhs_type = lhs.type();
+        const auto rhs_type = rhs.type();
         if (lhs_type == rhs_type)
         {
             switch(lhs_type)
@@ -162,6 +162,11 @@ Linear.
     --8<-- "examples/operator__equal__nullptr_t.output"
     ```
 
+## See also
+
+- [operator!=](operator_ne.md) compare for inequality
+- [operator<=>](operator_spaceship.md) comparison: 3-way (C++20)
+
 ## Version history
 
 1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.

docs/mkdocs/docs/api/basic_json/operator_ge.md

@@ -35,7 +35,7 @@ bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 
 ## Return value
 
-whether `lhs` is less than or equal to `rhs`
+whether `lhs` is greater than or equal to `rhs`
 
 ## Exception safety
 

docs/mkdocs/docs/api/basic_json/other_error.md

@@ -66,6 +66,7 @@ classDiagram
 
 ## See also
 
+- [`exception`](exception.md) for the base class of all exceptions thrown by the library
 - [List of other errors](../../home/exceptions.md#further-exceptions)
 - [`parse_error`](parse_error.md) for exceptions indicating a parse error
 - [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators

docs/mkdocs/docs/api/basic_json/out_of_range.md

@@ -67,6 +67,7 @@ classDiagram
 
 ## See also
 
+- [`exception`](exception.md) for the base class of all exceptions thrown by the library
 - [List of out-of-range errors](../../home/exceptions.md#out-of-range)
 - [`parse_error`](parse_error.md) for exceptions indicating a parse error
 - [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators

docs/mkdocs/docs/api/basic_json/parse.md

@@ -81,9 +81,6 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
   empty input like a null `FILE*` or `char*` pointer.
-- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if `to_unicode` fails or surrogate
-  error.
-- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if `to_unicode` fails.
 
 ## Complexity
 
@@ -95,6 +92,9 @@ super-linear complexity.
 
 A UTF-8 byte order mark is silently ignored.
 
+Invalid Unicode escapes and unpaired surrogates in the input are reported as
+[`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) with a detailed message.
+
 ## Examples
 
 ??? example "Parsing from a character array"
@@ -183,7 +183,7 @@ A UTF-8 byte order mark is silently ignored.
 
 ??? example "Effect of `allow_exceptions` parameter"
 
-    The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.
+    The example below demonstrates the effect of the `allow_exceptions` parameter in the `parse()` function.
 
     ```cpp
     --8<-- "examples/parse__allow_exceptions.cpp"
@@ -226,6 +226,7 @@ A UTF-8 byte order mark is silently ignored.
 ## See also
 
 - [accept](accept.md) - check if the input is valid JSON
+- [sax_parse](sax_parse.md) - parse input using the SAX interface
 - [operator>>](../operator_gtgt.md) - deserialize from stream
 
 ## Version history
@@ -234,7 +235,7 @@ A UTF-8 byte order mark is silently ignored.
 - Overload for contiguous containers (1) added in version 2.0.3.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
-- Added `ignore_trailing_commas` in version 3.12.1.
+- Added `ignore_trailing_commas` in version 3.12.x.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/parse_error.md

@@ -75,6 +75,7 @@ or the end of file. This also holds true when reading a byte vector for binary f
 
 ## See also
 
+- [`exception`](exception.md) for the base class of all exceptions thrown by the library
 - [List of parse errors](../../home/exceptions.md#parse-errors)
 - [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
 - [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type

docs/mkdocs/docs/api/basic_json/parse_event_t.md

@@ -24,6 +24,11 @@ The parser callback distinguishes the following events:
 
 ![Example when certain parse events are triggered](../../images/callback_events.png)
 
+## See also
+
+- [parser_callback_t](parser_callback_t.md) callback function type for the parser
+- [parse](parse.md) deserialize from a compatible input
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/parser_callback_t.md

@@ -68,6 +68,11 @@ the latter case, it is either skipped completely or replaced by an empty discard
     --8<-- "examples/parse__string__parser_callback_t.output"
     ```
 
+## See also
+
+- [parse](parse.md) deserialize from a compatible input
+- [parse_event_t](parse_event_t.md) enumeration of parser events
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/patch.md

@@ -32,7 +32,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
 - Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
   ("add", "remove", "move")
-- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
+- Throws [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) if an "add" operation's target
+  location has a parent that is neither an object nor an array.
+- Throws [`other_error.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
   unsuccessful.
 
 ## Complexity
@@ -71,3 +73,5 @@ is thrown. In any case, the original value is not changed: the patch is applied
 ## Version history
 
 - Added in version 2.0.0.
+- Added [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's
+  target location has a non-object/non-array parent in version 3.12.x.

docs/mkdocs/docs/api/basic_json/patch_inplace.md

@@ -1,7 +1,7 @@
 # <small>nlohmann::basic_json::</small>patch_inplace
 
 ```cpp
-void patch_inplace(const basic_json& json_patch) const;
+void patch_inplace(const basic_json& json_patch);
 ```
 
 [JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
@@ -28,7 +28,9 @@ No guarantees, value may be corrupted by an unsuccessful patch operation.
   could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
 - Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
   ("add", "remove", "move")
-- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
+- Throws [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) if an "add" operation's target
+  location has a parent that is neither an object nor an array.
+- Throws [`other_error.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
   unsuccessful.
 
 ## Complexity
@@ -62,9 +64,11 @@ function throws an exception.
 
 - [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
 - [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
-- [patch](patch.md) applies a JSON Merge Patch
+- [patch](patch.md) applies a JSON Patch
 - [merge_patch](merge_patch.md) applies a JSON Merge Patch
 
 ## Version history
 
 - Added in version 3.11.0.
+- Added [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's
+  target location has a non-object/non-array parent in version 3.12.x.

docs/mkdocs/docs/api/basic_json/push_back.md

@@ -46,9 +46,12 @@ invalidates all iterators and all references.
 
 ## Exceptions
 
-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"`
+1. 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. 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"`
+3. 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
 
@@ -112,6 +115,7 @@ All functions can throw the following exception:
 
 - [emplace_back](emplace_back.md) add a value to an array
 - [operator+=](operator+=.md) add a value to an array/object
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/rbegin.md

@@ -11,7 +11,7 @@ Returns an iterator to the reverse-beginning; that is, the last element.
 
 ## Return value
 
-reverse iterator to the first element
+reverse iterator to the last element
 
 ## Exception safety
 

docs/mkdocs/docs/api/basic_json/rend.md

@@ -26,7 +26,7 @@ Constant.
 
 ??? example
 
-    The following code shows an example for `eend()`.
+    The following code shows an example for `rend()`.
     
     ```cpp
     --8<-- "examples/rend.cpp"

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -43,18 +43,19 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
       iterators.
 
 `IteratorType`
-:   Description
+:   a compatible iterator type for overload (2); a pair of character iterators whose `value_type` is an integral type
+    with a size of 1, 2, or 4 bytes (interpreted respectively as UTF-8, UTF-16, and UTF-32)
 
 `SAX`
-:   Description
+:   a class fulfilling the SAX event listener interface; see [`json_sax`](../json_sax/index.md)
 
 ## Parameters
 
 `i` (in)
-:   Input to parse from.
+:   Input to parse from
 
 `sax` (in)
-:   SAX event listener
+:   SAX event listener (must not be null)
 
 `format` (in)
 :    the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default), see
@@ -83,6 +84,13 @@ return value of the last processed SAX event
 
 ## Exception safety
 
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Exceptions
+
+- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
+  empty input like a null `FILE*` or `char*` pointer.
+
 ## Complexity
 
 Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX
@@ -109,11 +117,16 @@ A UTF-8 byte order mark is silently ignored.
     --8<-- "examples/sax_parse.output"
     ```
 
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [accept](accept.md) - check if the input is valid JSON
+
 ## Version history
 
 - Added in version 3.2.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
-- Added `ignore_trailing_commas` in version 3.12.1.
+- Added `ignore_trailing_commas` in version 3.12.x.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/std_formatter.md

@@ -0,0 +1,57 @@
+# <small>std::</small>formatter<nlohmann::basic_json\>
+
+```cpp
+namespace std {
+    template <>
+    struct formatter<nlohmann::basic_json, char>;
+}
+```
+
+Specialization to make JSON values formattable with [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format)
+(and the other members of C++20's `<format>` header, such as `std::format_to`).
+
+A subset of the [standard format spec grammar](https://en.cppreference.com/w/cpp/utility/format/spec) is
+supported, repurposed for JSON pretty-printing; any other spec component (sign, the `0` flag, precision,
+`L`, a dynamic width such as `#!cpp "{:{}}"`, or a trailing type character) throws
+[`std::format_error`](https://en.cppreference.com/w/cpp/utility/format/format_error):
+
+- `#!cpp "{}"` serializes the value the same way as [`dump()`](dump.md) (compact, no whitespace).
+- `#!cpp "{:#}"` ("alternate form") serializes the value the same way as `#!cpp dump(4)` (pretty-printed
+  with an indent of 4).
+- A width, with or without `#!cpp "#"` (e.g. `#!cpp "{:2}"` or `#!cpp "{:#2}"`), serializes the value the
+  same way as `#!cpp dump(width)` — a width on its own implies pretty-printing, since an indent size has
+  no meaning for compact output.
+- `fill-and-align` (e.g. `#!cpp "{:.>#}"` or `#!cpp "{:.>3}"`) picks a custom indent character, the same
+  way as `#!cpp dump(indent, indent_char)`. The alignment direction itself (`#!cpp '<'`, `#!cpp '>'`,
+  `#!cpp '^'`) has no separate meaning for JSON values — only the fill character before it is used, and
+  any of the three directions is accepted.
+
+This specialization is only available for `#!cpp char`-based JSON values and only if the standard library
+provides `<format>`, controlled by the [`JSON_HAS_STD_FORMAT`](../macros/json_has_std_format.md) macro.
+
+## Examples
+
+??? example
+
+    The example shows how to format JSON values with `std::format`.
+
+    ```cpp
+    --8<-- "examples/std_formatter.c++20.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/std_formatter.c++20.output"
+    ```
+
+## See also
+
+- [dump](dump.md) - serialization
+- [operator<<(std::ostream&)](../operator_ltlt.md) - serialize to stream
+- [format_as](format_as.md) - customization point used by `fmt::format` (fmtlib)
+- [Serialization](../../features/serialization.md) - the serialization article
+
+## Version history
+
+- Added in version 3.12.x.

docs/mkdocs/docs/api/basic_json/std_swap.md

@@ -16,6 +16,14 @@ Exchanges the values of two JSON objects.
 `j2` (in, out)
 :   value to be replaced by `j1`
 
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
 ## Possible implementation
 
 ```cpp

docs/mkdocs/docs/api/basic_json/string_t.md

@@ -9,7 +9,7 @@ The type used to store JSON strings.
 [RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON strings as follows:
 > A string is a sequence of zero or more Unicode characters.
 
-To store objects in C++, a type is defined by the template parameter described below. Unicode values are split by the
+To store strings in C++, a type is defined by the template parameter described below. Unicode values are split by the
 JSON class into byte-sized characters during deserialization.
 
 ## Template parameters

docs/mkdocs/docs/api/basic_json/swap.md

@@ -2,10 +2,20 @@
 
 ```cpp
 // (1)
-void swap(reference other) noexcept;
+void swap(reference other) noexcept (
+    std::is_nothrow_move_constructible<value_t>::value &&
+    std::is_nothrow_move_assignable<value_t>::value &&
+    std::is_nothrow_move_constructible<json_value>::value &&
+    std::is_nothrow_move_assignable<json_value>::value
+);
 
 // (2)
-void swap(reference left, reference right) noexcept;
+friend void swap(reference left, reference right) noexcept (
+    std::is_nothrow_move_constructible<value_t>::value &&
+    std::is_nothrow_move_assignable<value_t>::value &&
+    std::is_nothrow_move_constructible<json_value>::value &&
+    std::is_nothrow_move_assignable<json_value>::value
+);
 
 // (3)
 void swap(array_t& other);
@@ -56,15 +66,15 @@ void swap(typename binary_t::container_type& other);
 1. No-throw guarantee: this function never throws exceptions.
 2. No-throw guarantee: this function never throws exceptions.
 3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
-   arrays; example: `"cannot use swap() with boolean"`
+   arrays; example: `"cannot use swap(array_t&) with boolean"`
 4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
-   objects; example: `"cannot use swap() with boolean"`
+   objects; example: `"cannot use swap(object_t&) with boolean"`
 5. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
-   strings; example: `"cannot use swap() with boolean"`
+   strings; example: `"cannot use swap(string_t&) with boolean"`
 6. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
-   binaries; example: `"cannot use swap() with boolean"`
+   binaries; example: `"cannot use swap(binary_t&) with boolean"`
 7. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
-   binaries; example: `"cannot use swap() with boolean"`
+   binaries; example: `"cannot use swap(binary_t::container_type&) with boolean"`
 
 ## Complexity
 
@@ -128,7 +138,7 @@ Constant.
     --8<-- "examples/swap__string_t.output"
     ```
 
-??? example "Example: Swap string (6)"
+??? example "Example: Swap binary (6)"
 
     The example below shows how binary values can be swapped with `swap()`.
     
@@ -145,6 +155,8 @@ Constant.
 ## See also
 
 - [std::swap<basic_json\>](std_swap.md)
+- [operator=](operator=.md) copy assignment
+- [basic_json](basic_json.md) create a JSON value
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/to_bjdata.md

@@ -72,6 +72,14 @@ Linear in the size of the JSON value `j`.
     --8<-- "examples/to_bjdata.output"
     ```
 
+## See also
+
+- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
+- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
+- [to_bson](to_bson.md) create a BSON serialization of a JSON value
+- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/to_bson.md

@@ -34,6 +34,13 @@ The exact mapping and its limitations are described on a [dedicated page](../../
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+
+- Throws [`type_error.317`](../../home/exceptions.md#jsonexceptiontype_error317) if the top-level type of the JSON value
+  is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
+- Throws [`out_of_range.409`](../../home/exceptions.md#jsonexceptionout_of_range409) if a key in the JSON object contains
+  a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
+
 ## Complexity
 
 Linear in the size of the JSON value `j`.
@@ -54,6 +61,14 @@ Linear in the size of the JSON value `j`.
     --8<-- "examples/to_bson.output"
     ```
 
+## See also
+
+- [from_bson](from_bson.md) create a JSON value from an input in BSON format
+- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
+- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
+- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
+- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
+
 ## Version history
 
 - Added in version 3.4.0.

docs/mkdocs/docs/api/basic_json/to_cbor.md

@@ -55,6 +55,14 @@ Linear in the size of the JSON value `j`.
     --8<-- "examples/to_cbor.output"
     ```
 
+## See also
+
+- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
+- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
+- [to_bson](to_bson.md) create a BSON serialization of a JSON value
+- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
+- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
+
 ## Version history
 
 - Added in version 2.0.9.

docs/mkdocs/docs/api/basic_json/to_msgpack.md

@@ -54,6 +54,14 @@ Linear in the size of the JSON value `j`.
     --8<-- "examples/to_msgpack.output"
     ```
 
+## See also
+
+- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
+- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
+- [to_bson](to_bson.md) create a BSON serialization of a JSON value
+- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
+- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
+
 ## Version history
 
 - Added in version 2.0.9.

docs/mkdocs/docs/api/basic_json/to_string.md

@@ -59,6 +59,7 @@ std::string to_string(const BasicJsonType& j)
 ## See also
 
 - [dump](dump.md)
+- [Serialization](../../features/serialization.md) - the serialization article
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/to_ubjson.md

@@ -65,6 +65,14 @@ Linear in the size of the JSON value `j`.
     --8<-- "examples/to_ubjson.output"
     ```
 
+## See also
+
+- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
+- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
+- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
+- [to_bson](to_bson.md) create a BSON serialization of a JSON value
+- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
+
 ## Version history
 
 - Added in version 3.1.0.

docs/mkdocs/docs/api/basic_json/type_error.md

@@ -67,6 +67,7 @@ classDiagram
 
 ## See also
 
+- [`exception`](exception.md) for the base class of all exceptions thrown by the library
 - [List of type errors](../../home/exceptions.md#type-errors)
 - [`parse_error`](parse_error.md) for exceptions indicating a parse error
 - [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators

docs/mkdocs/docs/api/basic_json/unflatten.md

@@ -25,6 +25,10 @@ The function can throw the following exceptions:
 
 - Throws [`type_error.314`](../../home/exceptions.md#jsonexceptiontype_error314) if value is not an object
 - Throws [`type_error.315`](../../home/exceptions.md#jsonexceptiontype_error315) if object values are not primitive
+- Throws [`type_error.313`](../../home/exceptions.md#jsonexceptiontype_error313) if a key (JSON pointer) leads to a
+  conflicting nesting; example: `"invalid value to unflatten"`
+- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in a key is not a
+  number; example: `"array index 'one' is not a number"`
 
 ## Complexity