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

   1 # <small>nlohmann::basic_json::</small>from_ubjson
   2
   3 ```cpp
   4 // (1)
   5 template<typename InputType>
   6 static basic_json from_ubjson(InputType&& i,
   7                               const bool strict = true,
   8                               const bool allow_exceptions = true);
   9 // (2)
  10 template<typename IteratorType>
  11 static basic_json from_ubjson(IteratorType first, IteratorType last,
  12                               const bool strict = true,
  13                               const bool allow_exceptions = true);
  14 ```
  15
  16 Deserializes a given input to a JSON value using the UBJSON (Universal Binary JSON) serialization format.
  17
  18 1. Reads from a compatible input.
  19 2. Reads from an iterator range.
  20
  21 The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
  22
  23 ## Template parameters
  24
  25 `InputType`
  26 :   A compatible input, for instance:
  27
  28     - an `std::istream` object
  29     - a `FILE` pointer
  30     - a C-style array of characters
  31     - a pointer to a null-terminated string of single byte characters
  32     - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
  33
  34 `IteratorType`
  35 :   a compatible iterator type
  36
  37 ## Parameters
  38
  39 `i` (in)
  40 :   an input in UBJSON format convertible to an input adapter
  41
  42 `first` (in)
  43 :   iterator to start of the input
  44
  45 `last` (in)
  46 :   iterator to end of the input
  47
  48 `strict` (in)
  49 :   whether to expect the input to be consumed until EOF (`#!cpp true` by default)
  50
  51 `allow_exceptions` (in)
  52 :   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
  53
  54 ## Return value
  55
  56 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
  57 `value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
  58
  59 ## Exception safety
  60
  61 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
  62
  63 ## Exceptions
  64
  65 - Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
  66   the end of file was not reached when `strict` was set to true
  67 - Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
  68 - Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
  69   successfully
  70
  71 ## Complexity
  72
  73 Linear in the size of the input.
  74
  75 ## Examples
  76
  77 ??? example
  78
  79     The example shows the deserialization of a byte vector in UBJSON format to a JSON value.
  80
  81     ```cpp
  82     --8<-- "examples/from_ubjson.cpp"
  83     ```
  84
  85     Output:
  86
  87     ```json
  88     --8<-- "examples/from_ubjson.output"
  89     ```
  90
  91 ## Version history
  92
  93 - Added in version 3.1.0.
  94 - Added `allow_exceptions` parameter in version 3.2.0.
  95
  96 !!! warning "Deprecation"
  97
  98     - Overload (2) replaces calls to `from_ubjson` with a pointer and a length as first two parameters, which has been
  99       deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
 100       `#!cpp from_ubjson(ptr, len, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
 101     - Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been
 102       deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
 103       `#!cpp from_ubjson({ptr, ptr+len}, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
 104
 105     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
 106     function.