Merge branch 'develop' into claude/fix-issue-2649-738aba

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

.github/workflows/check_api_docs.yml

@@ -1,81 +0,0 @@
-name: "Check API documentation"
-
-on:
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  check_api_docs:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout pull request
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      - name: Install clang
-        # Used only as a subprocess for `clang++ -E -v` system-include-path discovery in
-        # extract_api.py; it does not need to version-match the pinned libclang pip wheel
-        # below, which does the actual AST parsing. Do not "fix" this to be version-matched.
-        run: sudo apt-get update && sudo apt-get install -y clang
-
-      - name: Install Python dependencies
-        run: pip install -r tools/api_checker/requirements.txt
-
-      - name: Extract API and regenerate the committed surface file
-        run: |
-          python3 tools/api_checker/extract_api.py \
-            --header include/nlohmann/json.hpp \
-            --include include \
-            --output /tmp/api_snapshot.json \
-            --surface-output tools/api_checker/api_surface.json
-
-      - name: "Check API documentation (Phase 1: advisory)"
-        # Surfaces missing/broken @sa links without failing the job while the backlog from the
-        # initial AST-based rollout is burned down. See tools/api_checker/POLICY.md and the PR
-        # that introduced this workflow for the two-phase rollout plan.
-        continue-on-error: true
-        run: |
-          python3 tools/api_checker/check_docs.py \
-            --snapshot /tmp/api_snapshot.json
-
-      - name: Check macro documentation (advisory only)
-        # Cross-checks docs/mkdocs/docs/api/macros/ pages against #define sites. Only checks the
-        # documented-macro-still-exists direction; never blocks CI. See POLICY.md.
-        run: python3 tools/api_checker/check_macros.py
-
-      - name: Check for uncommitted API surface changes
-        id: diff
-        run: |
-          mkdir -p ${{ github.workspace }}/patch
-          git diff --patch --no-color -- tools/api_checker/api_surface.json > ${{ github.workspace }}/patch/api_surface.patch
-          if [ -s ${{ github.workspace }}/patch/api_surface.patch ]; then
-            echo "tools/api_checker/api_surface.json is out of date. Diff:"
-            cat ${{ github.workspace }}/patch/api_surface.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 api_surface.patch`
-      # instead of installing libclang locally.
-      - name: Upload patch
-        if: steps.diff.outputs.has_diff == 'true'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: api-surface-patch
-          path: patch/api_surface.patch
-
-      - name: Fail if API surface file is not up to date
-        # Unlike the doc-backlog check above, this is purely mechanical regeneration with no
-        # backlog to phase in -- blocking from the start, matching check_amalgamation.yml's
-        # precedent. Contributors who add/remove/rename public API must regenerate and commit
-        # tools/api_checker/api_surface.json as part of their PR.
-        if: steps.diff.outputs.has_diff == 'true'
-        run: exit 1

.gitignore

@@ -3,7 +3,6 @@
 *.gcno
 *.gcda
 .DS_Store
-__pycache__/
 
 /.idea
 /cmake-build-*
@@ -44,9 +43,5 @@ venv
 
 nlohmann_json.spdx
 
-# api_checker: ephemeral, location/doc-status-sensitive working file (not the committed
-# release-tracking artifact -- see tools/api_checker/api_surface.json for that)
-/tools/api_checker/api_snapshot.json
-
 # Bazel-related
 MODULE.bazel.lock

README.md

@@ -106,7 +106,7 @@ Thanks everyone!
 
 :books: If you want to **learn more** about how to use the library, check out the rest of the [**README**](#examples), have a look at [**code examples**](https://github.com/nlohmann/json/tree/develop/docs/mkdocs/docs/examples), or browse through the [**help pages**](https://json.nlohmann.me).
 
-:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below. The public API surface is derived mechanically and checked for documentation coverage by the tooling in [`tools/api_checker/`](tools/api_checker/), whose [POLICY.md](tools/api_checker/POLICY.md) defines what counts as public API and what stability is guaranteed.
+:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below.
 
 :bug: If you found a **bug**, please check the [**FAQ**](https://json.nlohmann.me/home/faq/) if it is a known issue or the result of a design decision. Please also have a look at the [**issue list**](https://github.com/nlohmann/json/issues) before you [**create a new issue**](https://github.com/nlohmann/json/issues/new/choose). Please provide as much information as possible to help us understand and reproduce your issue.
 

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

@@ -272,6 +272,15 @@ basic_json(basic_json&& other) noexcept;
         When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
         function, yielding the JSON `#!json null` value.
 
+- Overload 4:
+
+    !!! info "Implicit conversion"
+
+        The conversion is implicit unless [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md)
+        is defined to `0` and `BasicJsonType::string_t` differs from `string_t`. In that case, the constructor is
+        `explicit`, so a JSON value with a different string type is no longer silently converted, for example when it is
+        passed to a function taking `#!cpp const json&`. Write `#!cpp json(other)` or `#!cpp other.get<json>()` instead.
+
 - Overload 7:
 
     !!! info "Preconditions"
@@ -420,9 +429,8 @@ basic_json(basic_json&& other) noexcept;
 1. Since version 1.0.0.
 2. Since version 1.0.0.
 3. Since version 2.1.0.
-4. Since version 3.2.0. Also initializes the position reported by
-   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
-   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0.
+4. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
+   version 3.13.0.
 5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/bjdata_version_t.md

@@ -1,38 +0,0 @@
-# <small>nlohmann::basic_json::</small>bjdata_version_t
-
-```cpp
-enum class bjdata_version_t
-{
-    draft2,
-    draft3,
-};
-```
-
-This enumeration is used in the [`to_bjdata`](to_bjdata.md) function to choose which draft version of
-the BJData specification to encode ND-array extensions for:
-
-draft2
-:   encode using the BJData Draft 2 ND-array format
-
-draft3
-:   encode using the BJData Draft 3 ND-array format
-
-## Examples
-
-??? example
-
-    The example shows how `bjdata_version_t` selects the BJData draft used by `to_bjdata`.
-
-    ```cpp
-    --8<-- "examples/bjdata_version_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/bjdata_version_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.12.0.

docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md

@@ -18,7 +18,8 @@ ignore
 :   ignore tags
 
 store
-:   store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.
+:   store tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are
+    read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored.
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/initializer_list_t.md

@@ -1,32 +0,0 @@
-# <small>nlohmann::basic_json::</small>initializer_list_t
-
-```cpp
-using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
-```
-
-The type used for the initializer-list [constructor](basic_json.md) (overload 5) and for functions
-such as [`operator=`](operator=.md) that accept a braced-init-list of JSON values. Each element wraps a
-`basic_json` value or something convertible to one, deferring the decision of whether the list should be
-parsed as a JSON array or a JSON object to the constructor itself.
-
-See the [constructor](basic_json.md) documentation for how `initializer_list_t` values are interpreted.
-
-## Examples
-
-??? example
-
-    The example shows how an `initializer_list_t` is used to construct a JSON value.
-
-    ```cpp
-    --8<-- "examples/initializer_list_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/initializer_list_t.output"
-    ```
-
-## Version history
-
-- Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/json_sax_t.md

@@ -1,31 +0,0 @@
-# <small>nlohmann::basic_json::</small>json_sax_t
-
-```cpp
-using json_sax_t = json_sax<basic_json>;
-```
-
-The [`json_sax`](../json_sax/index.md) interface bound to this `basic_json` specialization, i.e. with
-`BasicJsonType` fixed to `basic_json`. Used as the SAX interface type by [`sax_parse`](sax_parse.md) and
-other SAX-based parsing functions.
-
-See [`nlohmann::json_sax`](../json_sax/index.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `json_sax_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.2.0.

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

@@ -51,5 +51,3 @@ Linear.
 ## Version history
 
 - Added in version 1.0.0.
-- The `noexcept` specification was extended to also depend on
-  [`json_base_class_t`](json_base_class_t.md)'s move-assignment in version 3.11.3.

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

@@ -85,8 +85,3 @@ Linear in the size of the JSON value.
 - Since version 1.0.0.
 - Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
   in version 3.9.0.
-- The exclusion of `std::any` from this conversion became conditional on
-  [`JSON_HAS_STATIC_RTTI`](../macros/json_has_static_rtti.md) in version 3.11.3.
-- `std::optional<T>` excluded from this conversion in version 3.13.0; use
-  [`get<std::optional<T>>()`](get.md)/[`get_to()`](get_to.md) instead (see
-  [Converting values](../../features/conversions.md)).

docs/mkdocs/docs/api/byte_container_with_subtype/container_type.md

@@ -1,32 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>container_type
-
-```cpp
-using container_type = BinaryType;
-```
-
-The type of the underlying binary container, forwarded from the `BinaryType` template parameter that
-`byte_container_with_subtype` is instantiated with. `byte_container_with_subtype` publicly inherits from
-`container_type`.
-
-See [`basic_json::binary_t`](../basic_json/binary_t.md) for the type typically used to instantiate
-`BinaryType`.
-
-## Examples
-
-??? example
-
-    The example shows the type `container_type`.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__container_type.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__container_type.output"
-    ```
-
-## Version history
-
-- Since version 3.8.0.

docs/mkdocs/docs/api/byte_container_with_subtype/operator_eq.md

@@ -1,45 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>operator==
-
-```cpp
-bool operator==(const byte_container_with_subtype& rhs) const;
-```
-
-Compares two `byte_container_with_subtype` values for equality by comparing the underlying binary
-container, the subtype, and whether a subtype is set.
-
-## Parameters
-
-`rhs` (in)
-:   value to compare `*this` against
-
-## Return value
-
-whether `*this` and `rhs` are equal
-
-## Exception safety
-
-No-throw guarantee: this function never throws exceptions.
-
-## Complexity
-
-Linear in the size of the underlying binary container.
-
-## Examples
-
-??? example
-
-    The example demonstrates comparing `byte_container_with_subtype` values.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__operator_eq.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__operator_eq.output"
-    ```
-
-## Version history
-
-- Since version 3.8.0.

docs/mkdocs/docs/api/byte_container_with_subtype/operator_ne.md

@@ -1,45 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>operator!=
-
-```cpp
-bool operator!=(const byte_container_with_subtype& rhs) const;
-```
-
-Compares two `byte_container_with_subtype` values for inequality. Implemented as the negation of
-[`operator==`](operator_eq.md).
-
-## Parameters
-
-`rhs` (in)
-:   value to compare `*this` against
-
-## Return value
-
-whether `*this` and `rhs` are not equal
-
-## Exception safety
-
-No-throw guarantee: this function never throws exceptions.
-
-## Complexity
-
-Linear in the size of the underlying binary container.
-
-## Examples
-
-??? example
-
-    The example demonstrates comparing `byte_container_with_subtype` values.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__operator_ne.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__operator_ne.output"
-    ```
-
-## Version history
-
-- Since version 3.8.0.

docs/mkdocs/docs/api/byte_container_with_subtype/subtype_type.md

@@ -1,28 +0,0 @@
-# <small>nlohmann::byte_container_with_subtype::</small>subtype_type
-
-```cpp
-using subtype_type = std::uint64_t;
-```
-
-The type used to store the optional binary subtype tag. See [`subtype`](subtype.md) and
-[`set_subtype`](set_subtype.md).
-
-## Examples
-
-??? example
-
-    The example shows the type `subtype_type`.
-
-    ```cpp
-    --8<-- "examples/byte_container_with_subtype__subtype_type.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/byte_container_with_subtype__subtype_type.output"
-    ```
-
-## Version history
-
-- Since version 3.8.0.

docs/mkdocs/docs/api/json_sax/binary_t.md

@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>binary_t
-
-```cpp
-using binary_t = typename BasicJsonType::binary_t;
-```
-
-The type used by the [`binary`](binary.md) callback for JSON binary values, forwarded from the
-`BasicJsonType` template parameter.
-
-See [`basic_json::binary_t`](../basic_json/binary_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `binary_t` and its relation to `basic_json::binary_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__binary_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__binary_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.8.0.

docs/mkdocs/docs/api/json_sax/json_sax.md

@@ -1,33 +0,0 @@
-# <small>nlohmann::json_sax::</small>json_sax
-
-```cpp
-// (1)
-json_sax() = default;
-
-// (2)
-json_sax(const json_sax&) = default;
-
-// (3)
-json_sax(json_sax&&) noexcept = default;
-```
-
-1. Default constructor.
-2. Copy constructor.
-3. Move constructor.
-
-`json_sax` is a pure abstract base class with no data members of its own, so all three constructors are
-defaulted and only exist to make derived SAX consumers explicitly copyable/movable.
-
-## Exception safety
-
-No-throw guarantee: none of these constructors throw exceptions.
-
-## Complexity
-
-Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
-- Added in version 3.2.0.

docs/mkdocs/docs/api/json_sax/number_float_t.md

@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>number_float_t
-
-```cpp
-using number_float_t = typename BasicJsonType::number_float_t;
-```
-
-The type used by the [`number_float`](number_float.md) callback for JSON floating-point numbers,
-forwarded from the `BasicJsonType` template parameter.
-
-See [`basic_json::number_float_t`](../basic_json/number_float_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `number_float_t` and its relation to `basic_json::number_float_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__number_float_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__number_float_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.2.0.

docs/mkdocs/docs/api/json_sax/number_integer_t.md

@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>number_integer_t
-
-```cpp
-using number_integer_t = typename BasicJsonType::number_integer_t;
-```
-
-The type used by the [`number_integer`](number_integer.md) callback for JSON integer numbers, forwarded
-from the `BasicJsonType` template parameter.
-
-See [`basic_json::number_integer_t`](../basic_json/number_integer_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `number_integer_t` and its relation to `basic_json::number_integer_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__number_integer_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__number_integer_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.2.0.

docs/mkdocs/docs/api/json_sax/number_unsigned_t.md

@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>number_unsigned_t
-
-```cpp
-using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
-```
-
-The type used by the [`number_unsigned`](number_unsigned.md) callback for JSON unsigned integer numbers,
-forwarded from the `BasicJsonType` template parameter.
-
-See [`basic_json::number_unsigned_t`](../basic_json/number_unsigned_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `number_unsigned_t` and its relation to `basic_json::number_unsigned_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__number_unsigned_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__number_unsigned_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.2.0.

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

@@ -1,29 +0,0 @@
-# <small>nlohmann::json_sax::</small>operator=
-
-```cpp
-// (1)
-json_sax& operator=(const json_sax&) = default;
-
-// (2)
-json_sax& operator=(json_sax&&) noexcept = default;
-```
-
-1. Copy assignment operator.
-2. Move assignment operator.
-
-`json_sax` is a pure abstract base class with no data members of its own, so both assignment operators
-are defaulted and only exist to make derived SAX consumers explicitly copy-/move-assignable.
-
-## Exception safety
-
-No-throw guarantee: neither operator throws exceptions.
-
-## Complexity
-
-Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
-- Added in version 3.2.0.

docs/mkdocs/docs/api/json_sax/string_t.md

@@ -1,30 +0,0 @@
-# <small>nlohmann::json_sax::</small>string_t
-
-```cpp
-using string_t = typename BasicJsonType::string_t;
-```
-
-The type used by the [`string`](string.md) and [`key`](key.md) callbacks for JSON strings and object
-keys, forwarded from the `BasicJsonType` template parameter.
-
-See [`basic_json::string_t`](../basic_json/string_t.md) for more information.
-
-## Examples
-
-??? example
-
-    The example shows the type `string_t` and its relation to `basic_json::string_t`.
-
-    ```cpp
-    --8<-- "examples/json_sax__string_t.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/json_sax__string_t.output"
-    ```
-
-## Version history
-
-- Added in version 3.2.0.

docs/mkdocs/docs/api/json_sax/~json_sax.md

@@ -1,22 +0,0 @@
-# <small>nlohmann::json_sax::</small>~json_sax
-
-```cpp
-virtual ~json_sax() = default;
-```
-
-Destructor. Virtual to allow proper destruction of derived SAX consumer classes through a
-pointer/reference to `json_sax`.
-
-## Exception safety
-
-No-throw guarantee: this destructor never throws exceptions.
-
-## Complexity
-
-Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
-- Added in version 3.2.0.

docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md

@@ -5,7 +5,9 @@
 ```
 
 When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The
-value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md).
+value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md) and the
+[converting constructor](../basic_json/basic_json.md) from a `basic_json` specialization with a different string
+type (overload 4).
 
 ## Default definition
 
@@ -57,6 +59,25 @@ By default, implicit conversions are enabled.
     auto s = j.get<std::string>();
     ```
 
+??? example "Conversion between `basic_json` specializations"
+
+    A `basic_json` specialization with a different string type is also no longer converted implicitly when
+    `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`:
+
+    ```cpp
+    using wjson = nlohmann::basic_json<std::map, std::vector, std::wstring>;
+
+    void load(const nlohmann::json& j);
+
+    wjson wj = /* ... */;
+    load(wj);                            // error: no implicit conversion
+    load(nlohmann::json(wj));            // OK: explicit conversion
+    load(wj.get<nlohmann::json>());      // OK: explicit conversion
+    ```
+
+    Specializations that share the same string type, such as `json` and `ordered_json`, remain implicitly
+    convertible.
+
 ## See also
 
 - [**operator ValueType**](../basic_json/operator_ValueType.md) - get a value (implicit)
@@ -66,3 +87,4 @@ By default, implicit conversions are enabled.
 ## Version history
 
 - Added in version 3.9.0.
+- Also affects the conversion between `basic_json` specializations with different string types since version 3.13.0.

docs/mkdocs/docs/api/ordered_json.md

@@ -8,16 +8,16 @@ This type preserves the insertion order of object keys.
 
 ## Iterator invalidation
 
-The type is based on [`ordered_map`](ordered_map/index.md) which in turn uses a `std::vector` to store object elements.
+The type is based on [`ordered_map`](ordered_map.md) which in turn uses a `std::vector` to store object elements.
 Therefore, adding object elements can yield a reallocation in which case all iterators (including the
 [`end()`](basic_json/end.md) iterator) and all references to the elements are invalidated. Also, any iterator or
 reference after the insertion point will point to the same index, which is now a different value.
 
 ## Complexity
 
-[`ordered_map`](ordered_map/index.md) has no lookup index: every key-based object operation is a linear scan, so building or
+[`ordered_map`](ordered_map.md) has no lookup index: every key-based object operation is a linear scan, so building or
 parsing an object of `n` keys costs O(n²) rather than O(n log n). See
-[`ordered_map` complexity](ordered_map/index.md#complexity) for the per-operation table and for measured numbers.
+[`ordered_map` complexity](ordered_map.md#complexity) for the per-operation table and for measured numbers.
 
 ## Examples
 
@@ -37,7 +37,7 @@ parsing an object of `n` keys costs O(n²) rather than O(n log n). See
 
 ## See also
 
-- [ordered_map](ordered_map/index.md)
+- [ordered_map](ordered_map.md)
 - [Object Order](../features/object_order.md)
 
 ## Version history

docs/mkdocs/docs/api/ordered_map.md

@@ -6,7 +6,7 @@ template<class Key, class T, class IgnoredLess = std::less<Key>,
 struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
 ```
 
