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