• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>from_bjdata
2
3```cpp
4// (1)
5template<typename InputType>
6static basic_json from_bjdata(InputType&& i,
7                              const bool strict = true,
8                              const bool allow_exceptions = true);
9// (2)
10template<typename IteratorType>
11static basic_json from_bjdata(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 BJData (Binary JData) 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/bjdata.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 BJData 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 BJData format to a JSON value.
80
81    ```cpp
82    --8<-- "examples/from_bjdata.cpp"
83    ```
84
85    Output:
86
87    ```json
88    --8<-- "examples/from_bjdata.output"
89    ```
90
91## Version history
92
93- Added in version 3.11.0.
94