-A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](../ordered_json.md)
+A minimal map-like container that preserves insertion order for use within [`nlohmann::ordered_json`](ordered_json.md)
 (`nlohmann::basic_json<ordered_map>`).
 
 ## Template parameters
@@ -32,12 +32,12 @@ case all iterators (including the `end()` iterator) and all references to the el
 
 - **key_type** - key type (`Key`)
 - **mapped_type** - mapped type (`T`)
-- [**Container**](Container.md) - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
 - **iterator**
 - **const_iterator**
 - **size_type**
 - **value_type**
-- [**key_compare**](key_compare.md) - key comparison function
+- **key_compare** - key comparison function
 ```cpp
 std::equal_to<Key>  // until C++14
 
@@ -46,16 +46,15 @@ std::equal_to<>     // since C++14
 
 ## Member functions
 
-- [(constructor)](ordered_map.md)
-- [(destructor)](~ordered_map.md)
-- [**operator=**](operator=.md)
-- [**emplace**](emplace.md)
-- [**operator\[\]**](operator[].md)
-- [**at**](at.md)
-- [**erase**](erase.md)
-- [**count**](count.md)
-- [**find**](find.md)
-- [**insert**](insert.md)
+- (constructor)
+- (destructor)
+- **emplace**
+- **operator\[\]**
+- **at**
+- **erase**
+- **count**
+- **find**
+- **insert**
 
 ## Complexity
 
@@ -117,9 +116,9 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
 
 ## See also
 
-- [ordered_json](../ordered_json.md)
+- [ordered_json](ordered_json.md)
 
 ## Version history
 
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
 - Added **key_compare** member in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/Container.md

@@ -1,28 +0,0 @@
-# <small>nlohmann::ordered_map::</small>Container
-
-```cpp
-using Container = std::vector<std::pair<const Key, T>, Allocator>;
-```
-
-The base container type that `ordered_map` publicly inherits from. Elements are stored in insertion
-order as `#!cpp std::pair<const Key, T>` entries in a `std::vector`.
-
-## Examples
-
-??? example
-
-    The example shows the type `Container`.
-
-    ```cpp
-    --8<-- "examples/ordered_map__Container.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__Container.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).

docs/mkdocs/docs/api/ordered_map/at.md

@@ -1,61 +0,0 @@
-# <small>nlohmann::ordered_map::</small>at
-
-```cpp
-// (1)
-T& at(const key_type& key);
-const T& at(const key_type& key) const;
-
-// (2)
-template<class KeyType>
-T& at(KeyType&& key);
-template<class KeyType>
-const T& at(KeyType&& key) const;
-```
-
-1. Returns a reference to the value mapped to `key`.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup, e.g. looking up by a `#!cpp const char*` without constructing a temporary
-   `key_type`). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to find
-
-## Return value
-
-reference to the mapped value of the element with key equal to `key`
-
-## Exceptions
-
-Throws `std::out_of_range` if no element with key `key` exists.
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `at` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__at.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__at.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
-- Overload (2) added in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/count.md

@@ -1,53 +0,0 @@
-# <small>nlohmann::ordered_map::</small>count
-
-```cpp
-// (1)
-size_type count(const key_type& key) const;
-
-// (2)
-template<class KeyType>
-size_type count(KeyType&& key) const;
-```
-
-1. Returns the number of elements with key equal to `key` (0 or 1, since keys are unique).
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the elements to count
-
-## Return value
-
-number of elements with key equal to `key` (0 or 1)
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `count` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__count.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__count.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
-- Overload (2) added in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/emplace.md

@@ -1,58 +0,0 @@
-# <small>nlohmann::ordered_map::</small>emplace
-
-```cpp
-// (1)
-std::pair<iterator, bool> emplace(const key_type& key, T&& t);
-
-// (2)
-template<class KeyType>
-std::pair<iterator, bool> emplace(KeyType&& key, T&& t);
-```
-
-1. Inserts `#!cpp {key, t}` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
-   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to insert
-
-`t` (in)
-:   value of the element to insert
-
-## Return value
-
-pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
-took place and `false` if an element with an equal key already existed
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `emplace` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__emplace.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__emplace.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
-- Overload (2) added in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/erase.md

@@ -1,75 +0,0 @@
-# <small>nlohmann::ordered_map::</small>erase
-
-```cpp
-// (1)
-size_type erase(const key_type& key);
-
-// (2)
-template<class KeyType>
-size_type erase(KeyType&& key);
-
-// (3)
-iterator erase(iterator pos);
-
-// (4)
-iterator erase(iterator first, iterator last);
-```
-
-1. Removes the element with key equal to `key`, if any, preserving the relative order of the remaining
-   elements.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-3. Removes the element at `pos`.
-4. Removes the elements in range `[first, last)`.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to remove
-
-`pos` (in)
-:   iterator to the element to remove
-
-`first` (in)
-:   iterator to the first element to remove
-
-`last` (in)
-:   iterator one past the last element to remove
-
-## Return value
-
-1. number of elements removed (0 or 1)
-2. number of elements removed (0 or 1)
-3. iterator following the removed element
-4. iterator following the last removed element
-
-## Complexity
-
-Linear in the number of elements (elements after the removed one(s) are shifted to keep storage
-contiguous).
-
-## Examples
-
-??? example
-
-    The example shows how `erase` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__erase.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__erase.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
-- Overload (2) added in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/find.md

@@ -1,56 +0,0 @@
-# <small>nlohmann::ordered_map::</small>find
-
-```cpp
-// (1)
-iterator find(const key_type& key);
-const_iterator find(const key_type& key) const;
-
-// (2)
-template<class KeyType>
-iterator find(KeyType&& key);
-template<class KeyType>
-const_iterator find(KeyType&& key) const;
-```
-
-1. Returns an iterator to the element with key equal to `key`, or `end()` if no such element exists.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to find
-
-## Return value
-
-iterator to the element with key equal to `key`, or `end()` if not found
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `find` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__find.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__find.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).
-- Overload (2) added in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/insert.md

@@ -1,63 +0,0 @@
-# <small>nlohmann::ordered_map::</small>insert
-
-```cpp
-// (1)
-std::pair<iterator, bool> insert(value_type&& value);
-std::pair<iterator, bool> insert(const value_type& value);
-
-// (2)
-template<typename InputIt>
-void insert(InputIt first, InputIt last);
-```
-
-1. Inserts `value` if no element with an equal key already exists (per [`key_compare`](key_compare.md)),
-   appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
-2. Inserts the elements from range `[first, last)`, in iteration order, applying the same equal-key rule
-   as (1) to each element.
-
-## Template parameters
-
-`InputIt`
-:   an input iterator type
-
-## Parameters
-
-`value` (in)
-:   value to insert
-
-`first` (in)
-:   iterator to the first element to insert
-
-`last` (in)
-:   iterator one past the last element to insert
-
-## Return value
-
-1. pair of an iterator to the (possibly newly inserted) element, and a `bool` that is `true` if insertion
-   took place and `false` if an element with an equal key already existed
-2. (none)
-
-## Complexity
-
-1. Linear in the number of elements.
-2. Linear in the distance between `first` and `last`, times linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `insert` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__insert.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__insert.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.1 to implement [`nlohmann::ordered_json`](../ordered_json.md).

docs/mkdocs/docs/api/ordered_map/key_compare.md

@@ -1,34 +0,0 @@
-# <small>nlohmann::ordered_map::</small>key_compare
-
-```cpp
-using key_compare = std::equal_to<Key>;  // until C++14
-
-using key_compare = std::equal_to<>;     // since C++14
-```
-
-The comparator used to determine key equality when looking up elements. Unlike `std::map`, `ordered_map`
-uses linear search with `key_compare` rather than an ordering relation, since element order reflects
-insertion order rather than key order.
-
-Since C++14, the transparent `#!cpp std::equal_to<>` is used, which enables heterogeneous lookup (e.g.
-looking up by a `#!cpp const char*` key without constructing a temporary `Key`).
-
-## Examples
-
-??? example
-
-    The example shows how `key_compare` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__key_compare.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__key_compare.output"
-    ```
-
-## Version history
-
-- Added in version 3.11.0.

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

@@ -1,32 +0,0 @@
-# <small>nlohmann::ordered_map::</small>operator=
-
-```cpp
-// (1)
-ordered_map& operator=(const ordered_map& other);
-
-// (2)
-ordered_map& operator=(ordered_map&& other) noexcept(std::is_nothrow_move_assignable<Container>::value);
-```
-
-1. Copy assignment operator.
-2. Move assignment operator.
-
-## Parameters
-
-`other` (in)
-:   value to assign from
-
-## Return value
-
-`*this`
-
-## Complexity
-
-1. Linear in the size of `other`.
-2. Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).

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

@@ -1,62 +0,0 @@
-# <small>nlohmann::ordered_map::</small>operator[]
-
-```cpp
-// (1)
-T& operator[](const key_type& key);
-const T& operator[](const key_type& key) const;
-
-// (2)
-template<class KeyType>
-T& operator[](KeyType&& key);
-template<class KeyType>
-const T& operator[](KeyType&& key) const;
-```
-
-1. Returns a reference to the value mapped to `key`, inserting a default-constructed `T` (non-`const`
-   overload only) if no such element exists yet.
-2. Same as (1), but for any `KeyType` comparable to `key_type` via [`key_compare`](key_compare.md)
-   (heterogeneous lookup). Only participates in overload resolution if `KeyType` is usable as a key type.
-
-## Template parameters
-
-`KeyType`
-:   a type comparable to `key_type` via [`key_compare`](key_compare.md)
-
-## Parameters
-
-`key` (in)
-:   key of the element to find or insert
-
-## Return value
-
-reference to the mapped value of the element with key equal to `key`
-
-## Exceptions
-
-The `const` overloads throw `std::out_of_range` if no element with key `key` exists (they delegate to
-[`at`](at.md)).
-
-## Complexity
-
-Linear in the number of elements.
-
-## Examples
-
-??? example
-
-    The example shows how `operator[]` is used.
-
-    ```cpp
-    --8<-- "examples/ordered_map__operator_idx.cpp"
-    ```
-
-    Output:
-
-    ```
-    --8<-- "examples/ordered_map__operator_idx.output"
-    ```
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).
-- Overload (2) added in version 3.11.0.

docs/mkdocs/docs/api/ordered_map/ordered_map.md

@@ -1,66 +0,0 @@
-# <small>nlohmann::ordered_map::</small>ordered_map
-
-```cpp
-// (1)
-ordered_map() noexcept(noexcept(Container()));
-
-// (2)
-explicit ordered_map(const Allocator& alloc) noexcept(noexcept(Container(alloc)));
-
-// (3)
-template <class It>
-ordered_map(It first, It last, const Allocator& alloc = Allocator());
-
-// (4)
-ordered_map(std::initializer_list<value_type> init, const Allocator& alloc = Allocator());
-
-// (5)
-ordered_map(const ordered_map&) = default;
-
-// (6)
-ordered_map(ordered_map&&) noexcept(std::is_nothrow_move_constructible<Container>::value) = default;
-```
-
-1. Default constructor. Creates an empty `ordered_map`.
-2. Creates an empty `ordered_map` using the given allocator.
-3. Creates an `ordered_map` from the elements in range `[first, last)`, inserted in iteration order.
-4. Creates an `ordered_map` from an initializer list of key/value pairs, inserted in list order.
-5. Copy constructor.
-6. Move constructor.
-
-These constructors are declared explicitly (rather than inherited via `#!cpp using Container::Container`)
-because older compilers (GCC <= 5.5, Xcode <= 9.4) do not handle the inherited constructors correctly.
-
-## Template parameters
-
-`It`
-:   an input iterator type
-
-## Parameters
-
-`alloc` (in)
-:   allocator to use for the underlying container
-
-`first` (in)
-:   iterator to the first element to insert
-
-`last` (in)
-:   iterator one past the last element to insert
-
-`init` (in)
-:   initializer list of key/value pairs to insert
-
-## Complexity
-
-1. Constant.
-2. Constant.
-3. Linear in the distance between `first` and `last`.
-4. Linear in the size of `init`.
-5. Linear in the size of `other`.
-6. Constant.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).

docs/mkdocs/docs/api/ordered_map/~ordered_map.md

@@ -1,17 +0,0 @@
-# <small>nlohmann::ordered_map::</small>~ordered_map
-
-```cpp
-~ordered_map() = default;
-```
-
-Destroys the `ordered_map` and frees all allocated memory.
-
-## Complexity
-
-Linear in the number of elements.
-
-<!-- NOLINT Examples -->
-
-## Version history
-
-- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](../ordered_json.md).

docs/mkdocs/docs/examples/bjdata_version_t.cpp

@@ -1,21 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // an empty binary value is encoded differently by the two drafts:
-    // draft2 omits the optimized type marker for an empty byte array,
-    // while draft3 always writes it
-    json j = json::binary({});
-
-    // encode using BJData draft2 (the default)
-    auto v_draft2 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft2);
-
-    // encode using BJData draft3
-    auto v_draft3 = json::to_bjdata(j, true, true, json::bjdata_version_t::draft3);
-
-    std::cout << "draft2 size: " << v_draft2.size() << '\n'
-              << "draft3 size: " << v_draft3.size() << std::endl;
-}

docs/mkdocs/docs/examples/bjdata_version_t.output

@@ -1,2 +0,0 @@
-draft2 size: 4
-draft3 size: 6

docs/mkdocs/docs/examples/byte_container_with_subtype__container_type.cpp

@@ -1,11 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<byte_container_with_subtype::container_type, std::vector<std::uint8_t>>::value
-              << std::endl;
-}

docs/mkdocs/docs/examples/byte_container_with_subtype__container_type.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/byte_container_with_subtype__operator_eq.cpp

@@ -1,15 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    byte_container_with_subtype c1({0xca, 0xfe});
-    byte_container_with_subtype c2({0xca, 0xfe});
-    byte_container_with_subtype c3({0xca, 0xfe}, 42);
-
-    std::cout << std::boolalpha
-              << "c1 == c2: " << (c1 == c2) << '\n'
-              << "c1 == c3: " << (c1 == c3) << std::endl;
-}

docs/mkdocs/docs/examples/byte_container_with_subtype__operator_eq.output

@@ -1,2 +0,0 @@
-c1 == c2: true
-c1 == c3: false

docs/mkdocs/docs/examples/byte_container_with_subtype__operator_ne.cpp

@@ -1,15 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    byte_container_with_subtype c1({0xca, 0xfe});
-    byte_container_with_subtype c2({0xca, 0xfe});
-    byte_container_with_subtype c3({0xca, 0xfe}, 42);
-
-    std::cout << std::boolalpha
-              << "c1 != c2: " << (c1 != c2) << '\n'
-              << "c1 != c3: " << (c1 != c3) << std::endl;
-}

docs/mkdocs/docs/examples/byte_container_with_subtype__operator_ne.output

@@ -1,2 +0,0 @@
-c1 != c2: false
-c1 != c3: true

docs/mkdocs/docs/examples/byte_container_with_subtype__subtype_type.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<byte_container_with_subtype::subtype_type, std::uint64_t>::value << std::endl;
-}

docs/mkdocs/docs/examples/byte_container_with_subtype__subtype_type.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/initializer_list_t.cpp

@@ -1,13 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // an initializer_list_t is what a braced-init-list of JSON values is deduced as
-    json::initializer_list_t init = {"a", 1, 2.0, false};
-
-    json j(init);
-    std::cout << j.dump() << std::endl;
-}

docs/mkdocs/docs/examples/initializer_list_t.output

@@ -1 +0,0 @@
-["a",1,2.0,false]

docs/mkdocs/docs/examples/json_sax__binary_t.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::binary_t, json::binary_t>::value << std::endl;
-}

docs/mkdocs/docs/examples/json_sax__binary_t.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/json_sax__number_float_t.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::number_float_t, json::number_float_t>::value << std::endl;
-}

docs/mkdocs/docs/examples/json_sax__number_float_t.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/json_sax__number_integer_t.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::number_integer_t, json::number_integer_t>::value << std::endl;
-}

docs/mkdocs/docs/examples/json_sax__number_integer_t.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/json_sax__number_unsigned_t.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::number_unsigned_t, json::number_unsigned_t>::value << std::endl;
-}

docs/mkdocs/docs/examples/json_sax__number_unsigned_t.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/json_sax__string_t.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t::string_t, json::string_t>::value << std::endl;
-}

docs/mkdocs/docs/examples/json_sax__string_t.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/json_sax_t.cpp

@@ -1,10 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    std::cout << std::boolalpha
-              << std::is_same<json::json_sax_t, nlohmann::json_sax<json>>::value << std::endl;
-}

docs/mkdocs/docs/examples/json_sax_t.output

@@ -1 +0,0 @@
-true

docs/mkdocs/docs/examples/ordered_map__Container.cpp

@@ -1,12 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    using Map = nlohmann::ordered_map<std::string, int>;
-
-    std::cout << std::boolalpha
-              << "Container is std::vector<std::pair<const Key, T>>: "
-              << std::is_same<Map::Container, std::vector<std::pair<const std::string, int>>>::value
-              << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__Container.output

@@ -1 +0,0 @@
-Container is std::vector<std::pair<const Key, T>>: true

docs/mkdocs/docs/examples/ordered_map__at.cpp

@@ -1,26 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-    m["two"] = 2;
-
-    // access an existing element
-    std::cout << "m.at(\"one\") = " << m.at("one") << std::endl;
-
-    // modify through the reference returned by at()
-    m.at("two") = 22;
-    std::cout << "m.at(\"two\") = " << m.at("two") << std::endl;
-
-    // accessing a missing key throws
-    try
-    {
-        m.at("three");
-    }
-    catch (const std::out_of_range& e)
-    {
-        std::cout << "exception: " << e.what() << std::endl;
-    }
-}

docs/mkdocs/docs/examples/ordered_map__at.output

@@ -1,3 +0,0 @@
-m.at("one") = 1
-m.at("two") = 22
-exception: key not found

docs/mkdocs/docs/examples/ordered_map__count.cpp

@@ -1,12 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-
-    std::cout << std::boolalpha
-              << "m.count(\"one\") = " << m.count("one") << '\n'
-              << "m.count(\"two\") = " << m.count("two") << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__count.output

