mirror of https://github.com/nlohmann/json.git synced 2026-09-14 20:27:58 +00:00

Files

T

Niels LohmannandClaude Sonnet 5 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

1.4 KiB

Raw Blame History

nlohmann::ordered_map::emplace

// (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);

Inserts #!cpp {key, t} if no element with an equal key already exists (per key_compare), appending it at the end to preserve insertion order. If an equal key already exists, does nothing.
Same as (1), but for any KeyType comparable to key_type via key_compare (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

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.
Overload (2) added in version 3.11.0.

1.4 KiB Raw Blame History