Skip to content

nlohmann::basic_json::value 

// (1)
template<classValueType>
ValueTypevalue(consttypenameobject_t::key_type&key,
ValueType&&default_value)const;
// (2)
template<classValueType,classKeyType>
ValueTypevalue(KeyType&&key,
ValueType&&default_value)const;
// (3)
template<classValueType>
ValueTypevalue(constjson_pointer&ptr,
constValueType&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{
returnat(key);
}catch(out_of_range){
returndefault_value;
}

  2. See 1. This overload is only available if KeyType is comparable with typenameobject_t::key_type and typenameobject_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{
returnat(ptr);
}catch(out_of_range){
returndefault_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 array or object; in that case, using value() with a JSON pointer makes no sense.
    • Throws parse_error.106 if an array index in the passed JSON pointer ptr begins with '0'.
    • Throws parse_error.109 if an array index in the passed JSON pointer ptr is not a number.

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.

Notes

Return type

The value function is a template, and the return type of the function is determined by the type of the provided default value unless otherwise specified. This can have unexpected effects. In the example below, we store a 64-bit unsigned integer. We get exactly that value when using operator[]. However, when we call value and provide 0 as default value, then -1 is returned. This occurs, because 0 has type int which overflows when handling the value 18446744073709551615.

To address this issue, either provide a correctly typed default value or use the template parameter to specify the desired return type. Note that this issue occurs even when a value is stored at the provided key, and the default value is not used as the return value.

#include<iostream>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
intmain()
{
jsonj=json::parse(R"({"uint64": 18446744073709551615})");
std::cout<<"operator[]: "<<j["uint64"]<<'\n'
<<"default value (int): "<<j.value("uint64",0)<<'\n'
<<"default value (uint64_t): "<<j.value("uint64",std::uint64_t(0))<<'\n'
<<"explicit return value type: "<<j.value<std::uint64_t>("uint64",0)<<'\n';
}

Output:

operator[]:18446744073709551615
defaultvalue(int):-1
defaultvalue(uint64_t):18446744073709551615
explicitreturnvaluetype:18446744073709551615

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>
usingjson=nlohmann::json;
intmain()
{
// create a JSON object with different entry types
jsonj=
{
{"integer",1},
{"floating",42.23},
{"string","hello world"},
{"boolean",true},
{"object",{{"key1",1},{"key2",2}}},
{"array",{1,2,3}}
};
// access existing values
intv_integer=j.value("integer",0);
doublev_floating=j.value("floating",47.11);
// access nonexisting values and rely on default value
std::stringv_string=j.value("nonexisting","oops");
boolv_boolean=j.value("nonexisting",false);
// output values
std::cout<<std::boolalpha<<v_integer<<" "<<v_floating
<<" "<<v_string<<" "<<v_boolean<<"\n";
}

Output:

142.23oopsfalse
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>
usingnamespacestd::string_view_literals;
usingjson=nlohmann::json;
intmain()
{
// create a JSON object with different entry types
jsonj=
{
{"integer",1},
{"floating",42.23},
{"string","hello world"},
{"boolean",true},
{"object",{{"key1",1},{"key2",2}}},
{"array",{1,2,3}}
};
// access existing values
intv_integer=j.value("integer"sv,0);
doublev_floating=j.value("floating"sv,47.11);
// access nonexisting values and rely on default value
std::stringv_string=j.value("nonexisting"sv,"oops");
boolv_boolean=j.value("nonexisting"sv,false);
// output values
std::cout<<std::boolalpha<<v_integer<<" "<<v_floating
<<" "<<v_string<<" "<<v_boolean<<"\n";
}

Output:

142.23oopsfalse
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>
usingjson=nlohmann::json;
usingnamespacenlohmann::literals;
intmain()
{
// create a JSON object with different entry types
jsonj=
{
{"integer",1},
{"floating",42.23},
{"string","hello world"},
{"boolean",true},
{"object",{{"key1",1},{"key2",2}}},
{"array",{1,2,3}}
};
// access existing values
intv_integer=j.value("/integer"_json_pointer,0);
doublev_floating=j.value("/floating"_json_pointer,47.11);
// access nonexisting values and rely on default value
std::stringv_string=j.value("/nonexisting"_json_pointer,"oops");
boolv_boolean=j.value("/nonexisting"_json_pointer,false);
// output values
std::cout<<std::boolalpha<<v_integer<<" "<<v_floating
<<" "<<v_string<<" "<<v_boolean<<"\n";
}

Output:

142.23oopsfalse

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. Made ValueType the first template parameter in version 3.11.2.
  3. Added in version 2.0.2. Extended to work with arrays in version 3.12.x.
Copyright © 2013-2026 Niels Lohmann

AltStyle によって変換されたページ (->オリジナル) /