• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>from_bson
2
3```cpp
4// (1)
5template<typename InputType>
6static basic_json from_bson(InputType&& i,
7                            const bool strict = true,
8                            const bool allow_exceptions = true);
9// (2)
10template<typename IteratorType>
11static basic_json from_bson(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 BSON (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/bson.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 BSON 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
65Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
66encountered.
67
68## Complexity
69
70Linear in the size of the input.
71
72## Examples
73
74??? example
75
76    The example shows the deserialization of a byte vector in BSON format to a JSON value.
77
78    ```cpp
79    --8<-- "examples/from_bson.cpp"
80    ```
81
82    Output:
83
84    ```json
85    --8<-- "examples/from_bson.output"
86    ```
87
88## See also
89
90- [BSON specification](http://bsonspec.org/spec.html)
91- [to_bson](to_bson.md) for the analogous serialization
92- [from_cbor](from_cbor.md) for the related CBOR format
93- [from_msgpack](from_msgpack.md) for the related MessagePack format
94- [from_ubjson](from_ubjson.md) for the related UBJSON format
95
96## Version history
97
98- Added in version 3.4.0.
99
100!!! warning "Deprecation"
101
102    - Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been
103      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
104      `#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
105    - Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been
106      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
107      `#!cpp from_bson({ptr, ptr+len}, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
108
109    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
110    function.
111