mirror of
https://github.com/nlohmann/json.git
synced 2026-07-21 19:23:03 +04:00
Niels Lohmann
f23b3c63a2
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>
40 lines
1.0 KiB
Markdown
40 lines
1.0 KiB
Markdown
# <small>nlohmann::</small>ordered_json
|
|
|
|
```cpp
|
|
using ordered_json = basic_json<ordered_map>;
|
|
```
|
|
|
|
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.
|
|
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.
|
|
|
|
## Examples
|
|
|
|
??? example
|
|
|
|
The example below demonstrates how `ordered_json` preserves the insertion order of object keys.
|
|
|
|
```cpp
|
|
--8<-- "examples/ordered_json.cpp"
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
--8<-- "examples/ordered_json.output"
|
|
```
|
|
|
|
## See also
|
|
|
|
- [ordered_map](ordered_map/index.md)
|
|
- [Object Order](../features/object_order.md)
|
|
|
|
## Version history
|
|
|
|
Since version 3.9.0.
|