Skip to content

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

Note

- 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

`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 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. 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.

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

    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.
2. Added in version 2.0.2.

Back to top