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

   1 # <small>nlohmann::basic_json::</small>get
   2
   3 ```cpp
   4 // (1)
   5 template<typename ValueType>
   6 ValueType get() const noexcept(
   7     noexcept(JSONSerializer<ValueType>::from_json(
   8         std::declval<const basic_json_t&>(), std::declval<ValueType&>())));
   9
  10 // (2)
  11 template<typename BasicJsonType>
  12 BasicJsonType get() const;
  13
  14 // (3)
  15 template<typename PointerType>
  16 PointerType get_ptr();
  17
  18 template<typename PointerType>
  19 constexpr const PointerType get_ptr() const noexcept;
  20 ```
  21
  22 1. Explicit type conversion between the JSON value and a compatible value which is
  23    [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and
  24    [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). The value is converted by
  25    calling the `json_serializer<ValueType>` `from_json()` method.
  26
  27     The function is equivalent to executing
  28     ```cpp
  29     ValueType ret;
  30     JSONSerializer<ValueType>::from_json(*this, ret);
  31     return ret;
  32     ```
  33
  34     This overload is chosen if:
  35
  36     - `ValueType` is not `basic_json`,
  37     - `json_serializer<ValueType>` has a `from_json()` method of the form
  38       `void from_json(const basic_json&, ValueType&)`, and
  39     - `json_serializer<ValueType>` does not have a `from_json()` method of the form
  40       `ValueType from_json(const basic_json&)`
  41
  42     If the type is **not** [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and
  43     **not** [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible), the value is
  44     converted by calling the `json_serializer<ValueType>` `from_json()` method.
  45
  46     The function is then equivalent to executing
  47     ```cpp
  48     return JSONSerializer<ValueTypeCV>::from_json(*this);
  49     ```
  50
  51     This overload is chosen if:
  52
  53     - `ValueType` is not `basic_json` and
  54     - `json_serializer<ValueType>` has a `from_json()` method of the form
  55      `ValueType from_json(const basic_json&)`
  56
  57     If `json_serializer<ValueType>` has both overloads of `from_json()`, the latter one is chosen.
  58
  59 2. Overload for `basic_json` specializations. The function is equivalent to executing
  60     ```cpp
  61     return *this;
  62     ```
  63
  64 3. Explicit pointer access to the internally stored JSON value. No copies are made.
  65
  66 ## Template parameters
  67
  68 `ValueType`
  69 :   the value type to return
  70
  71 `BasicJsonType`
  72 :   a specialization of `basic_json`
  73
  74 `PointerType`
  75 :   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
  76     [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
  77     [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
  78     Other types will not compile.
  79
  80 ## Return value
  81
  82 1. copy of the JSON value, converted to `ValueType`
  83 2. a copy of `#!cpp *this`, converted into `BasicJsonType`
  84 3. pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
  85    otherwise
  86
  87 ## Exceptions
  88
  89 Depends on what `json_serializer<ValueType>` `from_json()` method throws
  90
  91 ## Notes
  92
  93 !!! warning
  94
  95     Writing data to the pointee (overload 3) of the result yields an undefined state.
  96
  97 ## Examples
  98
  99 ??? example
 100
 101     The example below shows several conversions from JSON values
 102     to other types. There a few things to note: (1) Floating-point numbers can
 103     be converted to integers, (2) A JSON array can be converted to a standard
 104     `std::vector<short>`, (3) A JSON object can be converted to C++
 105     associative containers such as `std::unordered_map<std::string, json>`.
 106
 107     ```cpp
 108     --8<-- "examples/get__ValueType_const.cpp"
 109     ```
 110
 111     Output:
 112
 113     ```json
 114     --8<-- "examples/get__ValueType_const.output"
 115     ```
 116
 117 ??? example
 118
 119     The example below shows how pointers to internal values of a JSON value can be requested. Note that no type
 120     conversions are made and a `#cpp nullptr` is returned if the value and the requested pointer type does not match.
 121
 122     ```cpp
 123     --8<-- "examples/get__PointerType.cpp"
 124     ```
 125
 126     Output:
 127
 128     ```json
 129     --8<-- "examples/get__PointerType.output"
 130     ```
 131
 132 ## Version history
 133
 134 1. Since version 2.1.0.
 135 2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
 136 3. Since version 1.0.0.