Skip to content

# 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;
       }

Differences to `at` and `operator[]`

- Unlike `at`, this function does not throw if the given `key`/`ptr` was not found.
- 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

`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

Example: (1) access specified object element with default value

The example below shows how object elements can be queried with a default value.

    #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";
    }

Output:

    1 42.23 oops false

Example: (2) access specified object element using string_view with default value

The example below shows how object elements can be queried with a default value.

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

    using namespace std::string_view_literals;
    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"sv, 0);
        double v_floating = j.value("floating"sv, 47.11);

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

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

Output:

    1 42.23 oops false

Example: (3) access specified object element via JSON Pointer with default value

The example below shows how object elements can be queried with a default value.

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

    using json = nlohmann::json;
    using namespace nlohmann::literals;

    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";
    }

Output:

    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.

Last update: July 31, 2022
Back to top