mirror of
https://github.com/nlohmann/json.git
synced 2026-10-12 10:13:13 +00:00
Niels Lohmann
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>
46 lines
1.3 KiB
Markdown
46 lines
1.3 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.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.
|
|
|
|
## Complexity
|
|
|
|
[`ordered_map`](ordered_map.md) 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](ordered_map.md#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
|
|
|
|
- [ordered_map](ordered_map.md)
|
|
- [Object Order](../features/object_order.md)
|
|
|
|
## Version history
|
|
|
|
Since version 3.9.0.
|