• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# basic_json::from_ubjson
2
3```cpp
4// (1)
5template<typename InputType>
6static basic_json from_ubjson(InputType&& i,
7                              const bool strict = true,
8                              const bool allow_exceptions = true);
9// (2)
10template<typename IteratorType>
11static basic_json from_ubjson(IteratorType first, IteratorType last,
12                              const bool strict = true,
13                              const bool allow_exceptions = true);
14```
15
16Deserializes a given input to a JSON value using the UBJSON (Universal Binary JSON) serialization format.
17
181. Reads from a compatible input.
192. Reads from an iterator range.
20
21## Template parameters
22
23`InputType`
24:   A compatible input, for instance:
25
26    - an `std::istream` object
27    - a `FILE` pointer
28    - a C-style array of characters
29    - a pointer to a null-terminated string of single byte characters
30    - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
31
32`IteratorType`
33:   a compatible iterator type
34
35## Parameters
36
37`i` (in)
38:   an input in UBJSON format convertible to an input adapter
39
40`first` (in)
41:   iterator to start of the input
42
43`last` (in)
44:   iterator to end of the input
45
46`strict` (in)
47:   whether to expect the input to be consumed until EOF (`#!cpp true` by default)
48
49`allow_exceptions` (in)
50:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
51
52## Return value
53
54deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
55`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
56
57## Exception safety
58
59Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
60
61## Complexity
62
63Linear in the size of the input.
64
65## Example
66
67??? example
68
69    The example shows the deserialization of a byte vector in UBJSON format to a JSON value.
70
71    ```cpp
72    --8<-- "examples/from_ubjson.cpp"
73    ```
74
75    Output:
76
77    ```json
78    --8<-- "examples/from_ubjson.output"
79    ```
80
81## Version history
82
83- Added in version 3.1.0.
84- Added `allow_exceptions` parameter in version 3.2.0.
85