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;
-
Returns either a copy of an object's element at the specified key
key
or a given default value if no element with keykey
exists.The function is basically equivalent to executing
try { return at(key); } catch(out_of_range) { return default_value; }
-
Returns either a copy of an object's element at the specified JSON pointer
ptr
or a given default value if no value atptr
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, orstd::vector
types for JSON arrays. Note the type of the expected value atkey
/ptr
and the default valuedefault_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¶
- copy of the element at key
key
ordefault_value
ifkey
is not found - copy of the element at JSON Pointer
ptr
ordefault_value
if no value forptr
is found
Exception safety¶
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
Exceptions¶
- The function can throw thw following exceptions:
- Throws
type_error.302
ifdefault_value
does not match the type of the value atkey
- Throws
type_error.306
if the JSON value is not an object; in that case, usingvalue()
with a key makes no sense.
- Throws
- The function can throw thw following exceptions:
- Throws
type_error.302
ifdefault_value
does not match the type of the value atptr
- Throws
type_error.306
if the JSON value is not an object; in that case, usingvalue()
with a key makes no sense.
- Throws
Complexity¶
- Logarithmic in the size of the container.
- Logarithmic in the size of the container.
Example¶
Example
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
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
Version history¶
- Added in version 1.0.0.
- Added in version 2.0.2.