Move instead of deep-copy ordered_json values when an object grows

[nlohmann]

What & why

nlohmann::ordered_map stores its elements in a std::vector<std::pair<const Key, T>>. With a std::string key, that pair is not nothrow move constructible, because the const key has to be copied. So whenever the vector reallocates, std::vector copy-constructs every element via move_if_noexcept.

For ordered_json, this means that growing an object deep-copies every member value it already holds, including whole nested subtrees. Parsing is affected, because the parser inserts members one by one. So is any code that fills an object through operator[], emplace, push_back, or update.

I found this while measuring allocations for #5298 (comment): ordered_json created exactly twice as many strings as json for the same document.

Changes

• ordered_map now grows its storage itself: the keys are copied and the values are moved. Only three places append, and all of them go through the new private append():

  • both emplace overloads;
  • insert(const value_type&).

  Everything else already reaches one of them: operator[], insert(value_type&&), insert(first, last), and the basic_json and parser paths.

• Strong exception guarantee without try/catch (the library also builds with -fno-exceptions):

  • The first phase may throw, but it only changes a temporary buffer: it copies the keys, value-initializes the values, and constructs the new element.
  • The second phase cannot throw: it move-assigns the values over and swaps the buffers.

• Arguments that point into the map stay valid, as with std::vector. The new element is constructed before any value is moved, so a call like j.emplace("new", std::move(j["old"])) still works.

• Which types take the new path: it is chosen at compile time, only when std::vector would copy (the element is not nothrow move constructible), the key is copyable, and T is default constructible and nothrow move assignable. basic_json meets all of these. Every other type keeps the current std::vector behavior. The trait is evaluated inside the member template, because T is still incomplete when basic_json instantiates its object_t.

• Benchmark: ParseStringOrdered rows mirror ParseString. So far, the benchmark suite had no ordered_json rows at all.

• Docs: ordered_map.md now describes the growth behavior, has an "Exception safety" section, and gets a version history entry.

Benchmark

ParseString / ParseStringOrdered, measured on an Apple M1 Max with Apple clang 21 -O3:

file	json	ordered_json before	ordered_json after
twitter.json	1.64 ms	3.20 ms	1.70 ms (−47%)
citm_catalog.json	3.26 ms	7.73 ms	3.67 ms (−53%)
jeopardy.json	165 ms	219 ms	177 ms (−19%)
canada.json	10.4 ms	10.5 ms	10.8 ms (no objects)

• Allocations while parsing twitter drop from 60,456 to 19,182, and for citm_catalog from 157,142 to 53,004. Both are now below json, whose std::map allocates one node per member.
• Building 2,000 objects of 64 members each through operator[] goes from 97 to 60 ms.

Tests

• unit-ordered_map.cpp: new test case "ordered_map growth".
  • No value copies: growing through emplace, operator[] and insert(value_type&&) makes no copies of the values. insert(const value_type&) and insert(first, last) make exactly one copy per inserted element.
  • Order and contents are preserved over many growth steps.
  • Strong guarantee: the container is unchanged if copying any of the keys throws while it grows. This is tested for every position of the throwing key, for emplace and for insert(const value_type&).
  • Aliasing: arguments that refer to elements of the full container work, for ordered_map and for ordered_json::emplace.
  • Types that keep the std::vector path: nothrow-movable elements, and a mapped type without a default constructor.
  • Guard against silent regressions: static_asserts check that ordered_json::object_t meets all the conditions, so a future noexcept change can't silently disable the optimization.
• unit-disabled_exceptions.cpp: grows an ordered_json object with exceptions switched off.
• Against develop's ordered_map.hpp, the copy-count checks fail (for example 127 value copies instead of 0 for 100 emplaces), and so do the argument checks in the strong-guarantee test.
• Local runs:
  • the full suite with ASan/UBSan;
  • unit-ordered_map with C++11/14/20, clang -Weverything, the CI's GCC warning flags (GCC 14), clang-tidy, -DJSON_NOEXCEPTION, and -fno-exceptions;
  • make check-amalgamation;
  • the documentation structure check.

Public API impact

No breaking changes.

• API: value_type stays std::pair<const Key, T>. The public members keep their signatures, and only private member templates are added.
• Requirements on Key and T: unchanged. Types that don't qualify for the new path keep the std::vector behavior, so everything that compiles today still compiles.
• Exception safety and iterators: the strong exception guarantee is kept. As before, growing invalidates all iterators and references.
• Layout: no new data members.
• Observable differences:
  • fewer copies of T, which only matters if its copy constructor has side effects;
  • on the new path, capacity() grows by a factor of 2. That is what libstdc++ and libc++ already do; MSVC's std::vector uses 1.5. Capacity growth is not a documented guarantee.

_{This PR was written by Claude Code on behalf of @nlohmann.}

🤖 Generated with Claude Code

[nlohmann]

CI fix: ci_icpc and ci_nvhpc

Both jobs failed while compiling tests/src/unit-ordered_map.cpp:

unit-ordered_map.cpp(89): error: static assertion failed with "std::vector would move the elements itself"

Cause (PR-caused, test only): icpc 2021.10 and nvc++ 25.5 share the EDG front end, which treats the defaulted move constructor of std::pair<const Key, T> as noexcept even when copying Key can throw. A small probe on Compiler Explorer, with libstdc++ 12, shows std::is_nothrow_move_constructible<std::pair<const std::string, V>> evaluates to 1 on both, but to 0 on GCC. On these compilers std::vector already "moves" the elements itself when it grows: it copies the key and moves the value. ordered_map::append then correctly falls back to emplace_back, so the library code is fine. Only the test's assumption fails.

The same misjudgement means std::vector calls std::terminate there if a key copy throws during growth (the probe aborts). So once the compile error was fixed, the throwing_key exception-safety section would also abort on these compilers.

Fix: c5d40f0 skips the first static_assert and the exception-safety section (together with throwing_key) when __EDG__ is defined. Both compilers define it. The comment in the test explains why. Library code is unchanged.

Verification:

• Compiler Explorer, icpc 2021.10 (-std=gnu++11) and nvc++ 25.5 (--c++11 --gnu_extensions, --c++17): unit-ordered_map.cpp builds and passes (3350/3352 assertions). unit-disabled_exceptions.cpp with JSON_NOEXCEPTION builds and passes.
• Local clang, C++11 and C++17: all assertions pass, including with -D__EDG__ to exercise the guarded path.
• astyle 3.4.13: clean.

— posted by Claude Code on behalf of @nlohmann