nlohmann::basic_json::value¶

// (1)
template<class ValueType>
ValueType value(const typename object_t::key_type& key,
                ValueType&& default_value) const;

// (2)
template<class KeyType, class ValueType>
ValueType value(KeyType&& key,
                ValueType&& default_value) const;

// (3)
template<class ValueType>
ValueType value(const json_pointer& ptr,
                const ValueType& default_value) const;

1. Returns either a copy of an object's element at the specified key key or a given default value if no element with key key exists.

   The function is basically equivalent to executing

   try {
      return at(key);
   } catch(out_of_range) {
      return default_value;
   }
   

2. See 1. This overload is only available if KeyType is comparable with typename object_t::key_type and typename object_comparator_t::is_transparent denotes a type.

3. Returns either a copy of an object's element at the specified JSON pointer ptr or a given default value if no value at ptr exists.

   The function is basically equivalent to executing

   try {
      return at(ptr);
   } catch(out_of_range) {
      return default_value;
   }
   

Template parameters¶

KeyType

A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17).

ValueType

type compatible to JSON values, for instance int for JSON integer numbers, bool for JSON booleans, or std::vector types for JSON arrays. Note the type of the expected value at key/ptr and the default value default_value must be compatible.

Parameters¶

key (in)

key of the element to access

default_value (in)

the value to return if key/ptr found no value

ptr (in)

a JSON pointer to the element to access

Return value¶

1. copy of the element at key key or default_value if key is not found
2. copy of the element at key key or default_value if key is not found
3. copy of the element at JSON Pointer ptr or default_value if no value for ptr is found

Exception safety¶

Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

Exceptions¶

1. The function can throw the following exceptions:
   • Throws type_error.302 if default_value does not match the type of the value at key
   • Throws type_error.306 if the JSON value is not an object; in that case, using value() with a key makes no sense.
2. See 1.
3. The function can throw the following exceptions:
   • Throws type_error.302 if default_value does not match the type of the value at ptr
   • Throws type_error.306 if the JSON value is not an object; in that case, using value() with a key makes no sense.

Complexity¶

1. Logarithmic in the size of the container.
2. Logarithmic in the size of the container.
3. Logarithmic in the size of the container.

Examples¶

#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // create a JSON object with different entry types
    json j =
    {
        {"integer", 1},
        {"floating", 42.23},
        {"string", "hello world"},
        {"boolean", true},
        {"object", {{"key1", 1}, {"key2", 2}}},
        {"array", {1, 2, 3}}
    };

    // access existing values
    int v_integer = j.value("integer", 0);
    double v_floating = j.value("floating", 47.11);

    // access nonexisting values and rely on default value
    std::string v_string = j.value("nonexisting", "oops");
    bool v_boolean = j.value("nonexisting", false);

    // output values
    std::cout << std::boolalpha << v_integer << " " << v_floating
              << " " << v_string << " " << v_boolean << "\n";
}

1 42.23 oops false

#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // create a JSON object with different entry types
    json j =
    {
        {"integer", 1},
        {"floating", 42.23},
        {"string", "hello world"},
        {"boolean", true},
        {"object", {{"key1", 1}, {"key2", 2}}},
        {"array", {1, 2, 3}}
    };

    // access existing values
    int v_integer = j.value("/integer"_json_pointer, 0);
    double v_floating = j.value("/floating"_json_pointer, 47.11);

    // access nonexisting values and rely on default value
    std::string v_string = j.value("/nonexisting"_json_pointer, "oops");
    bool v_boolean = j.value("/nonexisting"_json_pointer, false);

    // output values
    std::cout << std::boolalpha << v_integer << " " << v_floating
              << " " << v_string << " " << v_boolean << "\n";
}

1 42.23 oops false

See also¶

• see at for access by reference with range checking
• see operator[] for unchecked access by reference

Version history¶

1. Added in version 1.0.0. Changed parameter default_value type from const ValueType& to ValueType&& in version 3.11.0.
2. Added in version 3.11.0.
3. Added in version 2.0.2.