Feature request: dedicated function to add/overwrite by key

[Niko-O]

When getting values out of an object, I have these options:

• Use object.get_to("Key", target); (or target = object.get<decltype(target)>("Key");). This throws an exception if the key is not present. Very much what I want.
• Use value = object["Key"];
  • If object is "modifiable", this will create the key if it is not present. Not what I want.
  • If object is not "modifiable", this is undefined behavior. Super duper not what I want.

When putting values into the object, I have these options:

• Use object["Key"] = value;
  • If object is "modifiable", this will create the key and then overwrite it. Mostly what I want, but I'd prefer if it threw when the key already exists.
  • If object is not "modifiable", the compilation fails with "method is not marked const". This is what I want.

When I first started using the library, I used the operator [] for both cases because it looks very clean. I learned the hard way that this operator does not what I want when getting values (Related: issues #289 and #2111), so I decided to use get_to for getting values instead. But I can't find an equivalent set or set_from or add or add_from for setting values. (set would overwrite an existing value and add would throw an exception.)

This leaves an inconsistency in my code where I use one thing for getting values and a completely different thing for setting values.
Also, modern IDEs are awesome, so there is no reliable way of making sure that I don't still call the operator [] to get a value somewhere. And the operator itself can't (reliably) distinguish between getting and setting, so I can't just put an assert there. I would like to outright remove the operator []s from json.hpp, to make sure that I can't accidentally use it, but I don't have an alternative for setting values. I woud add such a function myself (even if it's just for my cloned copy of the repo), but I don't know the internal details of how your code works, so I would very likely introduce a bug. Even just having a version that does almost what I want (e.g. overwrite if already exists) would make it a lot easier to modify it (e.g. throw if already exists).

So to summarize: If there were dedicated functions to set values, just like there are dedicated functions to get values, this would

• improve consistency
• give more options in regards to what you want to happen in certain corner cases
• maybe kinda be more in-line with the "fast operator [], slow but safe non-operator functions" idea
• reduces the chance for bugs (Adding the same key twice would be a bug in my code, just like trying to get a non-existing value is)
• allow easier customization,

That last point is quite important for me. If you disagree on how those functions should behave, I would still appreciate having anything at all over no options whatsoever. And if you don't want to change your public-facing API in this way, I would still very much appreciate if you could write an exemplary function and post that here, even though that won't make it into your repository.

[falbrechtskirchinger]

• Use object.get_to("Key", target); (or target = object.get<decltype(target)>("Key");). This throws an exception if the key is not present.

There are no functions with these signatures. Do you mean object.at("Key").get_to(target);?

When putting values into the object, I have these options:

There are more options. See https://json.nlohmann.me/features/element_access/ for a complete list.

But I can't find an equivalent set or set_from or add or add_from for setting values. (set would overwrite an existing value and add would throw an exception.)

set() sounds very much like operator [] to me. add() does indeed not exist. The closest function is emplace() which doesn't overwrite existing keys, but also doesn't throw.

You'd have to check if the key exists yourself (using contains()) and then use operator [] to insert the key and value.

Examples:

auto j = json{{"foo", 42}};

// option 1
if(auto [_, inserted] = j.emplace("foo", 0); !inserted)
    throw "key exists";

// option 2
if(j.contains("foo"))
    throw "key exists";
j["foo"] = 0;

Note that emplace() may move r-values regardless of whether the value is inserted.

[nlohmann]

Maybe related: #1309 or #2715

[Niko-O]

@falbrechtskirchinger

There are no functions with these signatures. Do you mean object.at("Key").get_to(target);?

Durr. It seems I was having somewhat of a brainfart. I am actually using object["Key"].get_to(target);. Not sure why my brain blacked that out.

There are more options. See https://json.nlohmann.me/features/element_access/ for a complete list.

Yep, but none of them really do what I want.
operator [] see initial post.
at can't be used to insert new keys because it throws if the key doesn't already exist.
value is for getting only.
Iterators would be possible, but it's very inconvenient to do json temp = {{"Key", value}}; object.insert(temp.begin(), temp.end());, and object must already be an actual object. You can't do this in a to_json function unless you do object = json::object(); first.
Json pointers would be overkill for accessing something that's just one level deep, but I suspect that it won't solve my problem anyways.