@@ -1,2 +0,0 @@
-m.count("one") = 1
-m.count("two") = 0

docs/mkdocs/docs/examples/ordered_map__emplace.cpp

@@ -1,15 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, std::string> m;
-
-    // emplace a new element
-    auto res1 = m.emplace("one", "eins");
-    std::cout << std::boolalpha << "inserted: " << res1.second << ", value: " << res1.first->second << std::endl;
-
-    // emplace with an already-existing key: no-op, returns the existing element
-    auto res2 = m.emplace("one", "uno");
-    std::cout << std::boolalpha << "inserted: " << res2.second << ", value: " << res2.first->second << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__emplace.output

@@ -1,2 +0,0 @@
-inserted: true, value: eins
-inserted: false, value: eins

docs/mkdocs/docs/examples/ordered_map__erase.cpp

@@ -1,24 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-    m["two"] = 2;
-    m["three"] = 3;
-
-    // erase by key
-    std::size_t removed = m.erase("two");
-    std::cout << "removed by key: " << removed << std::endl;
-
-    // erase by iterator
-    m.erase(m.begin());
-
-    std::cout << "remaining: ";
-    for (const auto& element : m)
-    {
-        std::cout << element.first << ' ';
-    }
-    std::cout << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__erase.output

@@ -1,2 +0,0 @@
-removed by key: 1
-remaining: three 

docs/mkdocs/docs/examples/ordered_map__find.cpp

@@ -1,19 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-    m["one"] = 1;
-
-    auto it = m.find("one");
-    if (it != m.end())
-    {
-        std::cout << "found: " << it->first << " = " << it->second << std::endl;
-    }
-
-    if (m.find("two") == m.end())
-    {
-        std::cout << "\"two\" not found" << std::endl;
-    }
-}

docs/mkdocs/docs/examples/ordered_map__find.output

@@ -1,2 +0,0 @@
-found: one = 1
-"two" not found

docs/mkdocs/docs/examples/ordered_map__insert.cpp

@@ -1,21 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-
-    // insert a single value
-    auto res = m.insert({"one", 1});
-    std::cout << std::boolalpha << "inserted: " << res.second << std::endl;
-
-    // insert a range from another container
-    std::vector<std::pair<const std::string, int>> more = {{"two", 2}, {"three", 3}};
-    m.insert(more.begin(), more.end());
-
-    for (const auto& element : m)
-    {
-        std::cout << element.first << ':' << element.second << ' ';
-    }
-    std::cout << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__insert.output

@@ -1,2 +0,0 @@
-inserted: true
-one:1 two:2 three:3 

docs/mkdocs/docs/examples/ordered_map__key_compare.cpp

@@ -1,12 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    using Map = nlohmann::ordered_map<std::string, int>;
-    Map::key_compare compare{};
-
-    std::cout << std::boolalpha
-              << "compare(\"a\", \"a\") = " << compare("a", "a") << '\n'
-              << "compare(\"a\", \"b\") = " << compare("a", "b") << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__key_compare.output

@@ -1,2 +0,0 @@
-compare("a", "a") = true
-compare("a", "b") = false

docs/mkdocs/docs/examples/ordered_map__operator_idx.cpp

@@ -1,14 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-int main()
-{
-    nlohmann::ordered_map<std::string, int> m;
-
-    // operator[] inserts a default-constructed value if the key doesn't exist yet
-    m["one"] = 1;
-    std::cout << "m[\"one\"] = " << m["one"] << std::endl;
-
-    // accessing again just returns the existing value
-    std::cout << "m[\"one\"] = " << m["one"] << std::endl;
-}

docs/mkdocs/docs/examples/ordered_map__operator_idx.output

@@ -1,2 +0,0 @@
-m["one"] = 1
-m["one"] = 1

docs/mkdocs/docs/features/object_order.md

