Add AST-based public API checker and fix documentation gaps it found (#3691)

Adds tools/api_checker/: extract_api.py derives the public API surface directly
from the libclang AST (independent of documentation status), check_docs.py flags
public entries missing @sa links (and @sa on non-public ones), diff_api.py does
an overload-aware breaking/feature diff between two refs, check_macros.py cross-
checks documented macros against #define sites, and snapshot_release.py backfills
immutable per-release surface snapshots into tools/api_checker/history/ (v3.1.0
through v3.12.0) so diff_api.py can compare releases without live extraction.
POLICY.md documents what counts as public API and what stability is guaranteed.

Running this tooling against the current tree found and fixed a real documentation
backlog: ~25 new API doc pages (ordered_map's methods, json_sax's ctor/dtor/
operator=, byte_container_with_subtype's comparison operators, several orphaned
type aliases), each with a compiled and output-verified example, plus missing
@sa comments and stale/incorrect Version History entries on several existing
pages (found by diffing consecutive release pairs and checking whether the
resulting change was actually reflected in the target page's history section).

Also adds docs/home/api_changes.md, a per-release, per-function reference of
public API changes (v3.1.0 through v3.12.0) generated from the history/
snapshots, complementing (not replacing) the existing release notes.

Along the way, found and fixed several extractor bugs by testing against real
release tags rather than trusting the algorithm in isolation -- most notably an
identity-key scheme based on libclang's USR that encoded the enclosing class
template's own arity, and a since-renamed ABI inline-namespace pattern
(json_v3_11_0 vs. today's json_abi_v3_11_2) that neither of two earlier regex
attempts stripped correctly. Both are documented in extract_api.py's docstrings
and tools/api_checker/history/README.md so the failure mode doesn't recur
silently.

.github/workflows/check_api_docs.yml runs extract_api.py + check_docs.py in CI,
advisory-only for now (documented backlog may not be at zero for entities this
PR didn't touch), plus a blocking drift check on the committed
tools/api_checker/api_surface.json.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

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

@@ -420,7 +420,9 @@ 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.
+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.
 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

@@ -0,0 +1,38 @@
+# <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/initializer_list_t.md

@@ -0,0 +1,32 @@
+# <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

@@ -0,0 +1,31 @@
+# <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,3 +51,5 @@ 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,3 +85,8 @@ 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

@@ -0,0 +1,32 @@
+# <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

@@ -0,0 +1,45 @@
+# <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

@@ -0,0 +1,45 @@
+# <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

@@ -0,0 +1,28 @@
+# <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

@@ -0,0 +1,30 @@
+# <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

@@ -0,0 +1,33 @@
+# <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

@@ -0,0 +1,30 @@
+# <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

@@ -0,0 +1,30 @@
+# <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

@@ -0,0 +1,30 @@
+# <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

@@ -0,0 +1,29 @@
+# <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

@@ -0,0 +1,30 @@
+# <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

@@ -0,0 +1,22 @@
+# <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/ordered_json.md

@@ -8,7 +8,7 @@ This type preserves the insertion order of object keys.
 
 ## Iterator invalidation
 
-The type is based on [`ordered_map`](ordered_map.md) which in turn uses a `std::vector` to store object elements.
+The type is based on [`ordered_map`](ordered_map/index.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.
@@ -31,7 +31,7 @@ reference after the insertion point will point to the same index, which is now a
 
 ## See also
 
-- [ordered_map](ordered_map.md)
+- [ordered_map](ordered_map/index.md)
 - [Object Order](../features/object_order.md)
 
 ## Version history

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

@@ -0,0 +1,28 @@
+# <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

@@ -0,0 +1,61 @@
+# <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

@@ -0,0 +1,53 @@
+# <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

@@ -0,0 +1,58 @@
+# <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

@@ -0,0 +1,75 @@
+# <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

@@ -0,0 +1,56 @@
+# <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/index.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** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- [**Container**](Container.md) - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
 - **iterator**
 - **const_iterator**
 - **size_type**
 - **value_type**
-- **key_compare** - key comparison function
+- [**key_compare**](key_compare.md) - key comparison function
 ```cpp
 std::equal_to<Key>  // until C++14
 
@@ -46,15 +46,16 @@ std::equal_to<>     // since C++14
 
 ## Member functions
 
-- (constructor)
-- (destructor)
-- **emplace**
-- **operator\[\]**
-- **at**
-- **erase**
-- **count**
-- **find**
-- **insert**
+- [(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)
 
 ## Examples
 
@@ -74,9 +75,9 @@ std::equal_to<>     // since C++14
 
 ## 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/insert.md

@@ -0,0 +1,63 @@
+# <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

@@ -0,0 +1,34 @@
+# <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

@@ -0,0 +1,32 @@
+# <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

@@ -0,0 +1,62 @@
+# <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

@@ -0,0 +1,66 @@
+# <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

@@ -0,0 +1,17 @@
+# <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

@@ -0,0 +1,21 @@
+#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

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

docs/mkdocs/docs/examples/byte_container_with_subtype__container_type.cpp

@@ -0,0 +1,11 @@
+#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

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

docs/mkdocs/docs/examples/byte_container_with_subtype__operator_eq.cpp

@@ -0,0 +1,15 @@
+#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

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

docs/mkdocs/docs/examples/byte_container_with_subtype__operator_ne.cpp

@@ -0,0 +1,15 @@
+#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

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

docs/mkdocs/docs/examples/byte_container_with_subtype__subtype_type.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/initializer_list_t.cpp

@@ -0,0 +1,13 @@
+#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

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

docs/mkdocs/docs/examples/json_sax__binary_t.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/json_sax__number_float_t.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/json_sax__number_integer_t.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/json_sax__number_unsigned_t.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/json_sax__string_t.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/json_sax_t.cpp

@@ -0,0 +1,10 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__Container.cpp

@@ -0,0 +1,12 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__at.cpp

@@ -0,0 +1,26 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__count.cpp

@@ -0,0 +1,12 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__emplace.cpp

@@ -0,0 +1,15 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__erase.cpp

@@ -0,0 +1,24 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__find.cpp

@@ -0,0 +1,19 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__insert.cpp

@@ -0,0 +1,21 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__key_compare.cpp

@@ -0,0 +1,12 @@
+#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

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

docs/mkdocs/docs/examples/ordered_map__operator_idx.cpp

@@ -0,0 +1,14 @@
+#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

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

docs/mkdocs/docs/home/architecture.md

@@ -17,7 +17,7 @@ The main structure is class [nlohmann::basic_json](../api/basic_json/index.md).
 
 - describe template parameters of `basic_json`
 - [`json`](../api/json.md)
-- [`ordered_json`](../api/ordered_json.md) via [`ordered_map`](../api/ordered_map.md)
+- [`ordered_json`](../api/ordered_json.md) via [`ordered_map`](../api/ordered_map/index.md)
 
 ## Value storage
 

docs/mkdocs/docs/home/releases.md

@@ -2,7 +2,8 @@
 
 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).
+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).
 
 ## v3.12.0 (2025-04-11)
 

docs/mkdocs/mkdocs.yml

@@ -52,6 +52,7 @@ 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
@@ -117,6 +118,7 @@ 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
@@ -154,6 +156,7 @@ 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
@@ -172,6 +175,7 @@ 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
@@ -228,9 +232,13 @@ 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
@@ -256,25 +264,46 @@ 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': api/ordered_map.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
       - macros:
           - 'Overview': api/macros/index.md
           - 'JSON_ASSERT': api/macros/json_assert.md