• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>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
21The 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
56deserialized 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
61Strong 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
73Linear 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.
107