Store maps with enum keys as objects (opt-in)

[nlohmann]

Maps with enum keys, such as std::map<TaskState, std::string>, are stored as arrays of [key, value] pairs, even when NLOHMANN_JSON_SERIALIZE_ENUM maps the enum to strings (#4378):

[["stopped","aa"],["completed","bb"]]

This PR adds the opt-in macro JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS. With it, such maps are stored as objects, and each key is converted with the enum's own to_json:

{"completed":"bb","stopped":"aa"}

It supersedes #4531 by @amirghaz, which first proposed this. Thank you! The approach is different, so none of its commits were picked, but @amirghaz is credited as co-author.

Changes

• Writing (opt-in): a new to_json overload for any map-like type with enum keys (std::map with any comparator, std::unordered_map, …), active only with the macro.
  • A key that doesn't convert to a string throws type_error.302. This covers an enumerator mapped to nullptr, a numeric mapping, and an enum without NLOHMANN_JSON_SERIALIZE_ENUM.
  • Two keys that convert to the same string throw the new type_error.318 instead of silently losing an entry.
  • The target value stays unchanged when either error is thrown.
• Reading (always on): std::map and std::unordered_map with enum keys are now also read from objects, using the enum's from_json for the keys. Arrays of pairs are still read, so data written with or without the macro can be read either way. Non-enum keys keep the existing error.
• ABI tag: the macro changes the bodies of inline functions, so, like JSON_BRACE_INIT_COPY_SEMANTICS and JSON_STRICT_NUL_HANDLING, it is part of the ABI tag (_ekmo). The ABI config tests and the Natvis file are updated to match.
• Tests: new unit-enum_keyed_maps.cpp defines the macro itself. unit-conversions.cpp covers the default behavior and reading objects.
• Docs: a new macro page, plus updates to the enum conversion feature page, the NLOHMANN_JSON_SERIALIZE_ENUM(_STRICT) notes, the macro overviews, the namespace page, and the type_error.302/type_error.318 entries.

Refs #4378. Supersedes #4531.

Public API

No breaking changes.

• Without the macro, output is unchanged.
• Input that used to throw (type_error.302, "type must be array, but is object") for enum-keyed std::map/std::unordered_map is now accepted when it's an object whose keys convert to the enum.
• New: the JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS macro (default 0, adds _ekmo to the inline namespace when enabled), and the exception type_error.318, which can only be thrown with the macro enabled.

🤖 Generated with Claude Code

[nlohmann]

Review finding, fixed in 99716a5:

Multimaps with enum keys could not be serialized once the macro was enabled (include/nlohmann/detail/meta/type_traits.hpp, is_enum_keyed_map)

is_enum_keyed_map only checked for key_type/mapped_type and an enum key, so it also matched std::multimap<E, T> and std::unordered_multimap<E, T>. With JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS=1, the new to_json overload then stored them as objects. It threw type_error.318 ("duplicate object key") whenever a key appeared twice, which is the usual case for a multimap. Without the macro, the same values are stored losslessly as [["red",1],["red",2]], so enabling the opt-in made legitimate data impossible to serialize. The duplicate check only prevented silent data loss. It did not make the conversion work.

Fix: maps with non-unique keys are no longer treated as enum-keyed maps. The trait recognizes them because insert(value_type) returns an iterator instead of std::pair<iterator, bool>. Map-like types that have no such insert() are handled as before. They keep the array-of-pairs form. The macro page now has a note about this. (Reading multimaps from JSON never compiled, before or after this PR, so the read side is unaffected.)

Verification:

• I wrote a small repro with -DJSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS=1. Before the fix, json j = std::multimap<C,int>{{C::red,1},{C::red,2}} threw type_error.318, and std::unordered_multimap behaved the same way. After the fix, both produce [["red",1],["red",2]]. std::map, std::unordered_map and nlohmann::ordered_map still produce objects.
• I added a section to unit-enum_keyed_maps.cpp. Its 2 new checks fail without the type-trait change and pass with it (clang C++11/C++20 with JSON_DIAGNOSTICS, GCC latest with -Wall -Wextra -Werror, and also against single_include). unit-conversions.cpp passes both with and without the macro.
• make amalgamate is in sync. I also regenerated nlohmann_json.natvis with generate_natvis.py, and it is identical to the committed file.

— posted by Claude Code on behalf of @nlohmann

[nlohmann]

CI fix: Windows clang 20.1.8

test-conversions_cpp17 failed to link with relocation truncated to fit: IMAGE_REL_AMD64_REL32 against '.rdata'. The MinGW Debug objects of unit-conversions.cpp were already close to that limit, and the new "maps with enum keys" test case pushed it over. The comment in windows.yml asks to split test files in that case. The other clang versions in that matrix were cancelled, not failed.

Fixed in 103b37a: the test case moved unchanged into the new tests/src/unit-enum_keyed_maps_default.cpp, with the three enums it uses, and unit-conversions.cpp is back to its state on develop. The new file still honors a -D flag for JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS: 12 assertions by default and 10 with the flag, with clang at C++11/17 and GCC 14 at C++11/17 with strict warnings.

— posted by Claude Code on behalf of @nlohmann

[nlohmann]

CI fix: ci_cmake_options (ci_test_diagnostic_positions)

Moving the enum-keyed map tests into unit-enum_keyed_maps_default.cpp (103b37a) put them into a job that hadn't run on them before. With JSON_DIAGNOSTIC_POSITIONS, a parsed value adds its byte range to the exception message ((bytes 0-7) type must be array, but is object), so two exact-message checks failed. Fixed in 93fd4aa: the test now builds the object in memory, like unit-custom-array-type.cpp does. Both enum-keyed map test files pass with JSON_DIAGNOSTIC_POSITIONS=1, JSON_DIAGNOSTICS=1, the default settings, and JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS=1.

— posted by Claude Code on behalf of @nlohmann