]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | # <small>nlohmann::basic_json::</small>binary_t |
2 | ||
3 | ```cpp | |
4 | using binary_t = byte_container_with_subtype<BinaryType>; | |
5 | ``` | |
6 | ||
7 | This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type | |
8 | 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for | |
9 | compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values. | |
10 | ||
11 | Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_t`, which | |
12 | is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is | |
13 | incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType` | |
14 | via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.md). | |
15 | ||
16 | [CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as: | |
17 | > Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers | |
18 | > (major type 0). | |
19 | ||
20 | [MessagePack's documentation on the bin type | |
21 | family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as: | |
22 | > Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array. | |
23 | ||
24 | [BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to | |
25 | represent the generic binary type which has the description: | |
26 | > Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and | |
27 | > tools. | |
28 | ||
29 | None of these impose any limitations on the internal representation other than the basic unit of storage be some type of | |
30 | array whose parts are decomposable into bytes. | |
31 | ||
32 | The default representation of this binary format is a `#!cpp std::vector<std::uint8_t>`, which is a very common way to | |
33 | represent a byte array in modern C++. | |
34 | ||
35 | ## Template parameters | |
36 | ||
37 | `BinaryType` | |
38 | : container type to store arrays | |
39 | ||
40 | ## Notes | |
41 | ||
42 | #### Default type | |
43 | ||
44 | The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`. | |
45 | ||
46 | #### Storage | |
47 | ||
48 | Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the | |
49 | type `#!cpp binary_t*` must be dereferenced. | |
50 | ||
51 | #### Notes on subtypes | |
52 | ||
53 | - CBOR | |
54 | - Binary values are represented as byte strings. Subtypes are written as tags. | |
55 | ||
56 | - MessagePack | |
57 | - If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, | |
58 | fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is | |
59 | then added as signed 8-bit integer. | |
60 | - If no subtype is given, the bin family (bin8, bin16, bin32) is used. | |
61 | ||
62 | - BSON | |
63 | - If a subtype is given, it is used and added as unsigned 8-bit integer. | |
64 | - If no subtype is given, the generic binary subtype 0x00 is used. | |
65 | ||
66 | ## Examples | |
67 | ||
68 | ??? example | |
69 | ||
70 | The following code shows that `binary_t` is by default, a typedef to | |
71 | `#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`. | |
72 | ||
73 | ```cpp | |
74 | --8<-- "examples/binary_t.cpp" | |
75 | ``` | |
76 | ||
77 | Output: | |
78 | ||
79 | ```json | |
80 | --8<-- "examples/binary_t.output" | |
81 | ``` | |
82 | ||
83 | ## See also | |
84 | ||
85 | - [byte_container_with_subtype](../byte_container_with_subtype/index.md) | |
86 | ||
87 | ## Version history | |
88 | ||
89 | - Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0. |