@@ -51,16 +51,16 @@ If you do want to preserve the **insertion order**, you can use the type [`nlohm
     --8<-- "examples/ordered_json.output"
     ```
 
-Alternatively, [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) also preserves the insertion order and, unlike [`ordered_map`](../api/ordered_map/index.md), keeps a lookup index, so it does not have the quadratic cost described below. It is used through a small adapter ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
+Alternatively, [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) also preserves the insertion order and, unlike [`ordered_map`](../api/ordered_map.md), keeps a lookup index, so it does not have the quadratic cost described below. It is used through a small adapter ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
 
 If the order does not matter and you only want faster lookup, `boost::unordered_flat_map`, `absl::flat_hash_map`, `absl::node_hash_map`, and several other hash maps work through an adapter that restores the template argument order `basic_json` expects; see [Template Parameter Requirements](types/template_parameters.md#objecttype). Note these are *unordered*, not insertion-ordered.
 
 [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) cannot be used: its iterators expose the mapped value as `const`, while `basic_json` needs to modify it in place.
 
-The [`ordered_map`](../api/ordered_map/index.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup
+The [`ordered_map`](../api/ordered_map.md) behind `nlohmann::ordered_json` is deliberately minimal and has no lookup
 index, so every key access is a linear scan and building an object of `n` keys costs O(n²). This is unnoticeable at
 typical object sizes but becomes significant for objects with many thousands of keys; see
-[`ordered_map` complexity](../api/ordered_map/index.md#complexity). The alternatives above keep a lookup index and do not
+[`ordered_map` complexity](../api/ordered_map.md#complexity). The alternatives above keep a lookup index and do not
 have this cost.
 
 ### Notes on parsing

docs/mkdocs/docs/features/types/template_parameters.md

@@ -37,7 +37,7 @@ Requirements are split into two groups:
 
 | Template parameter                                                | Default                           | Notable substitutes                                                   |
 |-------------------------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------|
-| [`ObjectType`](#objecttype)                                       | `std::map`                        | [`nlohmann::ordered_map`](../../api/ordered_map/index.md), Abseil hash maps |
+| [`ObjectType`](#objecttype)                                       | `std::map`                        | [`nlohmann::ordered_map`](../../api/ordered_map.md), Abseil hash maps |
 | [`ArrayType`](#arraytype)                                         | `std::vector`                     | `#!cpp std::deque`                                                    |
 | [`StringType`](#stringtype)                                       | `std::string`                     | `std::string`-like types over `char`                                  |
 | [`BooleanType`](#booleantype)                                     | `bool`                            | none worth using                                                      |
@@ -230,7 +230,7 @@ The library does not sort or de-duplicate keys itself; the behavior described in
 | Container                                                                        | Notes                                                                         |
 |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | `#!cpp std::map` (default)                                                       |                                                                               |
-| [`nlohmann::ordered_map`](../../api/ordered_map/index.md)                              | used by [`ordered_json`](../../api/ordered_json.md); keeps insertion order    |
+| [`nlohmann::ordered_map`](../../api/ordered_map.md)                              | used by [`ordered_json`](../../api/ordered_json.md); keeps insertion order    |
 | [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map)                     | keeps insertion order; adapter puts `fifo_map_compare` in the comparator slot |
 | `boost::container::map`, `boost::container::flat_map`                            | no adapter needed                                                             |
 | `#!cpp std::unordered_map`                                                       | through the adapter above; not with libstdc++ 9, see the note                 |

docs/mkdocs/docs/home/architecture.md

@@ -50,7 +50,7 @@ The public headers are in [`include/nlohmann`](https://github.com/nlohmann/json/
 - [`adl_serializer.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/adl_serializer.hpp), [`byte_container_with_subtype.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/byte_container_with_subtype.hpp), and [`ordered_map.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/ordered_map.hpp) define
   [`adl_serializer`](../api/adl_serializer/index.md),
   [`byte_container_with_subtype`](../api/byte_container_with_subtype/index.md), and
-  [`ordered_map`](../api/ordered_map/index.md).
+  [`ordered_map`](../api/ordered_map.md).
 
 Everything else lives in [`detail/`](https://github.com/nlohmann/json/tree/develop/include/nlohmann/detail) and namespace `nlohmann::detail`, which is not part of the public API. Paths
 below are relative to `include/nlohmann`.
@@ -97,7 +97,7 @@ is generated from these files with `make amalgamate` and must not be edited by h
 The library provides two specializations:
 
 - [`json`](../api/json.md) uses all default template arguments.
-- [`ordered_json`](../api/ordered_json.md) uses [`ordered_map`](../api/ordered_map/index.md) as `ObjectType` to keep the
+- [`ordered_json`](../api/ordered_json.md) uses [`ordered_map`](../api/ordered_map.md) as `ObjectType` to keep the
   insertion order of object keys.
 
 The requirements on the template arguments are listed in

docs/mkdocs/docs/home/releases.md

@@ -2,8 +2,7 @@
 
 This page summarizes the notable changes of every release and links to the relevant documentation.
 The **complete release notes** — including all changes, the download files, and their checksums — are
-published on the [GitHub releases page](https://github.com/nlohmann/json/releases). For a raw,
-signature-level diff of the public API between releases, see [API Changes](api_changes.md).
+published on the [GitHub releases page](https://github.com/nlohmann/json/releases).
 
 ## v3.12.0 (2025-04-11)
 

docs/mkdocs/mkdocs.yml

@@ -52,7 +52,6 @@ nav:
       - "FAQ": home/faq.md
       - home/exceptions.md
       - home/releases.md
-      - home/api_changes.md
       - home/design_goals.md
       - home/architecture.md
       - home/customers.md
@@ -120,7 +119,6 @@ nav:
           - 'begin': api/basic_json/begin.md
           - 'binary': api/basic_json/binary.md
           - 'binary_t': api/basic_json/binary_t.md
-          - 'bjdata_version_t': api/basic_json/bjdata_version_t.md
           - 'boolean_t': api/basic_json/boolean_t.md
           - 'cbegin': api/basic_json/cbegin.md
           - 'cbor_tag_handler_t': api/basic_json/cbor_tag_handler_t.md
@@ -159,7 +157,6 @@ nav:
           - 'get_to': api/basic_json/get_to.md
           - 'std::formatter<basic_json>': api/basic_json/std_formatter.md
           - 'std::hash<basic_json>': api/basic_json/std_hash.md
-          - 'initializer_list_t': api/basic_json/initializer_list_t.md
           - 'input_format_t': api/basic_json/input_format_t.md
           - 'insert': api/basic_json/insert.md
           - 'invalid_iterator': api/basic_json/invalid_iterator.md
@@ -178,7 +175,6 @@ nav:
           - 'is_structured': api/basic_json/is_structured.md
           - 'items': api/basic_json/items.md
           - 'json_base_class_t': api/basic_json/json_base_class_t.md
-          - 'json_sax_t': api/basic_json/json_sax_t.md
           - 'json_serializer': api/basic_json/json_serializer.md
           - 'max_size': api/basic_json/max_size.md
           - 'meta': api/basic_json/meta.md
@@ -236,13 +232,9 @@ nav:
           - 'Overview': api/byte_container_with_subtype/index.md
           - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
           - 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md
-          - 'container_type': api/byte_container_with_subtype/container_type.md
           - 'has_subtype': api/byte_container_with_subtype/has_subtype.md
-          - 'operator==': api/byte_container_with_subtype/operator_eq.md
-          - 'operator!=': api/byte_container_with_subtype/operator_ne.md
           - 'set_subtype': api/byte_container_with_subtype/set_subtype.md
           - 'subtype': api/byte_container_with_subtype/subtype.md
-          - 'subtype_type': api/byte_container_with_subtype/subtype_type.md
       - adl_serializer:
           - 'Overview': api/adl_serializer/index.md
           - 'from_json': api/adl_serializer/from_json.md
@@ -268,46 +260,25 @@ nav:
           - 'to_string': api/json_pointer/to_string.md
       - json_sax:
           - 'Overview': api/json_sax/index.md
-          - '(Constructor)': api/json_sax/json_sax.md
-          - '(Destructor)': api/json_sax/~json_sax.md
-          - 'operator=': api/json_sax/operator=.md
           - 'binary': api/json_sax/binary.md
-          - 'binary_t': api/json_sax/binary_t.md
           - 'boolean': api/json_sax/boolean.md
           - 'end_array': api/json_sax/end_array.md
           - 'end_object': api/json_sax/end_object.md
           - 'key': api/json_sax/key.md
           - 'null': api/json_sax/null.md
           - 'number_float': api/json_sax/number_float.md
-          - 'number_float_t': api/json_sax/number_float_t.md
           - 'number_integer': api/json_sax/number_integer.md
-          - 'number_integer_t': api/json_sax/number_integer_t.md
           - 'number_unsigned': api/json_sax/number_unsigned.md
-          - 'number_unsigned_t': api/json_sax/number_unsigned_t.md
           - 'parse_error': api/json_sax/parse_error.md
           - 'start_array': api/json_sax/start_array.md
           - 'start_object': api/json_sax/start_object.md
           - 'string': api/json_sax/string.md
-          - 'string_t': api/json_sax/string_t.md
       - 'operator<<(basic_json), operator<<(json_pointer)': api/operator_ltlt.md
       - 'operator>>(basic_json)': api/operator_gtgt.md
       - 'operator""_json': api/operator_literal_json.md
       - 'operator""_json_pointer': api/operator_literal_json_pointer.md
       - 'ordered_json': api/ordered_json.md
-      - ordered_map:
-          - 'Overview': api/ordered_map/index.md
-          - '(Constructor)': api/ordered_map/ordered_map.md
-          - '(Destructor)': api/ordered_map/~ordered_map.md
-          - 'operator=': api/ordered_map/operator=.md
-          - 'at': api/ordered_map/at.md
-          - 'Container': api/ordered_map/Container.md
-          - 'count': api/ordered_map/count.md
-          - 'emplace': api/ordered_map/emplace.md
-          - 'erase': api/ordered_map/erase.md
-          - 'find': api/ordered_map/find.md
-          - 'insert': api/ordered_map/insert.md
-          - 'key_compare': api/ordered_map/key_compare.md
-          - 'operator[]': api/ordered_map/operator[].md
+      - 'ordered_map': api/ordered_map.md
       - macros:
           - 'Overview': api/macros/index.md
           - 'JSON_ASSERT': api/macros/json_assert.md

include/nlohmann/byte_container_with_subtype.hpp

@@ -22,9 +22,7 @@ template<typename BinaryType>
 class byte_container_with_subtype : public BinaryType
 {
   public:
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/container_type/
     using container_type = BinaryType;
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype_type/
     using subtype_type = std::uint64_t;
 
     /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
@@ -56,14 +54,12 @@ class byte_container_with_subtype : public BinaryType
         , m_has_subtype(true)
     {}
 
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/operator_eq/
     bool operator==(const byte_container_with_subtype& rhs) const
     {
         return std::tie(static_cast<const BinaryType&>(*this), m_subtype, m_has_subtype) ==
                std::tie(static_cast<const BinaryType&>(rhs), rhs.m_subtype, rhs.m_has_subtype);
     }
 
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/operator_ne/
     bool operator!=(const byte_container_with_subtype& rhs) const
     {
         return !(rhs == *this);

include/nlohmann/detail/conversions/to_json.hpp

@@ -291,7 +291,9 @@ void to_json(BasicJsonType& j, const std::optional<T>& opt) noexcept
 {
     if (opt.has_value())
     {
-        j = *opt;
+        // explicit construction, as the conversion from a basic_json with a different
+        // string type is explicit if JSON_USE_IMPLICIT_CONVERSIONS is 0 (#2649)
+        j = BasicJsonType(*opt);
     }
     else
     {

include/nlohmann/detail/input/json_sax.hpp

@@ -33,21 +33,15 @@ input.
 template<typename BasicJsonType>
 struct json_sax
 {
-    /// @sa https://json.nlohmann.me/api/json_sax/number_integer_t/
     using number_integer_t = typename BasicJsonType::number_integer_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/number_unsigned_t/
     using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/number_float_t/
     using number_float_t = typename BasicJsonType::number_float_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/string_t/
     using string_t = typename BasicJsonType::string_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/binary_t/
     using binary_t = typename BasicJsonType::binary_t;
 
     /*!
     @brief a null value was read
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/null/
     */
     virtual bool null() = 0;
 
@@ -55,7 +49,6 @@ struct json_sax
     @brief a boolean value was read
     @param[in] val  boolean value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/boolean/
     */
     virtual bool boolean(bool val) = 0;
 
@@ -63,7 +56,6 @@ struct json_sax
     @brief an integer number was read
     @param[in] val  integer value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_integer/
     */
     virtual bool number_integer(number_integer_t val) = 0;
 
@@ -71,7 +63,6 @@ struct json_sax
     @brief an unsigned integer number was read
     @param[in] val  unsigned integer value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_unsigned/
     */
     virtual bool number_unsigned(number_unsigned_t val) = 0;
 
@@ -80,7 +71,6 @@ struct json_sax
     @param[in] val  floating-point value
     @param[in] s    raw token value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_float/
     */
     virtual bool number_float(number_float_t val, const string_t& s) = 0;
 
@@ -89,7 +79,6 @@ struct json_sax
     @param[in] val  string value
     @return whether parsing should proceed
     @note It is safe to move the passed string value.
-    @sa https://json.nlohmann.me/api/json_sax/string/
     */
     virtual bool string(string_t& val) = 0;
 
@@ -98,7 +87,6 @@ struct json_sax
     @param[in] val  binary value
     @return whether parsing should proceed
     @note It is safe to move the passed binary value.
-    @sa https://json.nlohmann.me/api/json_sax/binary/
     */
     virtual bool binary(binary_t& val) = 0;
 
@@ -107,7 +95,6 @@ struct json_sax
     @param[in] elements  number of object elements or -1 if unknown
     @return whether parsing should proceed
     @note binary formats may report the number of elements
-    @sa https://json.nlohmann.me/api/json_sax/start_object/
     */
     virtual bool start_object(std::size_t elements) = 0;
 
@@ -116,14 +103,12 @@ struct json_sax
     @param[in] val  object key
     @return whether parsing should proceed
     @note It is safe to move the passed string.
-    @sa https://json.nlohmann.me/api/json_sax/key/
     */
     virtual bool key(string_t& val) = 0;
 
     /*!
     @brief the end of an object was read
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/end_object/
     */
     virtual bool end_object() = 0;
 
@@ -132,14 +117,12 @@ struct json_sax
     @param[in] elements  number of array elements or -1 if unknown
     @return whether parsing should proceed
     @note binary formats may report the number of elements
-    @sa https://json.nlohmann.me/api/json_sax/start_array/
     */
     virtual bool start_array(std::size_t elements) = 0;
 
     /*!
     @brief the end of an array was read
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/end_array/
     */
     virtual bool end_array() = 0;
 
@@ -149,23 +132,16 @@ struct json_sax
     @param[in] last_token  the last read token
     @param[in] ex          an exception object describing the error
     @return whether parsing should proceed (must return false)
-    @sa https://json.nlohmann.me/api/json_sax/parse_error/
     */
     virtual bool parse_error(std::size_t position,
                              const std::string& last_token,
                              const detail::exception& ex) = 0;
 
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
     json_sax() = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
     json_sax(const json_sax&) = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
     json_sax(json_sax&&) noexcept = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/operator=/
     json_sax& operator=(const json_sax&) = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/operator=/
     json_sax& operator=(json_sax&&) noexcept = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/~json_sax/
     virtual ~json_sax() = default;
 };
 

include/nlohmann/detail/json_pointer.hpp

@@ -56,7 +56,6 @@ class json_pointer
 
   public:
     // for backwards compatibility accept BasicJsonType
-    /// @sa https://json.nlohmann.me/api/json_pointer/string_t/
     using string_t = typename string_t_helper<RefStringType>::type;
 
     /// @brief create JSON pointer

include/nlohmann/json.hpp

@@ -202,31 +202,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     using serializer = ::nlohmann::detail::serializer<basic_json>;
 
   public:
-    /// @brief the type of the JSON value
-    /// @sa https://json.nlohmann.me/api/basic_json/value_t/
     using value_t = detail::value_t;
     /// JSON Pointer, see @ref nlohmann::json_pointer
     using json_pointer = ::nlohmann::json_pointer<StringType>;
     template<typename T, typename SFINAE>
     using json_serializer = JSONSerializer<T, SFINAE>;
     /// how to treat decoding errors
-    /// @sa https://json.nlohmann.me/api/basic_json/error_handler_t/
     using error_handler_t = detail::error_handler_t;
     /// how to treat CBOR tags
-    /// @sa https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/
     using cbor_tag_handler_t = detail::cbor_tag_handler_t;
     /// how to encode BJData
-    /// @sa https://json.nlohmann.me/api/basic_json/bjdata_version_t/
     using bjdata_version_t = detail::bjdata_version_t;
     /// helper type for initializer lists of basic_json values
-    /// @sa https://json.nlohmann.me/api/basic_json/initializer_list_t/
     using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
 
-    /// @brief the type of the SAX interface used to parse and serialize the JSON value
-    /// @sa https://json.nlohmann.me/api/basic_json/input_format_t/
     using input_format_t = detail::input_format_t;
     /// SAX interface type, see @ref nlohmann::json_sax
-    /// @sa https://json.nlohmann.me/api/basic_json/json_sax_t/
     using json_sax_t = json_sax<basic_json>;
 
     ////////////////
@@ -368,19 +359,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /// the template arguments passed to class @ref basic_json.
     /// @{
 
-#if defined(JSON_HAS_CPP_14)
     /// @brief default object key comparator type
     /// The actual object key comparator type (@ref object_comparator_t) may be
     /// different.
     /// @sa https://json.nlohmann.me/api/basic_json/default_object_comparator_t/
+#if defined(JSON_HAS_CPP_14)
     // use of transparent comparator avoids unnecessary repeated construction of temporaries
     // in functions involving lookup by key with types other than object_t::key_type (aka. StringType)
     using default_object_comparator_t = std::less<>;
 #else
-    /// @brief default object key comparator type
-    /// The actual object key comparator type (@ref object_comparator_t) may be
-    /// different.
-    /// @sa https://json.nlohmann.me/api/basic_json/default_object_comparator_t/
     using default_object_comparator_t = std::less<StringType>;
 #endif
 
@@ -1618,12 +1605,42 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
+  private:
+    /// whether a basic_json specialization can be converted implicitly into this one;
+    /// with JSON_USE_IMPLICIT_CONVERSIONS set to 0, this is only the case if both share
+    /// the same string type (see https://github.com/nlohmann/json/issues/2649)
+    template<typename BasicJsonType>
+    using is_implicitly_convertible_basic_json = std::integral_constant < bool,
+          (JSON_USE_IMPLICIT_CONVERSIONS != 0)
+          || std::is_same<typename BasicJsonType::string_t, string_t>::value >;
+
+    /// tag to select the constructor that performs the conversion from another basic_json specialization
+    struct convert_basic_json_tag {};
+
+  public:
     /// @brief create a JSON value from an existing one
     /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
     template < typename BasicJsonType,
                detail::enable_if_t <
-                   detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value, int > = 0 >
+                   detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value
+                   && is_implicitly_convertible_basic_json<BasicJsonType>::value, int > = 0 >
     basic_json(const BasicJsonType& val)
+        : basic_json(val, convert_basic_json_tag{})
+    {}
+
+    /// @brief create a JSON value from an existing one
+    /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
+    template < typename BasicJsonType,
+               detail::enable_if_t <
+                   detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value
+                   && !is_implicitly_convertible_basic_json<BasicJsonType>::value, int > = 0 >
+    explicit basic_json(const BasicJsonType& val)
+        : basic_json(val, convert_basic_json_tag{})
+    {}
+
+  private:
+    template<typename BasicJsonType>
+    basic_json(const BasicJsonType& val, convert_basic_json_tag /*unused*/)
 #if JSON_DIAGNOSTIC_POSITIONS
         : start_position(val.start_pos()),
           end_position(val.end_pos())
@@ -1679,6 +1696,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
+  public:
     /// @brief create a container (array or object) from an initializer list
     /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
     basic_json(initializer_list_t init,
@@ -1926,7 +1944,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     // other constructors and destructor //
     ///////////////////////////////////////
 
-    /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
     template<typename JsonRef,
              detail::enable_if_t<detail::conjunction<detail::is_json_ref<JsonRef>,
                                  std::is_same<typename JsonRef::value_type, basic_json>>::value, int> = 0 >
@@ -2446,7 +2463,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                    int > = 0 >
     BasicJsonType get_impl(detail::priority_tag<2> /*unused*/) const
     {
-        return *this;
+        return BasicJsonType(*this);
     }
 
     /*!
@@ -2510,8 +2527,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     @throw what @ref json_serializer<ValueType> `from_json()` method throws if conversion is required
 
     @since version 2.1.0
-
-    @sa https://json.nlohmann.me/api/basic_json/get/
     */
     template < typename ValueTypeCV, typename ValueType = detail::uncvref_t<ValueTypeCV>>
 #if defined(JSON_HAS_CPP_14)
@@ -2555,8 +2570,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     @sa see @ref get_ptr() for explicit pointer-member access
 
     @since version 1.0.0
-
-    @sa https://json.nlohmann.me/api/basic_json/get/
     */
     template<typename PointerType, typename std::enable_if<
                  std::is_pointer<PointerType>::value, int>::type = 0>
@@ -2583,18 +2596,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     // specialization to allow calling get_to with a basic_json value
     // see https://github.com/nlohmann/json/issues/2175
-    /// @sa https://json.nlohmann.me/api/basic_json/get_to/
     template<typename ValueType,
              detail::enable_if_t <
                  detail::is_basic_json<ValueType>::value,
                  int> = 0>
     ValueType & get_to(ValueType& v) const
     {
-        v = *this;
+        v = ValueType(*this);
         return v;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/get_to/
     template <
         typename T, std::size_t N,
         typename Array = T (&)[N], // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
@@ -2659,7 +2670,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     @since version 1.0.0
     */
-    /// @sa https://json.nlohmann.me/api/basic_json/operator_ValueType/
     template < typename ValueType, typename std::enable_if <
                    detail::conjunction <
                        detail::negation<std::is_pointer<ValueType>>,
@@ -2932,14 +2942,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     // these two functions resolve a (const) char * ambiguity affecting Clang and MSVC
     // (they seemingly cannot be constrained to resolve the ambiguity)
-    /// @sa https://json.nlohmann.me/api/basic_json/operator[]/
     template<typename T>
     reference operator[](T* key)
     {
         return operator[](typename object_t::key_type(key));
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/operator[]/
     template<typename T>
     const_reference operator[](T* key) const
     {
@@ -3149,7 +3157,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         JSON_THROW(type_error::create(306, detail::concat("cannot use value() with ", type_name()), this));
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/value/
     template < class ValueType, class BasicJsonType, detail::enable_if_t <
                    detail::is_basic_json<BasicJsonType>::value
                    && detail::is_getable<basic_json_t, ValueType>::value
@@ -3160,7 +3167,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return value(ptr.convert(), default_value);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/value/
     template < class ValueType, class BasicJsonType, class ReturnType = typename value_return_type<ValueType>::type,
                detail::enable_if_t <
                    detail::is_basic_json<BasicJsonType>::value
@@ -3540,7 +3546,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.contains(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/contains/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
@@ -4960,7 +4965,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/parse/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, parse(ptr, ptr + len))
     static basic_json parse(detail::span_input_adapter&& i,
@@ -4997,7 +5001,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return parser(detail::input_adapter(std::move(first), std::move(last)), nullptr, false, ignore_comments, ignore_trailing_commas, true).accept(true);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/accept/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, accept(ptr, ptr + len))
     static bool accept(detail::span_input_adapter&& i,
@@ -5381,7 +5384,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_cbor(ptr, ptr + len))
@@ -5393,7 +5395,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_cbor(ptr, ptr + len, strict, allow_exceptions, tag_handler);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_cbor(ptr, ptr + len))
     static basic_json from_cbor(detail::span_input_adapter&& i,
@@ -5449,7 +5450,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
@@ -5460,7 +5460,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_msgpack(ptr, ptr + len, strict, allow_exceptions);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
     static basic_json from_msgpack(detail::span_input_adapter&& i,
@@ -5515,7 +5514,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_ubjson(ptr, ptr + len))
@@ -5526,7 +5524,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_ubjson(ptr, ptr + len, strict, allow_exceptions);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_ubjson(ptr, ptr + len))
     static basic_json from_ubjson(detail::span_input_adapter&& i,
@@ -5655,7 +5652,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_bson(ptr, ptr + len))
@@ -5666,7 +5662,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_bson(ptr, ptr + len, strict, allow_exceptions);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_bson(ptr, ptr + len))
     static basic_json from_bson(detail::span_input_adapter&& i,
@@ -5699,7 +5694,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_unchecked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     reference operator[](const ::nlohmann::json_pointer<BasicJsonType>& ptr)
@@ -5714,7 +5708,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_unchecked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     const_reference operator[](const ::nlohmann::json_pointer<BasicJsonType>& ptr) const
@@ -5729,7 +5722,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_checked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/at/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     reference at(const ::nlohmann::json_pointer<BasicJsonType>& ptr)
@@ -5744,7 +5736,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_checked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/at/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     const_reference at(const ::nlohmann::json_pointer<BasicJsonType>& ptr) const

include/nlohmann/ordered_map.hpp

@@ -30,41 +30,30 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
 {
     using key_type = Key;
     using mapped_type = T;
-    /// @sa https://json.nlohmann.me/api/ordered_map/Container/
     using Container = std::vector<std::pair<const Key, T>, Allocator>;
     using iterator = typename Container::iterator;
     using const_iterator = typename Container::const_iterator;
     using size_type = typename Container::size_type;
     using value_type = typename Container::value_type;
 #ifdef JSON_HAS_CPP_14
-    /// @sa https://json.nlohmann.me/api/ordered_map/key_compare/
     using key_compare = std::equal_to<>;
 #else
-    /// @sa https://json.nlohmann.me/api/ordered_map/key_compare/
     using key_compare = std::equal_to<Key>;
 #endif
 
     // Explicit constructors instead of `using Container::Container`
     // otherwise older compilers choke on it (GCC <= 5.5, xcode <= 9.4)
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map() noexcept(noexcept(Container())) : Container{} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     explicit ordered_map(const Allocator& alloc) noexcept(noexcept(Container(alloc))) : Container{alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     template <class It>
     ordered_map(It first, It last, const Allocator& alloc = Allocator())
         : Container{first, last, alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map(std::initializer_list<value_type> init, const Allocator& alloc = Allocator() )
         : Container{init, alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map(const ordered_map&) = default;
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map(ordered_map&&) noexcept(std::is_nothrow_move_constructible<Container>::value) = default;
-    /// @sa https://json.nlohmann.me/api/ordered_map/~ordered_map/
     ~ordered_map() = default;
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator=/
     ordered_map& operator=(const ordered_map& other)
     {
         if (this != &other)
@@ -75,14 +64,12 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return *this;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator=/
     ordered_map& operator=(ordered_map&& other) noexcept(std::is_nothrow_move_assignable<Container>::value)
     {
         Container::operator=(std::move(static_cast<Container&>(other)));
         return *this;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/emplace/
     std::pair<iterator, bool> emplace(const key_type& key, T&& t)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -96,7 +83,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return {std::prev(this->end()), true};
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/emplace/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     std::pair<iterator, bool> emplace(KeyType && key, T && t)
@@ -112,13 +98,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return {std::prev(this->end()), true};
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     T& operator[](const key_type& key)
     {
         return emplace(key, T{}).first->second;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     T & operator[](KeyType && key)
@@ -126,13 +110,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return emplace(std::forward<KeyType>(key), T{}).first->second;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     const T& operator[](const key_type& key) const
     {
         return at(key);
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     const T & operator[](KeyType && key) const
@@ -140,7 +122,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return at(std::forward<KeyType>(key));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     T& at(const key_type& key)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -154,7 +135,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     T & at(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -170,7 +150,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     const T& at(const key_type& key) const
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -184,7 +163,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     const T & at(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -200,7 +178,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     size_type erase(const key_type& key)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -220,7 +197,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     size_type erase(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -242,13 +218,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     iterator erase(iterator pos)
     {
         return erase(pos, std::next(pos));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     iterator erase(iterator first, iterator last)
     {
         if (first == last)
@@ -302,7 +276,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::begin() + offset;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/count/
     size_type count(const key_type& key) const
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -315,7 +288,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/count/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     size_type count(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -330,7 +302,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     iterator find(const key_type& key)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -343,7 +314,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     iterator find(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -358,7 +328,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     const_iterator find(const key_type& key) const
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -371,7 +340,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     const_iterator find(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -386,13 +354,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
     std::pair<iterator, bool> insert( value_type&& value )
     {
         return emplace(value.first, std::move(value.second));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
     std::pair<iterator, bool> insert( const value_type& value )
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -410,7 +376,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
     using require_input_iter = typename std::enable_if<std::is_convertible<typename std::iterator_traits<InputIt>::iterator_category,
         std::input_iterator_tag>::value>::type;
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
     template<typename InputIt, typename = require_input_iter<InputIt>>
     void insert(InputIt first, InputIt last)
     {

single_include/nlohmann/json.hpp

@@ -6820,7 +6820,9 @@ void to_json(BasicJsonType& j, const std::optional<T>& opt) noexcept
 {
     if (opt.has_value())
     {
-        j = *opt;
+        // explicit construction, as the conversion from a basic_json with a different
+        // string type is explicit if JSON_USE_IMPLICIT_CONVERSIONS is 0 (#2649)
+        j = BasicJsonType(*opt);
     }
     else
     {
@@ -7154,9 +7156,7 @@ template<typename BinaryType>
 class byte_container_with_subtype : public BinaryType
 {
   public:
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/container_type/
     using container_type = BinaryType;
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype_type/
     using subtype_type = std::uint64_t;
 
     /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
@@ -7188,14 +7188,12 @@ class byte_container_with_subtype : public BinaryType
         , m_has_subtype(true)
     {}
 
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/operator_eq/
     bool operator==(const byte_container_with_subtype& rhs) const
     {
         return std::tie(static_cast<const BinaryType&>(*this), m_subtype, m_has_subtype) ==
                std::tie(static_cast<const BinaryType&>(rhs), rhs.m_subtype, rhs.m_has_subtype);
     }
 
-    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/operator_ne/
     bool operator!=(const byte_container_with_subtype& rhs) const
     {
         return !(rhs == *this);
@@ -11419,21 +11417,15 @@ input.
 template<typename BasicJsonType>
 struct json_sax
 {
-    /// @sa https://json.nlohmann.me/api/json_sax/number_integer_t/
     using number_integer_t = typename BasicJsonType::number_integer_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/number_unsigned_t/
     using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/number_float_t/
     using number_float_t = typename BasicJsonType::number_float_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/string_t/
     using string_t = typename BasicJsonType::string_t;
-    /// @sa https://json.nlohmann.me/api/json_sax/binary_t/
     using binary_t = typename BasicJsonType::binary_t;
 
     /*!
     @brief a null value was read
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/null/
     */
     virtual bool null() = 0;
 
@@ -11441,7 +11433,6 @@ struct json_sax
     @brief a boolean value was read
     @param[in] val  boolean value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/boolean/
     */
     virtual bool boolean(bool val) = 0;
 
@@ -11449,7 +11440,6 @@ struct json_sax
     @brief an integer number was read
     @param[in] val  integer value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_integer/
     */
     virtual bool number_integer(number_integer_t val) = 0;
 
@@ -11457,7 +11447,6 @@ struct json_sax
     @brief an unsigned integer number was read
     @param[in] val  unsigned integer value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_unsigned/
     */
     virtual bool number_unsigned(number_unsigned_t val) = 0;
 
@@ -11466,7 +11455,6 @@ struct json_sax
     @param[in] val  floating-point value
     @param[in] s    raw token value
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/number_float/
     */
     virtual bool number_float(number_float_t val, const string_t& s) = 0;
 
@@ -11475,7 +11463,6 @@ struct json_sax
     @param[in] val  string value
     @return whether parsing should proceed
     @note It is safe to move the passed string value.
-    @sa https://json.nlohmann.me/api/json_sax/string/
     */
     virtual bool string(string_t& val) = 0;
 
@@ -11484,7 +11471,6 @@ struct json_sax
     @param[in] val  binary value
     @return whether parsing should proceed
     @note It is safe to move the passed binary value.
-    @sa https://json.nlohmann.me/api/json_sax/binary/
     */
     virtual bool binary(binary_t& val) = 0;
 
@@ -11493,7 +11479,6 @@ struct json_sax
     @param[in] elements  number of object elements or -1 if unknown
     @return whether parsing should proceed
     @note binary formats may report the number of elements
-    @sa https://json.nlohmann.me/api/json_sax/start_object/
     */
     virtual bool start_object(std::size_t elements) = 0;
 
@@ -11502,14 +11487,12 @@ struct json_sax
     @param[in] val  object key
     @return whether parsing should proceed
     @note It is safe to move the passed string.
-    @sa https://json.nlohmann.me/api/json_sax/key/
     */
     virtual bool key(string_t& val) = 0;
 
     /*!
     @brief the end of an object was read
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/end_object/
     */
     virtual bool end_object() = 0;
 
@@ -11518,14 +11501,12 @@ struct json_sax
     @param[in] elements  number of array elements or -1 if unknown
     @return whether parsing should proceed
     @note binary formats may report the number of elements
-    @sa https://json.nlohmann.me/api/json_sax/start_array/
     */
     virtual bool start_array(std::size_t elements) = 0;
 
     /*!
     @brief the end of an array was read
     @return whether parsing should proceed
-    @sa https://json.nlohmann.me/api/json_sax/end_array/
     */
     virtual bool end_array() = 0;
 
@@ -11535,23 +11516,16 @@ struct json_sax
     @param[in] last_token  the last read token
     @param[in] ex          an exception object describing the error
     @return whether parsing should proceed (must return false)
-    @sa https://json.nlohmann.me/api/json_sax/parse_error/
     */
     virtual bool parse_error(std::size_t position,
                              const std::string& last_token,
                              const detail::exception& ex) = 0;
 
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
     json_sax() = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
     json_sax(const json_sax&) = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/json_sax/
     json_sax(json_sax&&) noexcept = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/operator=/
     json_sax& operator=(const json_sax&) = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/operator=/
     json_sax& operator=(json_sax&&) noexcept = default;
-    /// @sa https://json.nlohmann.me/api/json_sax/~json_sax/
     virtual ~json_sax() = default;
 };
 
@@ -18728,7 +18702,6 @@ class json_pointer
 
   public:
     // for backwards compatibility accept BasicJsonType
-    /// @sa https://json.nlohmann.me/api/json_pointer/string_t/
     using string_t = typename string_t_helper<RefStringType>::type;
 
     /// @brief create JSON pointer
@@ -25623,41 +25596,30 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
 {
     using key_type = Key;
     using mapped_type = T;
-    /// @sa https://json.nlohmann.me/api/ordered_map/Container/
     using Container = std::vector<std::pair<const Key, T>, Allocator>;
     using iterator = typename Container::iterator;
     using const_iterator = typename Container::const_iterator;
     using size_type = typename Container::size_type;
     using value_type = typename Container::value_type;
 #ifdef JSON_HAS_CPP_14
-    /// @sa https://json.nlohmann.me/api/ordered_map/key_compare/
     using key_compare = std::equal_to<>;
 #else
-    /// @sa https://json.nlohmann.me/api/ordered_map/key_compare/
     using key_compare = std::equal_to<Key>;
 #endif
 
     // Explicit constructors instead of `using Container::Container`
     // otherwise older compilers choke on it (GCC <= 5.5, xcode <= 9.4)
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map() noexcept(noexcept(Container())) : Container{} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     explicit ordered_map(const Allocator& alloc) noexcept(noexcept(Container(alloc))) : Container{alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     template <class It>
     ordered_map(It first, It last, const Allocator& alloc = Allocator())
         : Container{first, last, alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map(std::initializer_list<value_type> init, const Allocator& alloc = Allocator() )
         : Container{init, alloc} {}
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map(const ordered_map&) = default;
-    /// @sa https://json.nlohmann.me/api/ordered_map/ordered_map/
     ordered_map(ordered_map&&) noexcept(std::is_nothrow_move_constructible<Container>::value) = default;
-    /// @sa https://json.nlohmann.me/api/ordered_map/~ordered_map/
     ~ordered_map() = default;
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator=/
     ordered_map& operator=(const ordered_map& other)
     {
         if (this != &other)
@@ -25668,14 +25630,12 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return *this;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator=/
     ordered_map& operator=(ordered_map&& other) noexcept(std::is_nothrow_move_assignable<Container>::value)
     {
         Container::operator=(std::move(static_cast<Container&>(other)));
         return *this;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/emplace/
     std::pair<iterator, bool> emplace(const key_type& key, T&& t)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25689,7 +25649,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return {std::prev(this->end()), true};
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/emplace/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     std::pair<iterator, bool> emplace(KeyType && key, T && t)
@@ -25705,13 +25664,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return {std::prev(this->end()), true};
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     T& operator[](const key_type& key)
     {
         return emplace(key, T{}).first->second;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     T & operator[](KeyType && key)
@@ -25719,13 +25676,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return emplace(std::forward<KeyType>(key), T{}).first->second;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     const T& operator[](const key_type& key) const
     {
         return at(key);
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/operator[]/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     const T & operator[](KeyType && key) const
@@ -25733,7 +25688,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return at(std::forward<KeyType>(key));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     T& at(const key_type& key)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25747,7 +25701,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     T & at(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -25763,7 +25716,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     const T& at(const key_type& key) const
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25777,7 +25729,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/at/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     const T & at(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -25793,7 +25744,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         JSON_THROW(std::out_of_range("key not found"));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     size_type erase(const key_type& key)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25813,7 +25763,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     size_type erase(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -25835,13 +25784,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     iterator erase(iterator pos)
     {
         return erase(pos, std::next(pos));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/erase/
     iterator erase(iterator first, iterator last)
     {
         if (first == last)
@@ -25895,7 +25842,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::begin() + offset;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/count/
     size_type count(const key_type& key) const
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25908,7 +25854,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/count/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     size_type count(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -25923,7 +25868,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return 0;
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     iterator find(const key_type& key)
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25936,7 +25880,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     iterator find(KeyType && key) // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -25951,7 +25894,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     const_iterator find(const key_type& key) const
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -25964,7 +25906,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/find/
     template<class KeyType, detail::enable_if_t<
                  detail::is_usable_as_key_type<key_compare, key_type, KeyType>::value, int> = 0>
     const_iterator find(KeyType && key) const // NOLINT(cppcoreguidelines-missing-std-forward)
@@ -25979,13 +25920,11 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
         return Container::end();
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
     std::pair<iterator, bool> insert( value_type&& value )
     {
         return emplace(value.first, std::move(value.second));
     }
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
     std::pair<iterator, bool> insert( const value_type& value )
     {
         for (auto it = this->begin(); it != this->end(); ++it)
@@ -26003,7 +25942,6 @@ template <class Key, class T, class IgnoredLess = std::less<Key>,
     using require_input_iter = typename std::enable_if<std::is_convertible<typename std::iterator_traits<InputIt>::iterator_category,
         std::input_iterator_tag>::value>::type;
 
-    /// @sa https://json.nlohmann.me/api/ordered_map/insert/
     template<typename InputIt, typename = require_input_iter<InputIt>>
     void insert(InputIt first, InputIt last)
     {
@@ -26149,31 +26087,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     using serializer = ::nlohmann::detail::serializer<basic_json>;
 
   public:
-    /// @brief the type of the JSON value
-    /// @sa https://json.nlohmann.me/api/basic_json/value_t/
     using value_t = detail::value_t;
     /// JSON Pointer, see @ref nlohmann::json_pointer
     using json_pointer = ::nlohmann::json_pointer<StringType>;
     template<typename T, typename SFINAE>
     using json_serializer = JSONSerializer<T, SFINAE>;
     /// how to treat decoding errors
-    /// @sa https://json.nlohmann.me/api/basic_json/error_handler_t/
     using error_handler_t = detail::error_handler_t;
     /// how to treat CBOR tags
-    /// @sa https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/
     using cbor_tag_handler_t = detail::cbor_tag_handler_t;
     /// how to encode BJData
-    /// @sa https://json.nlohmann.me/api/basic_json/bjdata_version_t/
     using bjdata_version_t = detail::bjdata_version_t;
     /// helper type for initializer lists of basic_json values
-    /// @sa https://json.nlohmann.me/api/basic_json/initializer_list_t/
     using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
 
-    /// @brief the type of the SAX interface used to parse and serialize the JSON value
-    /// @sa https://json.nlohmann.me/api/basic_json/input_format_t/
     using input_format_t = detail::input_format_t;
     /// SAX interface type, see @ref nlohmann::json_sax
-    /// @sa https://json.nlohmann.me/api/basic_json/json_sax_t/
     using json_sax_t = json_sax<basic_json>;
 
     ////////////////
@@ -26315,19 +26244,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /// the template arguments passed to class @ref basic_json.
     /// @{
 
-#if defined(JSON_HAS_CPP_14)
     /// @brief default object key comparator type
     /// The actual object key comparator type (@ref object_comparator_t) may be
     /// different.
     /// @sa https://json.nlohmann.me/api/basic_json/default_object_comparator_t/
+#if defined(JSON_HAS_CPP_14)
     // use of transparent comparator avoids unnecessary repeated construction of temporaries
     // in functions involving lookup by key with types other than object_t::key_type (aka. StringType)
     using default_object_comparator_t = std::less<>;
 #else
-    /// @brief default object key comparator type
-    /// The actual object key comparator type (@ref object_comparator_t) may be
-    /// different.
-    /// @sa https://json.nlohmann.me/api/basic_json/default_object_comparator_t/
     using default_object_comparator_t = std::less<StringType>;
 #endif
 
@@ -27565,12 +27490,42 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
+  private:
+    /// whether a basic_json specialization can be converted implicitly into this one;
+    /// with JSON_USE_IMPLICIT_CONVERSIONS set to 0, this is only the case if both share
+    /// the same string type (see https://github.com/nlohmann/json/issues/2649)
+    template<typename BasicJsonType>
+    using is_implicitly_convertible_basic_json = std::integral_constant < bool,
+        (JSON_USE_IMPLICIT_CONVERSIONS != 0)
+        || std::is_same<typename BasicJsonType::string_t, string_t>::value >;
+
+    /// tag to select the constructor that performs the conversion from another basic_json specialization
+    struct convert_basic_json_tag {};
+
+  public:
     /// @brief create a JSON value from an existing one
     /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
     template < typename BasicJsonType,
                detail::enable_if_t <
-                   detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value, int > = 0 >
+                   detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value
+                   && is_implicitly_convertible_basic_json<BasicJsonType>::value, int > = 0 >
     basic_json(const BasicJsonType& val)
+        : basic_json(val, convert_basic_json_tag{})
+    {}
+
+    /// @brief create a JSON value from an existing one
+    /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
+    template < typename BasicJsonType,
+               detail::enable_if_t <
+                   detail::is_basic_json<BasicJsonType>::value&& !std::is_same<basic_json, BasicJsonType>::value
+                   && !is_implicitly_convertible_basic_json<BasicJsonType>::value, int > = 0 >
+    explicit basic_json(const BasicJsonType& val)
+        : basic_json(val, convert_basic_json_tag{})
+    {}
+
+  private:
+    template<typename BasicJsonType>
+    basic_json(const BasicJsonType& val, convert_basic_json_tag /*unused*/)
 #if JSON_DIAGNOSTIC_POSITIONS
         : start_position(val.start_pos()),
           end_position(val.end_pos())
@@ -27626,6 +27581,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
+  public:
     /// @brief create a container (array or object) from an initializer list
     /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
     basic_json(initializer_list_t init,
@@ -27873,7 +27829,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     // other constructors and destructor //
     ///////////////////////////////////////
 
-    /// @sa https://json.nlohmann.me/api/basic_json/basic_json/
     template<typename JsonRef,
              detail::enable_if_t<detail::conjunction<detail::is_json_ref<JsonRef>,
                                  std::is_same<typename JsonRef::value_type, basic_json>>::value, int> = 0 >
@@ -28393,7 +28348,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                    int > = 0 >
     BasicJsonType get_impl(detail::priority_tag<2> /*unused*/) const
     {
-        return *this;
+        return BasicJsonType(*this);
     }
 
     /*!
@@ -28457,8 +28412,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     @throw what @ref json_serializer<ValueType> `from_json()` method throws if conversion is required
 
     @since version 2.1.0
-
-    @sa https://json.nlohmann.me/api/basic_json/get/
     */
     template < typename ValueTypeCV, typename ValueType = detail::uncvref_t<ValueTypeCV>>
 #if defined(JSON_HAS_CPP_14)
@@ -28502,8 +28455,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     @sa see @ref get_ptr() for explicit pointer-member access
 
     @since version 1.0.0
-
-    @sa https://json.nlohmann.me/api/basic_json/get/
     */
     template<typename PointerType, typename std::enable_if<
                  std::is_pointer<PointerType>::value, int>::type = 0>
@@ -28530,18 +28481,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     // specialization to allow calling get_to with a basic_json value
     // see https://github.com/nlohmann/json/issues/2175
-    /// @sa https://json.nlohmann.me/api/basic_json/get_to/
     template<typename ValueType,
              detail::enable_if_t <
                  detail::is_basic_json<ValueType>::value,
                  int> = 0>
     ValueType & get_to(ValueType& v) const
     {
-        v = *this;
+        v = ValueType(*this);
         return v;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/get_to/
     template <
         typename T, std::size_t N,
         typename Array = T (&)[N], // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
@@ -28606,7 +28555,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     @since version 1.0.0
     */
-    /// @sa https://json.nlohmann.me/api/basic_json/operator_ValueType/
     template < typename ValueType, typename std::enable_if <
                    detail::conjunction <
                        detail::negation<std::is_pointer<ValueType>>,
@@ -28879,14 +28827,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
 
     // these two functions resolve a (const) char * ambiguity affecting Clang and MSVC
     // (they seemingly cannot be constrained to resolve the ambiguity)
-    /// @sa https://json.nlohmann.me/api/basic_json/operator[]/
     template<typename T>
     reference operator[](T* key)
     {
         return operator[](typename object_t::key_type(key));
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/operator[]/
     template<typename T>
     const_reference operator[](T* key) const
     {
@@ -29096,7 +29042,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         JSON_THROW(type_error::create(306, detail::concat("cannot use value() with ", type_name()), this));
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/value/
     template < class ValueType, class BasicJsonType, detail::enable_if_t <
                    detail::is_basic_json<BasicJsonType>::value
                    && detail::is_getable<basic_json_t, ValueType>::value
@@ -29107,7 +29052,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return value(ptr.convert(), default_value);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/value/
     template < class ValueType, class BasicJsonType, class ReturnType = typename value_return_type<ValueType>::type,
                detail::enable_if_t <
                    detail::is_basic_json<BasicJsonType>::value
@@ -29487,7 +29431,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.contains(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/contains/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
@@ -30907,7 +30850,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/parse/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, parse(ptr, ptr + len))
     static basic_json parse(detail::span_input_adapter&& i,
@@ -30944,7 +30886,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return parser(detail::input_adapter(std::move(first), std::move(last)), nullptr, false, ignore_comments, ignore_trailing_commas, true).accept(true);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/accept/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, accept(ptr, ptr + len))
     static bool accept(detail::span_input_adapter&& i,
@@ -31328,7 +31269,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_cbor(ptr, ptr + len))
@@ -31340,7 +31280,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_cbor(ptr, ptr + len, strict, allow_exceptions, tag_handler);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_cbor/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_cbor(ptr, ptr + len))
     static basic_json from_cbor(detail::span_input_adapter&& i,
@@ -31396,7 +31335,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
@@ -31407,7 +31345,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_msgpack(ptr, ptr + len, strict, allow_exceptions);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_msgpack/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_msgpack(ptr, ptr + len))
     static basic_json from_msgpack(detail::span_input_adapter&& i,
@@ -31462,7 +31399,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_ubjson(ptr, ptr + len))
@@ -31473,7 +31409,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_ubjson(ptr, ptr + len, strict, allow_exceptions);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_ubjson/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_ubjson(ptr, ptr + len))
     static basic_json from_ubjson(detail::span_input_adapter&& i,
@@ -31602,7 +31537,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return result;
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
     template<typename T>
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_bson(ptr, ptr + len))
@@ -31613,7 +31547,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return from_bson(ptr, ptr + len, strict, allow_exceptions);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/from_bson/
     JSON_HEDLEY_WARN_UNUSED_RESULT
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, from_bson(ptr, ptr + len))
     static basic_json from_bson(detail::span_input_adapter&& i,
@@ -31646,7 +31579,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_unchecked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     reference operator[](const ::nlohmann::json_pointer<BasicJsonType>& ptr)
@@ -31661,7 +31593,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_unchecked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/operator%5B%5D/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     const_reference operator[](const ::nlohmann::json_pointer<BasicJsonType>& ptr) const
@@ -31676,7 +31607,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_checked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/at/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     reference at(const ::nlohmann::json_pointer<BasicJsonType>& ptr)
@@ -31691,7 +31621,6 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return ptr.get_checked(this);
     }
 
-    /// @sa https://json.nlohmann.me/api/basic_json/at/
     template<typename BasicJsonType, detail::enable_if_t<detail::is_basic_json<BasicJsonType>::value, int> = 0>
     JSON_HEDLEY_DEPRECATED_FOR(3.11.0, basic_json::json_pointer or nlohmann::json_pointer<basic_json::string_t>) // NOLINT(readability/alt_tokens)
     const_reference at(const ::nlohmann::json_pointer<BasicJsonType>& ptr) const

tests/src/unit-alt-string.cpp

@@ -13,6 +13,7 @@
 
 #include <cstdint>
 #include <string>
+#include <type_traits>
 #include <utility>
 #include <vector>
 
@@ -374,4 +375,39 @@ TEST_CASE("alternative string type")
         const auto j2 = j.flatten();
         CHECK(j2.dump() == R"({"/foo/0":"bar","/foo/1":"baz"})");
     }
+
+    SECTION("conversion between basic_json specializations (#2649)")
+    {
+        // explicit conversions are always possible
+        CHECK(std::is_constructible<nlohmann::json, alt_json>::value);
+        CHECK(std::is_constructible<alt_json, nlohmann::json>::value);
+        CHECK(std::is_constructible<nlohmann::json, nlohmann::ordered_json>::value);
+        CHECK(std::is_constructible<nlohmann::ordered_json, nlohmann::json>::value);
+
+        // specializations with the same string type are implicitly convertible
+        CHECK(std::is_convertible<nlohmann::ordered_json, nlohmann::json>::value);
+        CHECK(std::is_convertible<nlohmann::json, nlohmann::ordered_json>::value);
+
+        // specializations with different string types are only implicitly convertible
+        // if implicit conversions are enabled
+#if JSON_USE_IMPLICIT_CONVERSIONS
+        CHECK(std::is_convertible<alt_json, nlohmann::json>::value);
+        CHECK(std::is_convertible<nlohmann::json, alt_json>::value);
+#else
+        CHECK_FALSE(std::is_convertible<alt_json, nlohmann::json>::value);
+        CHECK_FALSE(std::is_convertible<nlohmann::json, alt_json>::value);
+#endif
+
+        // get<BasicJsonType>() works in either case
+        const nlohmann::json j = {{"foo", 1}, {"bar", true}};
+        CHECK(j.get<nlohmann::ordered_json>() == nlohmann::ordered_json(j));
+        // (only a number is converted here, as objects and strings are affected by #3425)
+        CHECK(nlohmann::json(42).get<alt_json>() == 42);
+        CHECK(alt_json(nlohmann::json(42)) == 42);
+
+        // get_to() also works in either case
+        alt_json a;
+        nlohmann::json(42).get_to(a);
+        CHECK(a == 42);
+    }
 }

tests/src/unit-msgpack.cpp

@@ -2208,8 +2208,11 @@ TEST_CASE("MessagePack Size above uint32 for array")
     auto& array = j.get_ref<huge_array_json::array_t&>();
     array.fake_size = true;
 
+    // write into a caller-owned vector: to_msgpack(j) reserves space based on
+    // the (faked) element count, which fails with bad_alloc on Windows
+    std::vector<std::uint8_t> result;
     CHECK_THROWS_WITH_AS(
-        huge_array_json::to_msgpack(j),
+        huge_array_json::to_msgpack(j, result),
         "[json.exception.out_of_range.412] MessagePack length 4294967296 exceeds maximum of 4294967295",
         json::out_of_range&);
 
@@ -2261,8 +2264,11 @@ TEST_CASE("MessagePack Size above uint32 for object")
     auto& object = j.get_ref<huge_object_json::object_t&>();
     object.fake_size = true;
 
+    // write into a caller-owned vector: to_msgpack(j) reserves space based on
+    // the (faked) element count, which fails with bad_alloc on Windows
+    std::vector<std::uint8_t> result;
     CHECK_THROWS_WITH_AS(
-        huge_object_json::to_msgpack(j),
+        huge_object_json::to_msgpack(j, result),
         "[json.exception.out_of_range.412] MessagePack length 4294967296 exceeds maximum of 4294967295",
         json::out_of_range&);
 

tools/api_checker/POLICY.md

@@ -1,127 +0,0 @@
-# Public API Policy
-
-This document defines what counts as the **public API** of nlohmann/json for the purposes of the
-`tools/api_checker/` tooling, what stability is (and is not) guaranteed, and how API changes are
-classified as breaking or feature additions. It exists so that "public API" is a checkable, mechanical
-property of the source, not a matter of convention or memory — see
-[Discussion #3691](https://github.com/nlohmann/json/discussions/3691) for the original motivation.
-
-## What counts as public API
-
-The public API surface is derived from C++ semantics (class templates, access specifiers, namespace
-scoping) by `extract_api.py`, not from the presence of documentation. It consists of:
-
-1. **Public members of six class templates**: `basic_json`, `adl_serializer`,
-   `byte_container_with_subtype`, `json_pointer`, `json_sax`, `ordered_map`. Specifically, the *primary
-   template definition* (`CLASS_TEMPLATE` cursor with `is_definition() == True`) — never an implicit
-   instantiation, which silently drops SFINAE-guarded overloads. Two tiers apply:
-   - **Callable tier** (methods, constructors, destructors, conversion operators, function templates):
-     every public callable requires its own `@sa` documentation link, without exception.
-   - **Type tier** (public type aliases): requires `@sa`, except for a fixed exemption list of
-     STL-container named-requirement aliases that mirror standard-library conventions rather than being
-     independently documented: `value_type`, `reference`, `const_reference`, `pointer`, `const_pointer`,
-     `iterator`, `const_iterator`, `reverse_iterator`, `const_reverse_iterator`, `difference_type`,
-     `size_type`, `allocator_type`, `key_type`, `mapped_type`. This list is defined once, in
-     `extract_api.py`'s `stl_exempt` set, and referenced here rather than duplicated.
-2. **Free functions and operators in `nlohmann::`**, including `nlohmann::literals::json_literals`
-   (the `operator""_json` / `operator""_json_pointer` user-defined literals). Comparison and stream
-   operators on `basic_json` and `json_pointer`, `operator/`, `swap`.
-3. **The six alias-exposed exception types**: `basic_json::exception`, `parse_error`,
-   `invalid_iterator`, `type_error`, `out_of_range`, `other_error`. These are public `TYPE_ALIAS_DECL`s
-   in `basic_json` (e.g. `using exception = detail::exception;`) whose underlying class is physically
-   defined in `nlohmann::detail::exceptions.hpp`. `extract_api.py` follows the alias to find the `@sa` on
-   the underlying `detail::` class definition, since that's where the existing documentation convention
-   places it. Each exception class is documented as *one page* — its individual members (`what()`, `id`)
-   are not separately tracked, matching the existing one-page-per-class convention.
-4. **Macros**, governed separately by `docs/mkdocs/docs/api/macros/` (the curated list of ~30 pages is
-   authoritative) and cross-checked, advisory-only, by `check_macros.py`. See "Known limitations" below
-   for why macros can't be checked the same way as everything else.
-
-## What's excluded
-
-- **Everything in `nlohmann::detail::`**, with the one narrow exception above (exception-type aliases).
-  **No stability is guaranteed for any symbol in the `detail::` namespace — clients must not rely on it**,
-  regardless of whether a given `detail::` symbol happens to be reachable from user code today. This is
-  an explicit, deliberate policy, not an oversight.
-- **Private and protected members**, even of the six tracked classes. `extract_api.py` walks non-public
-  members only to check they don't carry a stray `@sa` (a documentation leak) — never to add them to the
-  public surface.
-- **The ABI inline-namespace segment** (`json_abi_v3_12_0`, `json_abi_diag_v3_12_0`, etc. — see
-  [docs/mkdocs/docs/features/namespace.md](../../docs/mkdocs/docs/features/namespace.md)). This is a
-  version-tag identity concern for `diff_api.py` (it must not make every release look like the entire API
-  was removed and re-added), not a scoping or visibility concern — the symbols inside it are public or
-  not independent of the tag.
-
-## Breaking vs. feature classification
-
-`diff_api.py` compares the `public_api` surface of two snapshots using an overload-disambiguating
-identity — `(scope, identity_name, kind, signature)`, where `signature` is the declaration's own
-source text (return type, name, parameter list, trailing qualifiers; comments and constructors'
-member-initializer-lists stripped). This is the third identity scheme this tooling has used; the
-first two were each found broken by testing against real release tags, not by inspection — see
-`extract_api.py`'s `identity_key()` docstring for the full history (a naive params-only key silently
-collided on overloads differing only by constness/SFINAE; libclang's USR fixed that but encoded the
-*enclosing class template's own arity*, so a single backward-compatible template-parameter addition
-made ~228 of 330 `basic_json` entries look "changed" between two real releases with zero actual
-breaking changes among them).
-
-- An identity present only in the **new** snapshot → **feature** (addition).
-- An identity present only in the **old** snapshot → **breaking** (removal).
-- The same `(scope, name)` with one identity removed and a different one added → reported as a
-  **changed overload**, classified breaking by default. No automatic overload-compatibility reasoning
-  is attempted — whether a signature change is source-compatible is a judgment call for a human
-  reviewer, not a sound problem for a CI tool to solve unsupervised.
-
-## Stable per-release API history
-
-`tools/api_checker/history/<tag>.json` holds one immutable, committed API-surface record per
-released `v3.*` tag (captured via `snapshot_release.py`; see `tools/api_checker/README.md` and
-`tools/api_checker/history/README.md`). `diff_api.py` reads from here automatically when a ref
-matches a stored file, instead of live-extracting via `git archive` every time.
-
-Every surface file (the live `api_surface.json` and every `history/*.json` record) carries a
-`format_version` integer. **Bump it whenever a change to the schema, or to the identity-computing
-algorithm (`get_signature_text()`/`get_identity_name()`/`identity_key()` in `extract_api.py`), could
-alter the `signature` or `identity_name` text for otherwise-unchanged source.** `diff_api.py` refuses
-by default to compare two surfaces with different `format_version` values — this is a direct,
-mechanical safeguard against the exact class of bug that motivated the current identity scheme (see
-above): a silent algorithm change corrupting every historical comparison with no way to detect it.
-An explicit `--allow-format-mismatch` flag exists for a deliberate, informed comparison anyway.
-
-Practical implication for anyone changing `extract_api.py`'s identity logic: bump
-`SURFACE_FORMAT_VERSION`, and treat every already-committed `history/*.json` file as needing a
-`--force` regeneration (reviewed, not blind) before it can be meaningfully compared against surfaces
-produced by the new algorithm version.
-
-## Stability guarantees
-
-This tooling makes the project's existing commitments *mechanically checkable* — it does not introduce a
-new promise:
-
-- `ChangeLog.md` states the project "adheres to [Semantic Versioning](http://semver.org/)."
-- [docs/mkdocs/docs/home/releases.md](../../docs/mkdocs/docs/home/releases.md) marks every 3.x release "All
-  changes are backward-compatible" (except 3.0.0 itself, a major bump with a migration guide).
-- `tests/abi/` provides a complementary, narrower guarantee: ABI/link compatibility *within one ABI tag*.
-  That is a binary-compatibility concern; this tooling's concern is source/API-level — a symbol can be
-  ABI-stable and still be a source-breaking change (e.g. a removed overload), or vice versa.
-
-## Known limitations
-
-- **Macros have no C++ access-specifier concept**, so the public/private test that works for classes
-  doesn't transfer. Only a minority of documented macro `#define`s have an attached `@sa`-style comment
-  (the `#ifndef X / #define X value #endif` idiom has no natural comment-attachment point), and internal
-  helper macros live in the same files as public configuration macros, so no path-based exclusion works
-  either. `check_macros.py` therefore only checks one direction: that every documented macro still has a
-  matching `#define` somewhere under `include/nlohmann/` (catches stale/renamed doc pages). It does
-  **not** attempt to detect undocumented macros — no reliable signal exists for that direction with the
-  current codebase conventions, and this tool doesn't pretend otherwise.
-- **`diff_api.py` does not track exception specifications or template-parameter-only changes.** A
-  function whose `noexcept` status changes, or whose template parameter list changes without altering
-  its externally-visible identity, will not be flagged.
-- **Known API-hygiene gap, surfaced by this tooling rather than fixed**:
-  `basic_json::insert_iterator` (a `public` member per C++ access rules) is a helper used internally by
-  `insert()`; its own source comment calls it "Helper for insertion of an iterator." It has no
-  documentation page and is deliberately left undocumented rather than either speculatively documented or
-  silently exempted — this is exactly the class of undocumented-and-probably-shouldn't-be-public symbol
-  this tooling exists to surface, per the motivating discussion. A future PR may reclassify it as private
-  as a (breaking, ABI-relevant) cleanup; that is out of scope here.

tools/api_checker/README.md

@@ -1,393 +0,0 @@
-# API Checker Tools
-
-Tooling to extract, validate, and track changes to the public API surface of nlohmann/json.
-
-## Overview
-
-These tools use libclang AST parsing to programmatically derive "the public API" from C++ semantics
-(class templates, access specifiers, namespace scoping) — independently of documentation status. The
-extracted surface is the source of truth for what is considered "public API." On top of this, the tools
-verify that every public entity carries a documentation link and detect API changes between releases.
-A per-release historical record lives in [`history/`](history/README.md), one file per tagged `v3.*`
-release, so past API changes can be derived without re-running libclang against old git refs.
-
-See [POLICY.md](POLICY.md) for the full definition of what counts as public API, what's excluded, how
-breaking vs. feature changes are classified, and known limitations.
-
-## Installation
-
-Install dependencies:
-
-```bash
-pip install -r tools/api_checker/requirements.txt
-```
-
-Requires:
-- Python 3.7+
-- libclang 18.1.1 (installed via pip)
-- clang++ or clang (system package, for include-path discovery only — does not need to
-  version-match the pinned libclang wheel)
-
-## Tools
-
-### extract_api.py
-
-Extract the public API surface by parsing C++ AST using libclang. Produces two different outputs for
-two different consumers — see "Two outputs, one extraction pass" below for why.
-
-**Usage:**
-```bash
-python3 tools/api_checker/extract_api.py \
-  --header include/nlohmann/json.hpp \
-  --include include \
-  --output api_snapshot.json \
-  --surface-output api_surface.json
-```
-
-**Options:**
-- `--header PATH` — Header file to analyze (default: `include/nlohmann/json.hpp`)
-- `--include PATH` — Include directory for parsing (default: `include`)
-- `--output PATH` — Full snapshot output (location + doc status; default: `api_snapshot.json`)
-- `--surface-output PATH` — Minimal surface output (identity only; omit to skip)
-- `--extra-isystem PATH` — Extra `-isystem` include path (repeatable), in case system-include
-  discovery via `clang++ -E -v` ever fails on a given runner image
-- `--self-test` — Run self-tests and exit (validates ABI-tag stripping)
-
-**How it works:**
-Parses the header file using libclang with `PARSE_DETAILED_PROCESSING_RECORD`, discovers system
-includes via `clang++ -E -x c++ -v /dev/null`, and walks the AST:
-
-1. For each of the 6 public class templates (`basic_json`, `adl_serializer`, `byte_container_with_subtype`,
-   `json_pointer`, `json_sax`, `ordered_map`): locate the `CLASS_TEMPLATE` cursor with `is_definition() == True`
-   — never a `CLASS_DECL` implicit instantiation, which silently drops SFINAE-guarded overloads
-2. Extract public members: `CXX_METHOD`, `CONSTRUCTOR`, `DESTRUCTOR`, `CONVERSION_FUNCTION`, `FUNCTION_TEMPLATE`
-   (callable tier — strict `@sa` requirement), and `TYPE_ALIAS_DECL` (type tier — with STL-container exemptions)
-3. Extract free functions in `nlohmann::` namespace (excluding `detail::` and `std::`)
-4. Normalize away ABI inline-namespace (regex `::json_abi[a-z_]*_v\d+_\d+_\d+` → `::`)
-5. Use overload-disambiguating identity keys built from raw source-text signature capture,
-   ABI-tag-stripped — see "Identity keys" below
-
-**Two outputs, one extraction pass:**
-- `--output` (full snapshot): each entry carries `location` (file:line) and documentation status
-  (`doc_url`, `has_sa`). Consumed by `check_docs.py`. **Not meant to be committed** — `location` shifts
-  on any unrelated code edit and `doc_url` changes when doc pages move, so a diff of this file mixes real
-  API changes with pure noise.
-- `--surface-output` (minimal surface): each entry has only `scope`, `kind`, `name`, `identity_name`,
-  `tier`, `signature`, and `pretty_signature` — nothing that can change without the API itself changing.
-  **This is the file that gets committed** (`tools/api_checker/api_surface.json` for the current
-  working tree, `tools/api_checker/history/<tag>.json` per released tag) and diffed by `diff_api.py`.
-
-**Identity keys — three approaches were tried and rejected before arriving at the current one:**
-1. `{scope, name, kind, params}` from `cursor.get_arguments()`: silently collided for any overload set
-   differentiated only by constness, ref-qualifiers, or SFINAE constraints rather than parameter types —
-   confirmed empirically: `basic_json`'s two zero-argument `get()` overloads (one `const`, one not) both
-   produced `params=[]` and silently overwrote each other. A full scan found **59 such silent overwrites
-   across 27 colliding names**.
-2. libclang's USR: correctly disambiguates every overload (it encodes the full mangled signature) — but
-   *also* encodes the enclosing class template's own arity into every member's USR. Confirmed
-   empirically against real release tags: `basic_json` gaining one new defaulted template parameter
-   between v3.11.2 and v3.11.3 (a backward-compatible change) changed literally every member's USR,
-   which made `diff_api.py` report **228 of 330 entries as "changed"** for a release with zero real
-   breaking changes among them.
-3. **Current approach**: raw source-text signature capture — `identity = (scope, identity_name, kind,
-   signature)`, where `signature` is the declaration's own text (return type, name, parameter list,
-   trailing cv/ref/noexcept qualifiers; comments and constructors' member-initializer-lists stripped;
-   stops before the function body) read directly via the cursor's byte-offset extent. This is what's
-   actually written in source — declared names like `ValueType`, never a resolved
-   `basic_json<T0,...,T10>` — so it's immune to the class-arity problem above. Verified by manually
-   cross-referencing every "added"/"removed"/"changed" entry in three real release-to-release diffs
-   (v3.11.2→v3.11.3, v3.11.3→v3.12.0, v3.12.0→HEAD) against the actual `git diff` of the source — every
-   one confirmed genuine. Full details, including several further edge-case fixes found the same way
-   (a libclang tokenizer gap, comment-stripping, constructor-name arity-poisoning), are in
-   `extract_api.py`'s `identity_key()`/`get_signature_text()` docstrings.
-
-**Output (full snapshot, from `--output`):**
-```json
-{
-  "meta": {
-    "extracted_from": "include/nlohmann/json.hpp"
-  },
-  "public_api": {
-    "<opaque internal key, not meant to be read>": {
-      "scope": "nlohmann::basic_json",
-      "name": "parse",
-      "identity_name": "parse",
-      "kind": "CXX_METHOD",
-      "tier": "callable",
-      "signature": "static basic_json parse ( InputType && i , ... )",
-      "location": "include/nlohmann/json.hpp:4104",
-      "doc_url": "https://json.nlohmann.me/api/basic_json/parse/",
-      "has_sa": true,
-      "pretty_signature": "nlohmann::basic_json::parse"
-    }
-  },
-  "documented_non_public": []
-}
-```
-
-`documented_non_public` lists entities **not** part of the public surface (private/protected members of
-the six tracked classes) that surprisingly carry an `@sa` URL into the documentation site
-(`https://json.nlohmann.me/`) — a genuine documentation leak. `@sa` links to anything else, such as GitHub
-issues, are ignored. It does not list public entries that merely lack `@sa`; that's `check_docs.py`'s job.
-
-**Output (surface, from `--surface-output`):**
-```json
-{
-  "format_version": 1,
-  "meta": {
-    "extracted_from": "include/nlohmann/json.hpp"
-  },
-  "public_api": [
-    {
-      "scope": "nlohmann::basic_json",
-      "kind": "CXX_METHOD",
-      "name": "parse",
-      "identity_name": "parse",
-      "tier": "callable",
-      "signature": "static basic_json parse ( InputType && i , parser_callback_t cb = nullptr , const bool allow_exceptions = true , const bool ignore_comments = false )",
-      "pretty_signature": "nlohmann::basic_json::parse"
-    }
-  ]
-}
-```
-
-A flat, sorted list of self-describing records — `signature`/`identity_name` are the same values
-`identity_key()` joins into one opaque internal string, exposed here as explicit fields so the file is
-readable and diffable by inspection, not just by tooling. `identity_name` differs from `name` only for
-constructors/destructors (a canonical `"(constructor)"`/`"(destructor)"` placeholder — see
-`get_identity_name()`'s docstring for why `cursor.spelling` isn't used directly there).
-
-`format_version` guards against a future change to this schema or to the identity-computing algorithm
-silently corrupting a comparison against an older stored surface — bump it whenever such a change could
-alter `signature`/`identity_name` text for otherwise-unchanged source (see `diff_api.py`).
-
-### check_docs.py
-
-Verify that all public API entries have valid documentation links and that no non-public entities
-carry `@sa` comments.
-
-**Usage:**
-```bash
-python3 tools/api_checker/check_docs.py --snapshot api_snapshot.json
-```
-
-**Options:**
-- `--snapshot PATH` — Full API snapshot JSON file from `extract_api.py --output` (default: `api_snapshot.json`)
-
-**How it works:**
-Two-pass validation over the extracted snapshot:
-
-1. For every `public_api` entry (callable tier, and type tier minus STL exemptions): flag if missing `@sa`,
-   flag if `@sa` URL doesn't resolve to an existing documentation file (following `docs/mkdocs/mkdocs.yml`'s
-   `redirect_maps` when a page has moved, and trying the class-overview conventions used by different
-   classes — flat `<class>.md`, nested `<class>/<class>.md`, nested `<class>/index.md`)
-2. For every `documented_non_public` entry: flag as unexpected `@sa` on a non-public entity
-
-**Output:**
-Prints warnings for each issue, categorized by rule:
-- `docs/missing_sa_comment` — public API without `@sa` documentation link
-- `docs/missing_doc_file` — `@sa` URL points to non-existent `.md` file
-- `docs/invalid_sa_url` — malformed `@sa` URL
-- `docs/sa_on_non_public` — unexpected `@sa` on a non-public entity
-
-Exits with status 0 if all checks pass, 1 if issues found.
-
-### diff_api.py
-
-Compare the public API surface between two refs and classify changes as feature (added) or
-breaking (removed / changed overload).
-
-**Usage:**
-```bash
-python3 tools/api_checker/diff_api.py --old v3.12.0 --new HEAD
-python3 tools/api_checker/diff_api.py --old v3.11.2 --new v3.11.3          # both resolved from history/
-python3 tools/api_checker/diff_api.py --old v3.12.0 --new HEAD --fail-on-breaking
-python3 tools/api_checker/diff_api.py --old-file a.json --new-file b.json  # compare two files directly
-```
-
-**Options:**
-- `--old REF` / `--new REF` — Refs to compare (tags, branches, commits). `--new` defaults to `HEAD`.
-  Each is resolved by checking `tools/api_checker/history/<ref>.json` first (fast — no libclang or
-  git-archive needed), falling back to live extraction if no matching file exists there.
-- `--old-file PATH` / `--new-file PATH` — Load an arbitrary surface JSON file directly, bypassing
-  both git and `tools/api_checker/history/`. Mutually exclusive with `--old`/`--new` respectively.
-- `--no-history` — Force live extraction even when a matching `tools/api_checker/history/<ref>.json`
-  exists. Useful to check that a stored record is still faithful to a fresh run of the current tool.
-- `--allow-format-mismatch` — Proceed even if the two surfaces have different `format_version`
-  (otherwise `diff_api.py` refuses — see below).
-- `--header PATH` / `--include PATH` — For live extraction only (default:
-  `include/nlohmann/json.hpp` / `include`)
-- `--fail-on-breaking` — Exit with status 1 if breaking changes are detected
-
-**How it works:**
-For a ref not found in `tools/api_checker/history/`, checks out the **full `include/` tree** at
-that ref into a temp directory via `git archive` (a single-file checkout of `json.hpp` is not
-enough — it `#include`s dozens of other headers that must exist at the same ref), then runs the
-*current* `extract_api.py --surface-output` against it. Diffs the two surfaces by identity
-(`scope`, `identity_name`, `kind`, `signature`):
-- Identity only in the new surface → **feature**.
-- Identity only in the old surface → **breaking** (removed).
-- Same `(scope, name)` with a removed identity and an added identity → grouped as a **changed
-  overload**, breaking by default. No automatic overload-compatibility reasoning is attempted — a
-  human judges whether the change is actually source-compatible.
-
-Before diffing, the two surfaces' `format_version` fields are compared; a mismatch aborts with an
-error (override with `--allow-format-mismatch`) rather than silently producing an unsound diff — see
-`extract_api.py`'s `SURFACE_FORMAT_VERSION` docstring for the incident that motivated this guard.
-
-ABI-tag stripping is inherited automatically since both extractions go through the same
-`extract_api.py`.
-
-**Use case:** Run before cutting a release to verify the changelog correctly categorizes changes as
-breaking vs. features.
-
-### snapshot_release.py
-
-Capture an immutable, per-release API surface record into `tools/api_checker/history/<tag>.json`.
-This is what makes `diff_api.py` fast for released tags — see "How it works" above.
-
-**Usage:**
-```bash
-python3 tools/api_checker/snapshot_release.py --ref v3.12.0
-python3 tools/api_checker/snapshot_release.py --ref v3.11.0 --ref v3.12.0   # repeatable
-python3 tools/api_checker/snapshot_release.py --all-tags                    # every v3.* tag
-python3 tools/api_checker/snapshot_release.py --ref v3.12.0 --force         # overwrite an existing record
-```
-
-**Options:**
-- `--ref REF` — Git tag to snapshot; repeatable
-- `--all-tags` — Snapshot every `v3.*` tag (existing files are skipped unless `--force`)
-- `--output-dir PATH` — Where to write (default: `tools/api_checker/history/`)
-- `--force` — Overwrite an existing history file. History files are immutable by convention —
-  only pass this for a deliberate, reviewed regeneration; review the resulting diff before
-  committing
-- `--header PATH` / `--include PATH` — Same as `diff_api.py`'s live-extraction options
-
-**How it works:** Reuses `diff_api.py`'s `extract_surface_for_ref()` for the git-archive-and-extract
-work, then adds `generated_at`/`generator` provenance and writes the result to
-`tools/api_checker/history/<ref>.json`. Given multiple refs (or `--all-tags`), does **not** abort
-the batch on one failing ref — collects failures and prints a summary at the end, so one
-unparseable old tag doesn't block backfilling the releases that do work. See
-`tools/api_checker/history/README.md` for the currently-known gaps (pre-restructuring tags that
-predate the `include/nlohmann/` layout entirely).
-
-**Not CI-automated** — this is a manual step in the release checklist (see below), by design.
-
-### check_macros.py
-
-Advisory-only cross-check between documented macros and their `#define`/reference sites. **Never blocks
-CI**, regardless of findings.
-
-**Usage:**
-```bash
-python3 tools/api_checker/check_macros.py
-```
-
-**Options:**
-- `--macros-dir PATH` — Directory of macro doc pages (default: `docs/mkdocs/docs/api/macros`)
-- `--include-dir PATH` — Directory to search for `#define`/reference sites (default: `include/nlohmann`)
-
-**How it works:**
-For each `.md` page under `docs/mkdocs/docs/api/macros/` (excluding `index.md`), extracts the macro
-name(s) from the H1 heading — handling both plain single-macro headings and multi-line HTML headings
-that list a family of related macros (e.g. the `NLOHMANN_DEFINE_DERIVED_TYPE_*` family) — then checks
-whether each name is defined **or referenced** (`#define`, `#ifdef`, `#ifndef`, `defined(...)`) anywhere
-under `include/nlohmann/`. Referenced-but-not-defined is deliberately accepted: macros like
-`JSON_NOEXCEPTION` or `JSON_THROW_USER` are user-supplied overrides that the library only checks for,
-never defines itself.
-
-Only checks the documented-macro-still-exists direction (catches stale/renamed doc pages). Does **not**
-check the converse (undocumented macros) — see [POLICY.md](POLICY.md)'s "Known limitations" for why.
-
-## Continuous Integration
-
-A GitHub Actions workflow (`.github/workflows/check_api_docs.yml`) runs on every pull request:
-
-1. Installs `clang` (system package, for include discovery) and Python dependencies
-2. Runs `extract_api.py`, regenerating both the ephemeral full snapshot and the tracked
-   `tools/api_checker/api_surface.json`
-3. Runs `check_docs.py` — **Phase 1: advisory** (`continue-on-error: true`), surfacing the doc backlog
-   without failing the job while it's burned down. Will flip to blocking once the backlog is cleared.
-4. Runs `check_macros.py` — always advisory
-5. Diffs `tools/api_checker/api_surface.json` against the regenerated copy — **blocking from the start**
-   (unlike the doc-backlog check, this is purely mechanical regeneration with no backlog to phase in,
-   matching the precedent set by `check_amalgamation.yml`). Uploads a patch artifact if it differs, so
-   contributors can `git apply` it instead of installing libclang locally.
-
-## Workflow: Adding New Public API
-
-1. Add the new public method/function to the header
-2. Add a `/// @sa https://json.nlohmann.me/api/<class>/<member>/` comment above it
-3. Create the corresponding documentation page at `docs/mkdocs/docs/api/<class>/<member>.md` and a
-   `mkdocs.yml` nav entry
-4. Regenerate and commit the tracked surface file:
-   ```bash
-   python3 tools/api_checker/extract_api.py --surface-output tools/api_checker/api_surface.json
-   git add tools/api_checker/api_surface.json
-   ```
-5. Push your PR — CI verifies both the doc link and that the surface file is up to date
-
-## Workflow: Release Checklist
-
-Before cutting a release:
-
-```bash
-# Diff current API against the previous release
-python3 tools/api_checker/diff_api.py --old v3.12.0 --new HEAD
-
-# Review the output to verify the changelog correctly categorizes breaking vs. feature changes
-```
-
-After tagging the release:
-
-```bash
-# Capture and commit the new tag's API surface, so future diffs against it hit the fast,
-# stored-file path instead of live-extracting every time. A manual step, not CI-automated.
-python3 tools/api_checker/snapshot_release.py --ref v3.13.0
-git add tools/api_checker/history/v3.13.0.json
-```
-
-## Troubleshooting
-
-**libclang not found:**
-```
-Error: Could not locate libclang library
-```
-→ Ensure libclang is installed: `python3 -m pip install libclang==18.1.1`
-
-**Parse errors in header:**
-```
-Parse errors encountered:
-  ... list of diagnostics ...
-```
-→ Check that system includes can be discovered. Run `clang++ -E -x c++ -v /dev/null` and verify
-the output includes a section titled `#include <...> search starts here:` with system paths.
-If include discovery fails, use `--extra-isystem PATH` to provide additional paths.
-
-**No API entries extracted (or very few):**
-- Check that the header file exists and is valid C++: `ls -la include/nlohmann/json.hpp`
-- Verify that no parse errors occur above
-- Confirm that you're targeting a `CLASS_TEMPLATE` definition, not an implicit instantiation
-  (the tool logs `Found N public API entries` — a zero or very small count suggests the wrong cursor kind)
-
-**Doc link returns 404:**
-- Verify the file exists at the expected path: `docs/mkdocs/docs/api/<class>/<member>.md`
-- Check for URL encoding issues (e.g., `operator[]` → `operator%5B%5D`)
-- Verify the URL structure in the `@sa` comment: should be `https://json.nlohmann.me/api/<path>/`
-- Check `docs/mkdocs/mkdocs.yml`'s `redirect_maps` if the page has moved
-
-**`tools/api_checker/api_surface.json` is out of date in CI:**
-→ Regenerate and commit it: `python3 tools/api_checker/extract_api.py --surface-output tools/api_checker/api_surface.json`
-
-**`diff_api.py` refuses with "format_version mismatch":**
-→ One side is a stored surface (live `api_surface.json` or a `tools/api_checker/history/*.json`
-file) captured with an older/newer version of `extract_api.py`'s identity-computing algorithm than
-the other side. Comparing them directly could produce an unsound diff (this is exactly the failure
-mode that motivated adding the check — see `extract_api.py`'s `SURFACE_FORMAT_VERSION` docstring).
-Either regenerate the older side with the current tool, or pass `--allow-format-mismatch` if you
-understand the risk and want to proceed anyway.
-
-## Contributing
-
-Report bugs or suggest improvements to [Discussion #3691](https://github.com/nlohmann/json/discussions/3691).
-Read [POLICY.md](POLICY.md) first for the definition of public API this tooling enforces.

tools/api_checker/check_docs.py

@@ -1,185 +0,0 @@
-#!/usr/bin/env python3
-"""
-Verify that public API entries have documentation links.
-
-Consumes an API snapshot from extract_api.py and checks:
-1. Every public callable/type-tier entry has an @sa comment (with exceptions)
-2. Every @sa URL resolves to an existing documentation file
-3. No @sa comments appear on non-public entities
-"""
-
-import argparse
-import json
-import os
-import re
-# subprocess is only called with fixed argument lists, never through a shell.
-import subprocess  # nosec B404
-import sys
-from urllib.parse import unquote
-
-warnings = 0
-
-# STL-container-named-requirement aliases that are exempt from @sa requirement
-STL_EXEMPT = {'value_type', 'reference', 'const_reference', 'pointer', 'const_pointer',
-              'iterator', 'const_iterator', 'reverse_iterator', 'const_reverse_iterator',
-              'difference_type', 'size_type', 'allocator_type', 'key_type', 'mapped_type'}
-
-
-def get_repo_root():
-    """Find the repository root via git, so this script works regardless of invoking CWD."""
-    try:
-        result = subprocess.run(  # nosec B603 B607
-            ['git', 'rev-parse', '--show-toplevel'],
-            capture_output=True, text=True, check=True, timeout=10
-        )
-        return result.stdout.strip()
-    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
-        return os.getcwd()
-
-
-REPO_ROOT = get_repo_root()
-MKDOCS_YML = os.path.join(REPO_ROOT, 'docs', 'mkdocs', 'mkdocs.yml')
-
-
-def load_redirect_map() -> dict:
-    """
-    Parse the redirect_maps block of docs/mkdocs/mkdocs.yml: {old_relative_path: new_relative_path}.
-
-    mkdocs' redirect plugin lets a doc page move without breaking existing @sa URLs -- e.g.
-    'api/basic_json/operator_ltlt.md' redirects to the real file at 'api/operator_ltlt.md'.
-    Without consulting this map, url_to_docfile() would flag every redirected URL as a broken link.
-    """
-    if not os.path.exists(MKDOCS_YML):
-        return {}
-    with open(MKDOCS_YML) as f:
-        content = f.read()
-    redirect_map = {}
-    for m in re.finditer(r"^\s*'([^']+\.md)':\s*(\S+\.md)\s*$", content, re.MULTILINE):
-        redirect_map[m.group(1)] = m.group(2)
-    return redirect_map
-
-
-REDIRECT_MAP = load_redirect_map()
-
-
-def report(rule: str, location: str, description: str):
-    """Report a documentation issue."""
-    global warnings
-    warnings += 1
-    print(f'{warnings:3}. {location}:  {description} [{rule}]')
-
-
-def url_to_docfile(url: str) -> str | None:
-    """Convert @sa URL to the documentation file it resolves to, following mkdocs redirects."""
-    if not url:
-        return None
-
-    # Extract path after /api/
-    match = re.search(r'/api/(.+?)/?$', url)
-    if not match:
-        return None
-
-    # URL-decode each path component
-    path_parts = [unquote(part) for part in match.group(1).split('/')]
-    relative_path = 'api/' + '/'.join(path_parts) + '.md'
-
-    docs_root = os.path.join(REPO_ROOT, 'docs', 'mkdocs', 'docs')
-    direct_path = os.path.join(docs_root, relative_path)
-
-    # Class-overview URLs (a single path segment after /api/, e.g. ".../api/json_pointer/")
-    # use inconsistent on-disk conventions across classes: ordered_map.md is a flat file,
-    # byte_container_with_subtype/byte_container_with_subtype.md nests under a same-named
-    # file, json_pointer/index.md nests under index.md. Try all observed conventions.
-    candidates = [direct_path]
-    if len(path_parts) == 1:
-        stem = path_parts[0]
-        candidates.append(os.path.join(docs_root, 'api', stem, 'index.md'))
-        candidates.append(os.path.join(docs_root, 'api', stem, stem + '.md'))
-
-    redirected = REDIRECT_MAP.get(relative_path)
-    if redirected:
-        candidates.append(os.path.join(docs_root, redirected))
-
-    for candidate in candidates:
-        if os.path.exists(candidate):
-            return candidate
-
-    # Nothing resolved -- return the direct path so the caller reports a meaningful "missing" location.
-    return direct_path
-
-
-def check_docs(snapshot_path: str):
-    """Check documentation for all API entries."""
-    if not os.path.exists(snapshot_path):
-        print(f"Error: Snapshot file not found: {snapshot_path}")
-        sys.exit(1)
-
-    with open(snapshot_path, 'r') as f:
-        data = json.load(f)
-
-    api = data.get('public_api', {})
-    documented_non_public = data.get('documented_non_public', [])
-
-    print(f"Checking documentation for {len(api)} API entries...")
-    print(120 * "-")
-
-    # Check public API entries
-    for _identity_key, entry in sorted(api.items()):
-        location = entry.get('location', 'unknown')
-        name = entry.get('name', '?')
-        tier = entry.get('tier', '?')
-        doc_url = entry.get('doc_url')
-        has_sa = entry.get('has_sa', False)
-
-        # Skip type_exempt tier entries
-        if tier == 'type_exempt':
-            continue
-
-        # Check for missing @sa
-        if not has_sa:
-            report('docs/missing_sa_comment', location,
-                  f'public API "{name}" (tier: {tier}) has no @sa documentation link')
-            continue
-
-        # Verify URL resolves to an existing file
-        doc_file = url_to_docfile(doc_url)
-        if not doc_file:
-            report('docs/invalid_sa_url', location,
-                  f'public API "{name}" has invalid @sa URL: {doc_url}')
-            continue
-
-        if not os.path.exists(doc_file):
-            display_path = os.path.relpath(doc_file, REPO_ROOT)
-            report('docs/missing_doc_file', location,
-                  f'public API "{name}" @sa URL points to non-existent file: {display_path}')
-
-    # Check documented_non_public entries
-    for entry in documented_non_public:
-        location = entry.get('location', 'unknown')
-        reason = entry.get('reason', '?')
-        report('docs/sa_on_non_public', location,
-              f'@sa comment found on non-public entity: {reason}')
-
-    print(120 * "-")
-
-    if warnings > 0:
-        print(f"\nFound {warnings} documentation issues")
-        return False
-    else:
-        print("\nAll public API entries are properly documented ✓")
-        return True
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Check documentation for public API')
-    parser.add_argument('--snapshot', default='api_snapshot.json',
-                       help='Path to API snapshot JSON file')
-
-    args = parser.parse_args()
-
-    if not check_docs(args.snapshot):
-        sys.exit(1)
-
-
-if __name__ == '__main__':
-    main()

tools/api_checker/check_macros.py

@@ -1,135 +0,0 @@
-#!/usr/bin/env python3
-"""
-Advisory-only cross-check between documented macros and their #define sites.
-
-Macros have no C++ access-specifier concept, so the AST-based public/private test that
-extract_api.py uses for classes doesn't transfer -- see tools/api_checker/POLICY.md's "Known
-limitations" section. This script only checks one direction: that every macro documented under
-docs/mkdocs/docs/api/macros/ still has a matching #define somewhere under include/nlohmann/,
-catching stale or renamed doc pages. It does NOT check the converse (undocumented macros) --
-no reliable signal exists for that direction given this codebase's conventions.
-
-Never blocks CI -- always exits 0, even when it reports findings.
-"""
-
-import argparse
-import glob
-import os
-import re
-import sys
-
-MACRO_TOKEN_RE = re.compile(r'\b([A-Z][A-Z0-9_]*)\b')
-
-warnings = 0
-
-
-def report(location: str, description: str):
-    global warnings
-    warnings += 1
-    print(f'{warnings:3}. {location}:  {description}')
-
-
-def extract_macro_names(md_path: str) -> list:
-    """
-    Extract macro name(s) from a doc page's H1 heading.
-
-    Most pages use a single-line markdown heading ('# JSON_ASSERT'). A few document a family of
-    related macros under one page using a multi-line HTML heading listing comma-separated names
-    (e.g. NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, ..._WITH_DEFAULT, ..._ONLY_SERIALIZE). Handle
-    both: collect the heading text (markdown '# ...' line, or everything between <h1> and </h1>,
-    which may span multiple lines), then split on commas.
-    """
-    with open(md_path) as f:
-        content = f.read()
-
-    heading_text = None
-    html_match = re.search(r'<h1>(.*?)</h1>', content, re.DOTALL)
-    if html_match:
-        heading_text = html_match.group(1)
-    else:
-        for line in content.splitlines():
-            if line.startswith('# '):
-                heading_text = line[2:]
-                break
-
-    if not heading_text:
-        return []
-
-    names = []
-    for part in heading_text.split(','):
-        match = MACRO_TOKEN_RE.search(part)
-        if match:
-            names.append(match.group(1))
-    return names
-
-
-def macro_is_referenced(macro_name: str, include_dir: str) -> bool:
-    """
-    Check whether macro_name is defined or referenced anywhere under include_dir.
-
-    A reference is any #ifdef, #ifndef, or defined() check.
-
-    Some documented macros (e.g. JSON_NOEXCEPTION, JSON_THROW_USER) are user-supplied overrides:
-    the library only checks whether they're defined, it never #defines them itself. Requiring a
-    literal #define would make this advisory check permanently noisy for that whole category, so
-    presence of any reference is treated as "this macro still exists in the codebase."
-    """
-    pattern = re.compile(
-        r'#\s*define\s+' + re.escape(macro_name) + r'\b'
-        r'|#\s*ifn?def\s+' + re.escape(macro_name) + r'\b'
-        r'|defined\s*\(\s*' + re.escape(macro_name) + r'\s*\)'
-        r'|defined\s+' + re.escape(macro_name) + r'\b'
-    )
-    for root, _dirs, files in os.walk(include_dir):
-        for fname in files:
-            if not fname.endswith('.hpp'):
-                continue
-            path = os.path.join(root, fname)
-            with open(path, encoding='utf-8', errors='ignore') as f:
-                if pattern.search(f.read()):
-                    return True
-    return False
-
-
-def check_macros(macros_dir: str, include_dir: str) -> bool:
-    md_files = sorted(glob.glob(os.path.join(macros_dir, '*.md')))
-    md_files = [f for f in md_files if os.path.basename(f) != 'index.md']
-
-    print(f"Checking {len(md_files)} documented macros against #define sites in {include_dir}...")
-    print(120 * "-")
-
-    for md_path in md_files:
-        macro_names = extract_macro_names(md_path)
-        if not macro_names:
-            report(md_path, "could not extract macro name(s) from H1 heading")
-            continue
-
-        for macro_name in macro_names:
-            if not macro_is_referenced(macro_name, include_dir):
-                report(md_path, f'documented macro "{macro_name}" is not defined or referenced under {include_dir}')
-
-    print(120 * "-")
-
-    if warnings > 0:
-        print(f"\nFound {warnings} stale/renamed macro doc pages (advisory only, not blocking)")
-    else:
-        print("\nAll documented macros have a matching #define ✓")
-
-    return warnings == 0
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Advisory cross-check of documented macros vs. #define sites')
-    parser.add_argument('--macros-dir', default='docs/mkdocs/docs/api/macros',
-                       help='Directory containing macro documentation pages')
-    parser.add_argument('--include-dir', default='include/nlohmann',
-                       help='Directory to search for #define sites')
-
-    args = parser.parse_args()
-    check_macros(args.macros_dir, args.include_dir)
-    # Advisory only -- never fail CI regardless of findings.
-    sys.exit(0)
-
-
-if __name__ == '__main__':
-    main()

tools/api_checker/diff_api.py

@@ -1,299 +0,0 @@
-#!/usr/bin/env python3
-"""
-Diff the public API surface between two refs to flag breaking vs. feature changes.
-
-A "ref" for --old/--new is resolved in this order:
-1. A stored, committed historical record at tools/api_checker/history/<ref>.json, if one exists
-   and --no-history wasn't passed (fast path -- no libclang/git-archive needed).
-2. Live extraction: check the ref out via `git archive` into a temp dir and run extract_api.py
-   against it (needed for HEAD, branches, or any tag not yet backfilled into history/).
---old-file/--new-file bypass both and load an arbitrary surface JSON file directly.
-
-Uses extract_api.py's --surface-output (identity-only: scope, kind, name, identity_name, tier,
-signature, pretty_signature -- no location, no doc_url) for both sides, so the diff reflects only
-genuine API changes, never unrelated code motion or documentation-site restructuring. Identity is
-(scope, identity_name, kind, signature) -- see extract_api.py's identity_key()/get_signature_text()
-docstrings for the full history of why this is what it is: a naive {scope,name,kind,params} key
-silently collided on overloads differing only by constness/SFINAE; switching to libclang's USR
-fixed that but encoded the *enclosing class template's own arity* into every member's identity, so
-a single backward-compatible template-parameter addition (confirmed via real release tags
-v3.11.2->v3.11.3) made ~228 of 330 entries look "changed" for a release with no real breaking
-changes. The current raw-source-text-signature approach was arrived at, and each of several further
-refinements verified, by testing against real historical releases -- not by inspecting code alone.
-"""
-
-import argparse
-import json
-import os
-# subprocess is only called with fixed argument lists, never through a shell.
-import subprocess  # nosec B404
-import sys
-import tempfile
-from collections import defaultdict
-
-SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
-HISTORY_DIR = os.path.join(SCRIPT_DIR, 'history')
-
-# The format_version this build of diff_api.py understands. Kept in sync with
-# extract_api.py's SURFACE_FORMAT_VERSION by convention (both bump together whenever the
-# identity-computing algorithm changes) -- imported directly so there's exactly one source of
-# truth, not two constants that can drift apart.
-sys.path.insert(0, SCRIPT_DIR)
-from extract_api import SURFACE_FORMAT_VERSION  # noqa: E402
-
-
-def resolve_commit_sha(ref: str) -> str | None:
-    """Resolve a ref to its full commit sha, or None if that fails."""
-    try:
-        result = subprocess.run(  # nosec B603 B607
-            ['git', 'rev-parse', ref],
-            capture_output=True, text=True, check=True, timeout=10
-        )
-        return result.stdout.strip()
-    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-
-
-def extract_surface_for_ref(ref: str, header: str = 'include/nlohmann/json.hpp',
-                            include: str = 'include') -> dict:
-    """
-    Check out the full include/ tree at `ref` into a temp dir and extract its API surface.
-
-    A single-file checkout of json.hpp is not enough: json.hpp #includes dozens of other
-    headers under nlohmann/detail/ that must exist at the same ref for parsing to succeed.
-
-    Returns the full loaded surface JSON (format_version, meta, public_api list), with `ref` and
-    the resolved commit sha recorded in meta -- callers that only care about the diff can ignore
-    these; snapshot_release.py uses them as a historical record's provenance.
-    """
-    with tempfile.TemporaryDirectory(prefix='api_checker_') as tmpdir:
-        archive = subprocess.run(  # nosec B603 B607
-            ['git', 'archive', ref, '--', 'include'],
-            capture_output=True, check=True
-        )
-        subprocess.run(['tar', '-x', '-C', tmpdir], input=archive.stdout, check=True)  # nosec B603 B607
-
-        ref_include = os.path.join(tmpdir, include)
-        ref_header = os.path.join(tmpdir, header)
-        if not os.path.exists(ref_header):
-            print(f"Error: {header} does not exist at ref {ref}")
-            sys.exit(1)
-
-        surface_output = os.path.join(tmpdir, 'surface.json')
-        result = subprocess.run(  # nosec B603
-            [sys.executable, os.path.join(SCRIPT_DIR, 'extract_api.py'),
-             '--header', ref_header,
-             '--include', ref_include,
-             '--output', os.path.join(tmpdir, 'snapshot.json'),
-             '--surface-output', surface_output],
-            capture_output=True, text=True
-        )
-        if result.returncode != 0:
-            print(f"Error extracting API at ref {ref}:")
-            print(result.stdout)
-            print(result.stderr)
-            sys.exit(1)
-
-        with open(surface_output) as f:
-            surface = json.load(f)
-
-    # extract_api.py resolved 'extracted_from' relative to *its own* invocation cwd/repo-root
-    # detection, which inside this temp checkout is meaningless (a path like
-    # "../../../../var/folders/.../tmp.XXXX/include/nlohmann/json.hpp") -- overwrite with the
-    # stable, repo-relative header path actually passed in, so a stored history file's metadata
-    # doesn't embed a throwaway temp directory name.
-    surface.setdefault('meta', {})['extracted_from'] = header
-    surface['meta']['ref'] = ref
-    commit_sha = resolve_commit_sha(ref)
-    if commit_sha:
-        surface['meta']['commit'] = commit_sha
-    return surface
-
-
-def load_surface_file(path: str) -> dict:
-    """Load a surface JSON file from disk (a stored history/ record or an explicit --old-file/--new-file)."""
-    with open(path) as f:
-        return json.load(f)
-
-
-def resolve_surface(ref: str | None, explicit_file: str | None, header: str, include: str,
-                    no_history: bool) -> tuple:
-    """Resolve one side of a diff. Returns (surface_dict, description_string_for_display)."""
-    if explicit_file:
-        return load_surface_file(explicit_file), f"file:{explicit_file}"
-
-    history_path = os.path.join(HISTORY_DIR, f"{ref}.json")
-    if not no_history and os.path.exists(history_path):
-        return load_surface_file(history_path), f"history:{ref}"
-
-    return extract_surface_for_ref(ref, header, include), f"live:{ref}"
-
-
-def build_identity_dict(public_api: list) -> dict:
-    """
-    Group a surface's public_api list by identity for diffing.
-
-    Identity is (scope, identity_name, kind, signature) -- the same four components
-    extract_api.py's identity_key() joins into one opaque string internally, exposed here as
-    explicit fields on each record (see extract_api.py's write_surface()) so this reconstruction
-    is a plain, visible tuple lookup rather than decoding anything.
-    """
-    return {
-        (entry['scope'], entry['identity_name'], entry['kind'], entry['signature']): entry
-        for entry in public_api
-    }
-
-
-def diff_surfaces(old_api: dict, new_api: dict) -> dict:
-    """Compare two API surfaces by identity key, grouping same-(scope,name) changes."""
-    old_keys = set(old_api.keys())
-    new_keys = set(new_api.keys())
-
-    added_keys = new_keys - old_keys
-    removed_keys = old_keys - new_keys
-
-    # Group removed/added entries by (scope, name) to detect "changed overload" pairs,
-    # rather than reporting a same-named removal+addition as two unrelated changes.
-    removed_by_name = defaultdict(list)
-    for key in removed_keys:
-        entry = old_api[key]
-        removed_by_name[(entry['scope'], entry['name'])].append(key)
-
-    added_by_name = defaultdict(list)
-    for key in added_keys:
-        entry = new_api[key]
-        added_by_name[(entry['scope'], entry['name'])].append(key)
-
-    changed = []
-    pure_added = []
-    pure_removed = []
-
-    for name, removed_list in removed_by_name.items():
-        if name in added_by_name:
-            added_list = added_by_name.pop(name)
-            for key in removed_list:
-                changed.append({'scope': name[0], 'name': name[1],
-                               'old': old_api[key]['pretty_signature'],
-                               'new': new_api[added_list[0]]['pretty_signature']})
-        else:
-            for key in removed_list:
-                pure_removed.append(old_api[key])
-
-    for name, added_list in added_by_name.items():
-        for key in added_list:
-            pure_added.append(new_api[key])
-
-    return {
-        'added': sorted(pure_added, key=lambda e: e['pretty_signature']),
-        'removed': sorted(pure_removed, key=lambda e: e['pretty_signature']),
-        'changed': sorted(changed, key=lambda e: (e['scope'], e['name'])),
-    }
-
-
-def print_diff(diff: dict, old_desc: str, new_desc: str) -> bool:
-    """Print a human-readable diff report. Returns True if breaking changes were found."""
-    print(120 * "-")
-    print(f"API Diff: {old_desc} -> {new_desc}")
-    print(120 * "-")
-
-    if diff['added']:
-        print(f"\nAdded ({len(diff['added'])} entries) -- feature:")
-        for entry in diff['added']:
-            print(f"  + {entry['pretty_signature']}")
-
-    if diff['removed']:
-        print(f"\nRemoved ({len(diff['removed'])} entries) -- BREAKING:")
-        for entry in diff['removed']:
-            print(f"  - {entry['pretty_signature']}")
-
-    if diff['changed']:
-        print(f"\nChanged overloads ({len(diff['changed'])} entries) -- BREAKING by default:")
-        for entry in diff['changed']:
-            print(f"  ~ {entry['old']}  ->  {entry['new']}")
-
-    if not any([diff['added'], diff['removed'], diff['changed']]):
-        print("\nNo API changes detected")
-
-    print(120 * "-")
-
-    breaking = bool(diff['removed'] or diff['changed'])
-    if breaking:
-        print("\nWARNING: Potential BREAKING CHANGES detected:")
-        print(f"  - {len(diff['removed'])} removed entries")
-        print(f"  - {len(diff['changed'])} changed overloads")
-    if diff['added']:
-        print(f"\nNew features: {len(diff['added'])} added entries")
-
-    return breaking
-
-
-def main():
-    parser = argparse.ArgumentParser(description='Diff public API surface between two refs')
-    parser.add_argument('--old', help='Old git ref (tag/commit) -- checks tools/api_checker/history/ first, '
-                       'then falls back to live extraction')
-    parser.add_argument('--new', help='New git ref (default: HEAD unless --new-file is given)')
-    parser.add_argument('--old-file', help='Path to a stored surface JSON file for the "old" side '
-                       '(bypasses git and tools/api_checker/history/ entirely)')
-    parser.add_argument('--new-file', help='Path to a stored surface JSON file for the "new" side '
-                       '(bypasses git and tools/api_checker/history/ entirely)')
-    parser.add_argument('--no-history', action='store_true',
-                       help='Force live extraction even if a matching tools/api_checker/history/<ref>.json '
-                       'exists -- useful to check a stored record is still faithful to a fresh run')
-    parser.add_argument('--allow-format-mismatch', action='store_true',
-                       help='Proceed even if the two surfaces have different format_version (results may '
-                       'be unsound -- the identity algorithm may differ between versions)')
-    parser.add_argument('--header', default='include/nlohmann/json.hpp',
-                       help='Header file to analyze (relative to repo root, live-extraction only)')
-    parser.add_argument('--include', default='include',
-                       help='Include directory (relative to repo root, live-extraction only)')
-    parser.add_argument('--fail-on-breaking', action='store_true',
-                       help='Exit with status 1 if breaking changes are detected')
-
-    args = parser.parse_args()
-
-    if args.old and args.old_file:
-        parser.error('--old and --old-file are mutually exclusive')
-    if not args.old and not args.old_file:
-        parser.error('one of --old or --old-file is required')
-    if args.new and args.new_file:
-        parser.error('--new and --new-file are mutually exclusive')
-
-    new_ref = args.new or ('HEAD' if not args.new_file else None)
-
-    print(f"Resolving old surface ({args.old_file or args.old})...")
-    old_surface, old_desc = resolve_surface(args.old, args.old_file, args.header, args.include, args.no_history)
-
-    print(f"Resolving new surface ({args.new_file or new_ref})...")
-    new_surface, new_desc = resolve_surface(new_ref, args.new_file, args.header, args.include, args.no_history)
-
-    old_fmt = old_surface.get('format_version')
-    new_fmt = new_surface.get('format_version')
-    # Check both surfaces against SURFACE_FORMAT_VERSION (what *this build* of diff_api.py
-    # understands), not just against each other: two surfaces on the same format_version could
-    # still both be on a version this build predates and doesn't correctly interpret.
-    mismatched = old_fmt != SURFACE_FORMAT_VERSION or new_fmt != SURFACE_FORMAT_VERSION
-    if mismatched and not args.allow_format_mismatch:
-        print(f"Error: format_version mismatch. This build of diff_api.py understands "
-              f"format_version {SURFACE_FORMAT_VERSION!r}, but {old_desc} is {old_fmt!r} and "
-              f"{new_desc} is {new_fmt!r}.")
-        print("The identity/signature algorithm may differ between these two surfaces, making a diff unsound.")
-        print("Re-run with --allow-format-mismatch to proceed anyway.")
-        sys.exit(1)
-    elif mismatched:
-        print(f"WARNING: proceeding with mismatched format_version (this build understands "
-              f"{SURFACE_FORMAT_VERSION!r}; {old_desc}={old_fmt!r}, {new_desc}={new_fmt!r}) as requested.")
-
-    old_api = build_identity_dict(old_surface['public_api'])
-    new_api = build_identity_dict(new_surface['public_api'])
-
-    print(f"\nComparing {len(old_api)} old entries with {len(new_api)} new entries...")
-    diff = diff_surfaces(old_api, new_api)
-
-    breaking = print_diff(diff, old_desc, new_desc)
-
-    if args.fail_on_breaking and breaking:
-        sys.exit(1)
-
-
-if __name__ == '__main__':
-    main()