Add null-safe noexcept accessors eval_value/eval_array/eval_object

[gitpaladin]

Summary

Introduces an opt-in header <nlohmann/eval.hpp> with three free function templates that complement basic_json::value() with semantics designed for untrusted JSON payloads:

Function	Behaviour
eval_value(j, key|ptr, default)	noexcept, returns default on any non-matching condition (non-object receiver, missing key/path, null resolved value, wrong type, conversion failure).
eval_array(j, key|ptr)	noexcept, returns a const& to a static empty array on any non-matching condition.
eval_object(j, key|ptr)	noexcept, returns a const& to a static empty object on any non-matching condition.

Follows the design agreed in #5129.

Why non-member, opt-in header

Per your preference in the discussion ("I definitely prefer this over an extension of the (already bloated) basic_json API"):

• Non-member functions in namespace nlohmann so ADL works without explicit qualification (eval_value(j, ...) just works).
• Dedicated opt-in header — basic_json's public surface is not extended.
• Uses only the public API (is_object, is_array, is_null, find, end, get, contains(json_pointer), at(json_pointer)).
• Pointer overloads guard with j.contains(ptr) before j.at(ptr), so they remain correct under JSON_NOEXCEPTION too (where at() would otherwise abort).
• Static empty array/object fallbacks are returned by const reference via Meyers' singletons — no per-call allocation, thread-safe since C++11.
• A header-private NLOHMANN_EVAL_TRY/NLOHMANN_EVAL_CATCH_ALL pair mirrors JSON_TRY/JSON_INTERNAL_CATCH, since those macros are #undef'd at the end of json.hpp via macro_unscope.hpp and are not visible to consumers.

What is added

• include/nlohmann/eval.hpp — 6 overloads (key / json_pointer × value / array / object).
• tests/src/unit-eval.cpp — 7 test cases, 79 assertions, picked up automatically by the existing file(GLOB src/unit-*.cpp) in tests/CMakeLists.txt.
• docs/mkdocs/docs/api/eval.md — API page mirroring basic_json/value.md style.

What is not changed

• basic_json is untouched — no new members, no signature changes, no ABI impact.
• single_include/nlohmann/json.hpp is not modified — the new header is intentionally not bundled into the amalgamated single-include (matches Step 4 of the "Next step" plan in Feature Discussion: Null-safe, noexcept accessors — `eval_value`, `eval_array`, `eval_object` #5129). Happy to extend tools/amalgamate/config_json.json if you'd prefer it bundled.

Local test matrix

Toolchain	Standards	Result
MSVC cl (VS 2026)	C++17	7/7 cases, 79/79 assertions PASS, 0 warnings
MSYS2 g++ 15.2	C++11 / C++17 / C++20	PASS each, 0 warnings
MSYS2 clang++ 21.1	C++11 / C++17 / C++20	PASS each, 0 warnings (incl. -Wshadow -Wconversion -Wsign-conversion -Wold-style-cast)
g++ 15.2 + -fno-exceptions -DJSON_NOEXCEPTION	C++17	smoke test PASS (doctest's own limitations apply to the full suite, same as test-disabled_exceptions)

Checklist

• Changes described above.
• References discussion Feature Discussion: Null-safe, noexcept accessors — `eval_value`, `eval_array`, `eval_object` #5129.
• New code covered by tests in tests/src/unit-eval.cpp (7 cases / 79 assertions).
• API documentation page added under docs/mkdocs/docs/api/.
• make amalgamate — not run yet because the new header is intentionally not part of the single-include. If you'd like it bundled, I'll extend the amalgamate config and rerun. Will also rerun should the CI's amalgamation check flag any astyle drift.

Marked as draft so you can pre-screen the direction; happy to address feedback (naming, single-include bundling, anything else) before un-drafting.