Feature Discussion: Null-safe, noexcept accessors — eval_value, eval_array, eval_object

[gitpaladin]

Motivation

In server-side C++ applications, JSON payloads received from external sources frequently contain null values, missing keys, or even entirely unexpected types (e.g., a string where an object was expected). The current value() function provides a convenient way to access object elements with a default fallback, but it throws type_error (306) when the receiver itself is null or is not an object.

Consider the following real-world scenario:

// Payload received from a remote server — could be null, partial, wrong type, or complete
auto received = from_server();

received.value("a", 0);          // throws type_error if received is null
received.value("/c/d", "");       // throws type_error if received is null or not an object

This forces developers to wrap every access in a type/null check:

int a = 0;
if (received.is_object()) {
    a = received.value("a", 0);
}

Or worse, when navigating nested paths with JSON Pointer:

std::string d;
if (received.is_object() && received.contains("c") && received["c"].is_object()) {
    d = received["c"].value("d", std::string{});
}

JavaScript doesn't have this problem. Optional chaining and nullish coalescing make this trivial:

const a = received?.a ?? 0;
const d = received?.c?.d ?? "";

The proposed eval_value, eval_array, and eval_object functions aim to bring similar ergonomics to C++ by treating any non-matching type (null, missing, wrong type) as equivalent to "not present" rather than as an error. Crucially, these functions never throw and can be marked noexcept, making them safe to use in any context without try-catch.

Proposed API

1. eval_value — noexcept value access with default

// Access by key — returns default_value if:
//   - *this is not an object (null, array, string, number, boolean — any type)
//   - *this is an object but key is not found
//   - *this is an object but the value at key is null
template <class ValueType>
ValueType eval_value(const typename object_t::key_type& key,
                     const ValueType& default_value) const noexcept;

// Access by JSON Pointer — returns default_value if:
//   - *this is not an object (null, array, string, number, boolean — any type)
//   - any intermediate node in the path is null, missing, or wrong type
//   - the resolved value is null
template <class ValueType>
ValueType eval_value(const json_pointer& ptr,
                     const ValueType& default_value) const noexcept;

Usage:

auto received = from_server();  // might be null

int a    = received.eval_value("a", 0);                           // safe, returns 0 if null
auto d   = received.eval_value("/c/d"_json_pointer, std::string{}); // safe, returns "" if any part is null

Semantics compared to value():

Condition	value()	eval_value()
*this is a non-null object, key exists	Returns value	Returns value
*this is a non-null object, key missing	Returns default	Returns default
*this is null	Throws type_error	Returns default
Resolved value is null	Returns null-converted value	Returns default
*this is another type (array, string…)	Throws type_error	Returns default

The key design decision is: any non-matching receiver type — including null, arrays, strings, numbers, and booleans — is treated as "absent", not as an error. This mirrors how JavaScript's optional chaining propagates null/undefined without throwing, and aligns with the defensive programming philosophy that server-side code should never crash due to malformed input — instead, it should degrade gracefully to zero/empty values.

Because eval_value never throws, it is marked noexcept. This provides a strong guarantee to callers and enables compiler optimizations.

2. eval_array — noexcept array access (returns const reference)

// Access by key
const basic_json& eval_array(const typename object_t::key_type& key) const noexcept;

// Access by JSON Pointer
const basic_json& eval_array(const json_pointer& ptr) const noexcept;

Returns a const reference to the array found at the specified key/pointer. If the receiver is any non-object type (null, array, string, number…), the key is missing, or the resolved value is not an array, returns a reference to a static empty array. Never throws.

Usage:

auto received = from_server();  // might be null, might lack "items"

// No need to check for null or existence — safe range-based for loop
for (const auto& item : received.eval_array("items")) {
    // process each item
}

// Works with JSON Pointer for nested arrays
for (const auto& entry : received.eval_array("/response/data/entries"_json_pointer)) {
    // process each entry
}

Without eval_array, the same code requires verbose guarding:

if (!received.is_null() && received.contains("items") && received["items"].is_array()) {
    for (const auto& item : received["items"]) {
        // process each item
    }
}

3. eval_object — noexcept object access (returns const reference)

// Access by key
const basic_json& eval_object(const typename object_t::key_type& key) const noexcept;

// Access by JSON Pointer
const basic_json& eval_object(const json_pointer& ptr) const noexcept;

Analogous to eval_array, but for objects. Returns a const reference to the object found at the specified key/pointer, or a static empty object if the receiver is any non-object type, the path is missing, or the resolved value is not an object. Never throws.

Usage:

auto received = from_server();

// Iterate over a nested object safely
for (const auto& [key, val] : received.eval_object("metadata").items()) {
    // process each key-value pair
}

Possible Implementation Sketch

Below is a simplified implementation sketch to illustrate the approach. The actual implementation would follow the library's template conventions (SFINAE guards, transparent comparator support, etc.).

All three functions are noexcept — they never throw, regardless of the receiver's type. If *this is not an object, or the path cannot be resolved, or the resolved value is the wrong type, the functions silently return the default/empty fallback. This makes them safe to use in any context.

// --- eval_value (key-based) ---
template <class ValueType>
ValueType eval_value(const typename object_t::key_type& key,
                     const ValueType& default_value) const noexcept
{
    if (!is_object())
    {
        return default_value;
    }

    const auto it = find(key);
    if (it != end() && !it->is_null())
    {
        JSON_TRY
        {
            return it->template get<ValueType>();
        }
        JSON_INTERNAL_CATCH (...)
        {
            return default_value;
        }
    }

    return default_value;
}

