docs: document the complexity of ordered_map operations - #5353
Merged
Conversation
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>
nlohmann
added
the
🚀 ready to merge
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>
gregmarr
approved these changes
Aug 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ordered_mapstores its elements in astd::vectorin insertion order and keeps no lookup index, so every key-based operation —emplace,operator[],at,find,count,erase,insert— is a linear scan over the elements inserted so far. The documentation stated no complexity at all: neitherordered_map.mdnorordered_json.mdsaid anything about it, andfeatures/object_order.mdrecommendsordered_jsonwithout mentioning the cost.This PR documents the current behavior. It changes no code.
api/ordered_map.md— new Complexity section with a per-operation table, an explicit contrast withstd::map's O(log n), and a warning that building an object ofnkeys is therefore O(n²).api/ordered_json.md— short Complexity section pointing at that table.features/object_order.md— one paragraph next to the existingtsl::ordered_map/fifo_mapsuggestions, noting that those alternatives keep a lookup index and do not have this cost.Measurements
Parsing a flat object
{"k0":0,"k1":1,…}ofnkeys,-O2 -DNDEBUG, median of repeated runs,ordered_jsonvs.json:njsonordered_jsonThe
ordered_jsontimings quadruple per doubling ofnwhilejsonroughly doubles — textbook quadratic. Parsing is affected because the SAX builder inserts each key as it is read.Non-goals
Making lookups sub-linear (e.g. by keeping a side index inside
ordered_map) would changesizeof(ordered_map)and is therefore ABI-visible, so it is a separate decision and not attempted here. The complexity is worth writing down either way.Breaking changes to the public API
None — documentation only, no code or headers touched.
This pull request was prepared by Claude Code.