]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
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. |