ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/api/basic_json/value.md

   1 # <small>nlohmann::basic_json::</small>value
   2
   3 ```cpp
   4 // (1)
   5 template<class ValueType>
   6 ValueType value(const typename object_t::key_type& key,
   7                 const ValueType& default_value) const;
   8
   9 // (2)
  10 template<class ValueType>
  11 ValueType value(const json_pointer& ptr,
  12                 const ValueType& default_value) const;
  13 ```
  14
  15 1. Returns either a copy of an object's element at the specified key `key` or a given default value if no element with
  16    key `key` exists.
  17
  18     The function is basically equivalent to executing
  19     ```cpp
  20     try {
  21        return at(key);
  22     } catch(out_of_range) {
  23        return default_value;
  24     }
  25     ```
  26
  27 2. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
  28    at `ptr` exists.
  29
  30     The function is basically equivalent to executing
  31     ```cpp
  32     try {
  33        return at(ptr);
  34     } catch(out_of_range) {
  35        return default_value;
  36     }
  37     ```
  38
  39 !!! note
  40
  41     - Unlike [`at`](at.md), this function does not throw if the given `key`/`ptr` was not found.
  42     - Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
  43      `key`/`ptr` key. This function is furthermore also applicable to const objects.
  44
  45 ## Template parameters
  46
  47 `ValueType`
  48 :   type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans,
  49     or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
  50     value `default_value` must be compatible.
  51
  52 ## Parameters
  53
  54 `key` (in)
  55 :   key of the element to access
  56
  57 `default_value` (in)
  58 :   the value to return if key/ptr found no value
  59
  60 `ptr` (in)
  61 :   a JSON pointer to the element to access
  62
  63 ## Return value
  64
  65 1. copy of the element at key `key` or `default_value` if `key` is not found
  66 1. copy of the element at JSON Pointer `ptr` or `default_value` if no value for `ptr` is found
  67
  68 ## Exception safety
  69
  70 Strong guarantee: if an exception is thrown, there are no
  71 changes to any JSON value.
  72
  73 ## Exceptions
  74
  75 1. The function can throw the following exceptions:
  76     - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
  77       the type of the value at `key`
  78     - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
  79       in that case, using `value()` with a key makes no sense.
  80 2. The function can throw the following exceptions:
  81     - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
  82       the type of the value at `ptr`
  83     - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
  84       in that case, using `value()` with a key makes no sense.
  85
  86 ## Complexity
  87
  88 1. Logarithmic in the size of the container.
  89 2. Logarithmic in the size of the container.
  90
  91 ## Examples
  92
  93 ??? example "Example (1): access specified object element with default value"
  94
  95     The example below shows how object elements can be queried with a default value.
  96
  97     ```cpp
  98     --8<-- "examples/basic_json__value.cpp"
  99     ```
 100
 101     Output:
 102
 103     ```json
 104     --8<-- "examples/basic_json__value.output"
 105     ```
 106
 107 ??? example "Example (2): access specified object element via JSON Pointer with default value"
 108
 109     The example below shows how object elements can be queried with a default value.
 110
 111     ```cpp
 112     --8<-- "examples/basic_json__value_ptr.cpp"
 113     ```
 114
 115     Output:
 116
 117     ```json
 118     --8<-- "examples/basic_json__value_ptr.output"
 119     ```
 120
 121 ## See also
 122
 123 - see [`at`](at.md) for access by reference with range checking
 124 - see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
 125
 126 ## Version history
 127
 128 1. Added in version 1.0.0.
 129 2. Added in version 2.0.2.