1# <small>nlohmann::basic_json::</small>binary_t 2 3```cpp 4using binary_t = byte_container_with_subtype<BinaryType>; 5``` 6 7This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type 82, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for 9compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values. 10 11Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_t`, which 12is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is 13incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType` 14via 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 21family](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 25represent 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 29None of these impose any limitations on the internal representation other than the basic unit of storage be some type of 30array whose parts are decomposable into bytes. 31 32The default representation of this binary format is a `#!cpp std::vector<std::uint8_t>`, which is a very common way to 33represent 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 44The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`. 45 46#### Storage 47 48Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the 49type `#!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. 90