mirror of https://github.com/nlohmann/json.git synced 2026-07-12 05:25:09 +00:00

Files

T

Niels Lohmann f23b3c63a2 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>

2026-07-11 18:59:00 +02:00

2.0 KiB

Raw Blame History

nlohmann::ordered_map

template<class Key, class T, class IgnoredLess = std::less<Key>,
         class Allocator = std::allocator<std::pair<const Key, T>>>
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 (nlohmann::basic_json<ordered_map>).

Template parameters

Key: key type
T: mapped type
IgnoredLess: comparison function (ignored and only added to ensure compatibility with #!cpp std::map)
Allocator: allocator type

Iterator invalidation

The type uses a std::vector to store object elements. Therefore, adding elements can yield a reallocation in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

Member types

key_type - key type (Key)
mapped_type - mapped type (T)
Container - base container type (#!cpp std::vector<std::pair<const Key, T>, Allocator>)
iterator
const_iterator
size_type
value_type
key_compare - key comparison function

std::equal_to<Key>  // until C++14

std::equal_to<>     // since C++14

Member functions

Examples

??? example

The example shows the different behavior of `std::map` and `nlohmann::ordered_map`.
 
```cpp
--8<-- "examples/ordered_map.cpp"
```

Output:

```json
--8<-- "examples/ordered_map.output"
```

Version history

Added in version 3.9.0 to implement nlohmann::ordered_json.
Added key_compare member in version 3.11.0.

2.0 KiB Raw Blame History