basic_json::value¶

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

// (2)
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. 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;
   }
   

Unlike operator[], this function does not implicitly add an element to the position defined by key/ptr key. This function is furthermore also applicable to const objects.

Template parameters¶

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 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 thw 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. The function can throw thw 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.

Example¶

#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

Version history¶

1. Added in version 1.0.0.
2. Added in version 2.0.2.