set() sounds very much like operator [] to me.

Not really. operator [] returns a reference and you assign to that from the outside. set would take the new value as a parameter and return void. So object.set("Key", value);, not obejct.set("Key") = value;.

add() does indeed not exist. The closest function is emplace() which doesn't overwrite existing keys, but also doesn't throw.

You'd have to check if the key exists yourself (using contains()) and then use operator [] to insert the key and value.

That all seems like an overcomplication for what I'm trying to do. But the latter I can at least add to the library. It does seem somewhat inefficient, though, searching once to see if the key is there and searching again to put the value in.
I'll check back here after trying.

@nlohmann

Maybe related: #1309 or #2715

Coalescing is the opposite of what I try to do. If I ever try to get something out of a JSON object that isn't there, that's an error. Either a bug in the program that sends me the JSON, or someone is messing with the API. In both cases I don't want to silently eat invalid data.
And it applies more to getting values out than putting values in.

[Niko-O]

I added these functions to do what I need:

    /// @brief Adds the key and value to the object. Throws, if the key already exists.
    template<typename KeyType, typename ValueType>
    void add(const KeyType& key, const ValueType& value)
    {
        if (contains(key))
        {
            JSON_THROW(out_of_range::create(499, detail::concat("Tried to add already existing key ", key), this));
        }
        (*this)[key] = value;
    }

    /// @brief Gets the value at that index from the array and puts it into v. Throws, if the index is out of range.
    template<typename ValueType>
    void get_to(size_type index, ValueType& v) const
    {
        if (!is_array())
        {
            JSON_THROW(type_error::create(305, detail::concat("cannot use get_to with a numeric argument with ", type_name()), this));
        }
        if (index >= m_value.array->size())
        {
            JSON_THROW(out_of_range::create(401, detail::concat("array index ", std::to_string(index), " is out of range"), this));
        }
        (*this)[index].get_to(v);
    }

    /// @brief Gets the value at that index from the array. Throws, if the index is out of range.
    template<typename ValueType>
    constexpr auto get(size_type index) const
    {
        if (!is_array())
        {
            JSON_THROW(type_error::create(305, detail::concat("cannot use get with a numeric argument with ", type_name()), this));
        }
        if (index >= m_value.array->size())
        {
            JSON_THROW(out_of_range::create(401, detail::concat("array index ", std::to_string(index), " is out of range"), this));
        }
        return (*this)[index].template get<ValueType>();
    }

    /// @brief Gets the value associated with that key from the object and puts it into v. Throws, if the key does not exists.
    template<typename ValueType>
    void get_to(typename object_t::key_type key, ValueType& v) const
    {
        if (!is_object())
        {
            JSON_THROW(type_error::create(305, detail::concat("cannot use get with a string argument with ", type_name()), this));
        }
        if (!contains(key))
        {
            JSON_THROW(out_of_range::create(498, detail::concat("Tried to get_to non-existing key ", key), this));
        }
        (*this)[key].get_to(v);
    }

    /// @brief Gets the value associated with that key from the object. Throws, if the key does not exists.
    template<typename ValueType>
    constexpr auto get(typename object_t::key_type key) const
    {
        if (!is_object())
        {
            JSON_THROW(type_error::create(305, detail::concat("cannot use get with a string argument with ", type_name()), this));
        }
        if (!contains(key))
        {
            JSON_THROW(out_of_range::create(497, detail::concat("Tried to get non-existing key ", key), this));
        }
        return (*this)[key].template get<ValueType>();
    }

(I didn't bother with enable_if and constexpr because it's not important for me. Feel free to suggest improvements.)
Then I made the stuff that I want to avoid (e.g. operator []) private, so I couldn't call it from outside and changed my code to use those new functions. Seems to work for now.

[falbrechtskirchinger]

Well, there's plenty wrong – incorrect reference types or lack of references being the most glaring.

As a PR, it's missing several overloads, and get(key)/get_to(key, val) seem redundant as at(key).get()/at(key).get_to(val) do exactly the same without too many more keystrokes.