// --- eval_value (JSON Pointer-based) ---
template <class ValueType>
ValueType eval_value(const json_pointer& ptr,
                     const ValueType& default_value) const noexcept
{
    if (!is_object())
    {
        return default_value;
    }

    JSON_TRY
    {
        const auto& resolved = ptr.get_checked(this);
        if (resolved.is_null())
        {
            return default_value;
        }
        return resolved.template get<ValueType>();
    }
    JSON_INTERNAL_CATCH (...)
    {
        return default_value;
    }
}

// --- eval_array (key-based) ---
const basic_json& eval_array(const typename object_t::key_type& key) const noexcept
{
    static const basic_json empty_array(value_t::array);

    if (!is_object())
    {
        return empty_array;
    }

    const auto it = find(key);
    if (it != end() && it->is_array())
    {
        return *it;
    }

    return empty_array;
}

// --- eval_array (JSON Pointer-based) ---
const basic_json& eval_array(const json_pointer& ptr) const noexcept
{
    static const basic_json empty_array(value_t::array);

    if (!is_object())
    {
        return empty_array;
    }

    JSON_TRY
    {
        const auto& resolved = ptr.get_checked(this);
        if (resolved.is_array())
        {
            return resolved;
        }
    }
    JSON_INTERNAL_CATCH (...) {}

    return empty_array;
}

// --- eval_object (key-based) ---
const basic_json& eval_object(const typename object_t::key_type& key) const noexcept
{
    static const basic_json empty_object(value_t::object);

    if (!is_object())
    {
        return empty_object;
    }

    const auto it = find(key);
    if (it != end() && it->is_object())
    {
        return *it;
    }

    return empty_object;
}

// --- eval_object (JSON Pointer-based) ---
const basic_json& eval_object(const json_pointer& ptr) const noexcept
{
    static const basic_json empty_object(value_t::object);

    if (!is_object())
    {
        return empty_object;
    }

    JSON_TRY
    {
        const auto& resolved = ptr.get_checked(this);
        if (resolved.is_object())
        {
            return resolved;
        }
    }
    JSON_INTERNAL_CATCH (...) {}

    return empty_object;
}

Design Considerations

Why not just fix value() to handle null?

Changing the existing value() behavior would be a breaking change — existing users may rely on the type_error exception for null receivers as part of their validation logic. Per the project's contribution guidelines, the public API of the 3.x.y series must not be broken. A new function name makes the intent explicit and preserves backward compatibility.

Why noexcept? Why not throw on type mismatch?

In server-side programming, the data received from external sources is fundamentally untrusted. When a server receives "hello" where it expected {"a": 1}, crashing or entering an exception handler is rarely the right response — the correct behavior is to treat it as "no valid data" and fall back to a sensible default (zero, empty string, empty array, etc.).

This is the same philosophy behind JavaScript's optional chaining: (null)?.a doesn't throw a TypeError — it simply evaluates to undefined. The eval_* functions extend this principle to all non-matching types.

Marking these functions noexcept provides:

1. Simplified call sites — no try-catch, no type checks, just use the result directly
2. Compiler optimization — noexcept enables the compiler to skip exception-handling table generation
3. Composability — safe to use in noexcept contexts, destructors, move constructors, etc.
4. Clear contract — the function signature itself communicates "this will never fail"

Why return static empty containers in eval_array/eval_object?

Returning a const reference to a static empty JSON array/object avoids allocation and allows the result to be used directly in range-based for loops. Since the reference is const, there is no risk of accidental mutation of the static sentinel.

Naming alternatives

The eval_ prefix is chosen to suggest "evaluate with safe navigation", but other names could work:

Name	Rationale
eval_value / eval_array / eval_object	"Evaluate" implies safe resolution through a path
value_or / array_or / object_or	Emphasizes the fallback behavior
safe_value / safe_array / safe_object	Emphasizes null-safety
opt_value / opt_array / opt_object	Short for "optional", mirrors std::optional semantics

Community feedback on naming is welcome.

Thread safety of static empty containers

The static empty basic_json objects used in eval_array and eval_object are const and initialized via constant initialization or at worst Meyers' singleton (thread-safe since C++11). This should be safe for concurrent use.

Summary

All eval_* functions are noexcept. They never throw regardless of the receiver's type.

Function	noexcept	On non-object receiver	On missing key/path	On null resolved value	On wrong resolved type
eval_value(key, default)	Yes	Returns default	Returns default	Returns default	Returns default
eval_value(ptr, default)	Yes	Returns default	Returns default	Returns default	Returns default
eval_array(key)	Yes	Returns empty []	Returns empty []	Returns empty []	Returns empty []
eval_array(ptr)	Yes	Returns empty []	Returns empty []	Returns empty []	Returns empty []
eval_object(key)	Yes	Returns empty {}	Returns empty {}	Returns empty {}	Returns empty {}
eval_object(ptr)	Yes	Returns empty {}	Returns empty {}	Returns empty {}	Returns empty {}

Comparison with existing value():

Condition	value()	eval_value()
*this is object, key exists, correct type	Returns value	Returns value
*this is object, key missing	Returns default	Returns default
*this is null	Throws	Returns default
*this is array, string, number, bool…	Throws	Returns default
Resolved value is null	Returns null-converted value	Returns default

These functions would significantly reduce boilerplate in server-side C++ code that processes JSON from untrusted or loosely-typed sources, bringing the developer experience closer to JavaScript's optional chaining — while remaining fully backward-compatible with the existing API and providing a strong noexcept guarantee.