1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
### jsoncons::bson::decode_bson
Decodes a [Binary JSON (BSON)](http://bsonspec.org/) data format into a C++ data structure.
```cpp
#include <jsoncons_ext/bson/bson.hpp>
template <typename T>
T decode_bson(const std::vector<uint8_t>& source,
const bson_decode_options& options = bson_decode_options()); (1) (until 0.152.0)
template <typename T,typename Source>
T decode_bson(const Source& source,
const bson_decode_options& options = bson_decode_options()); (1) (since 0.152.0)
template <typename T>
T decode_bson(std::istream& is,
const bson_decode_options& options = bson_decode_options()); (2)
template <typename T,typename InputIt>
T decode_bson(InputIt first, InputIt last,
const bson_decode_options& options = bson_decode_options()); (3) (since 0.153.0)
template <typename T,typename Source,typename Allocator,typename TempAllocator>
T decode_bson(const allocator_set<Allocator,TempAllocator>& alloc_set,
const Source& source,
const bson_decode_options& options = bson_decode_options()); (4) (since 0.171.0)
template <typename T,typename Allocator,typename TempAllocator>
T decode_bson(const allocator_set<Allocator,TempAllocator>& alloc_set,
std::istream& is,
const bson_decode_options& options = bson_decode_options()); (5) (since 0.171.0)
```
(1) Reads BSON data from a contiguous byte sequence provided by `source` into a type T, using the specified (or defaulted) [options](bson_options.md).
Type `Source` must be a container that has member functions `data()` and `size()`,
and member type `value_type` with size exactly 8 bits (since 0.152.0.)
Any of the values types `int8_t`, `uint8_t`, `char`, `unsigned char` and `std::byte` (since C++17) are allowed.
Type 'T' must be an instantiation of [basic_json](../basic_json.md)
or support [json_type_traits](../json_type_traits.md).
(2) Reads BSON data from a binary stream into a type T, using the specified (or defaulted) [options](bson_options.md).
Type 'T' must be an instantiation of [basic_json](../basic_json.md)
or support [json_type_traits](../json_type_traits.md).
(3) Reads BSON data from the range [`first`,`last`) into a type T, using the specified (or defaulted) [options](bson_options.md).
Type 'T' must be an instantiation of [basic_json](../basic_json.md)
or support [json_type_traits](../json_type_traits.md).
Functions (4)-(5) are identical to (1)-(2) except an [allocator_set](../allocator_set.md) is passed as an additional argument and
provides allocators for result data and temporary allocations.
#### Exceptions
Throws a [ser_error](../ser_error.md) if parsing fails, and a [conv_error](conv_error.md) if type conversion fails.
### Examples
#### Binary example
```cpp
#include <jsoncons/json.hpp>
#include <jsoncons_ext/bson/bson.hpp>
#include <iostream>
int main()
{
std::vector<uint8_t> input = { 0x13,0x00,0x00,0x00, // Document has 19 bytes
0x05, // Binary data
0x70,0x44,0x00, // "pD"
0x05,0x00,0x00,0x00, // Length is 5
0x80, // Subtype is 128
0x48,0x65,0x6c,0x6c,0x6f, // 'H','e','l','l','o'
0x00 // terminating null
};
json j = bson::decode_bson<json>(input);
std::cout << "JSON:\n" << pretty_print(j) << "\n\n";
std::cout << "tag: " << j["pD"].tag() << "\n";
std::cout << "ext_tag: " << j["pD"].ext_tag() << "\n";
auto bytes = j["pD"].as<std::vector<uint8_t>>();
std::cout << "binary data: " << byte_string_view{ bytes } << "\n";
}
```
Output:
```
JSON:
{
"pD": "SGVsbG8"
}
tag: ext
ext_tag: 128
binary data: 48,65,6c,6c,6f
```
Note that printing a json value by default encodes byte strings as base64url strings, but the json value holds the actual bytes.
### See also
[encode_bson](encode_bson.md) encodes a json value to the [Binary JSON](http://bsonspec.org/) data format.
|
