mirror of
https://github.com/nlohmann/json.git
synced 2026-08-11 19:53:18 +00:00
Niels LohmannandGitHub
c2e1cc50e0
* docs: document the complexity of ordered_map operations ordered_map stores its elements in a std::vector in insertion order and has no lookup index, so emplace, operator[], at, find, count, erase, and insert are all linear scans. The documentation stated no complexity for any operation, neither in ordered_map.md nor in ordered_json.md. Add a per-operation complexity table and note the consequence: building or parsing an ordered_json object of n keys is O(n^2). Measured with -O2 -DNDEBUG for parsing a flat object of n keys, ordered_json is 5x slower than json at n=2000 and 54x slower at n=16000, with the timings quadrupling per doubling of n. Cross-reference the table from ordered_json.md and from the object order page, which recommends ordered_json without mentioning the cost. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * docs: move the Complexity section after Member functions scripts/check_structure.py enforces a fixed section order for pages under docs/mkdocs/docs/api, in which Complexity comes after Member functions. The section had been placed right after Iterator invalidation, which made ci_test_build_documentation fail with structure/section_order. No content change beyond the move; the table columns are realigned to the narrower content. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
1.3 KiB
1.3 KiB
nlohmann::ordered_json
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 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() 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 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 for the per-operation table and for measured numbers.
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
Version history
Since version 3.9.0.