| # <small>nlohmann::basic_json::</small>binary_t | |
| ```cpp | |
| using binary_t = byte_container_with_subtype<BinaryType>; | |
| ``` | |
| This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type | |
| 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for | |
| compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values. | |
| Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_t`, which | |
| is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is | |
| incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType` | |
| via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.md). | |
| [CBOR's RFC 8949](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1) describes this type as: | |
| > Major type 2: A byte string. The number of bytes in the string is equal to the argument. | |
| [MessagePack's documentation on the bin type | |
| family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as: | |
| > 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. | |
| [BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to | |
| represent the generic binary type which has the description: | |
| > Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and | |
| > tools. | |
| None of these impose any limitations on the internal representation other than the basic unit of storage be some type of | |
| array whose parts are decomposable into bytes. | |
| The default representation of this binary format is a `#!cpp std::vector<std::uint8_t>`, which is a very common way to | |
| represent a byte array in modern C++. | |
| ## Template parameters | |
| `BinaryType` | |
| : container type to store arrays | |
| Although not formally expressed as a C++ concept, `BinaryType` must be default-constructible, | |
| copy/move-constructible, and support `push_back()`, `.data()`, and `.size()`, because | |
| [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) derives directly from it. Its | |
| `value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary | |
| serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via | |
| `reinterpret_cast`, which is only correct for byte-sized elements -- a container like | |
| `#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and | |
| the binary readers additionally require `resize()` and `operator[]`. See | |
| [Template Parameter Requirements](../../features/types/template_parameters.md#binarytype) for the full list. | |
| ## Notes | |
| ### Default type | |
| The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`. | |
| ### Supported byte types | |
| `#!cpp std::vector<std::uint8_t>`, `#!cpp std::vector<char>`, and `#!cpp std::vector<std::byte>` are supported. | |
| Regardless of which of them is configured, [`dump`](dump.md) writes the bytes as the numbers 0..255. | |
| ### Custom BinaryType behavior | |
| When a custom `BinaryType` is configured (other than the default `#!cpp std::vector<std::uint8_t>`), you can assign | |
| values of that type directly to a `basic_json` instance, and they will automatically be recognized as binary values | |
| rather than arrays: | |
| ```cpp | |
| using custom_json = nlohmann::ordered_json::with_binary_t<std::vector<std::byte>>; | |
| std::vector<std::byte> data{std::byte{1}, std::byte{2}, std::byte{3}}; | |
| custom_json j = data; // Creates a binary value, not an array | |
| assert(j.is_binary()); | |
| // Round-tripping works seamlessly | |
| auto extracted = j.get<std::vector<std::byte>>(); | |
| assert(extracted == data); | |
| ``` | |
| This automatic type detection is a convenience feature that only applies to custom (non-default) `BinaryType` configurations. | |
| The default `nlohmann::json` continues to treat `#!cpp std::vector<std::uint8_t>` as arrays for backward compatibility. | |
| ### Storage | |
| Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the | |
| type `#!cpp binary_t*` must be dereferenced. | |
| ### Notes on subtypes | |
| - CBOR | |
| - Binary values are represented as byte strings. Subtypes are written as tags. | |
| - MessagePack | |
| - If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, | |
| fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is | |
| then added as a signed 8-bit integer. | |
| - If no subtype is given, the bin family (bin8, bin16, bin32) is used. | |
| - BSON | |
| - If a subtype is given, it is used and added as an unsigned 8-bit integer. | |
| - If no subtype is given, the generic binary subtype 0x00 is used. | |
| ## Examples | |
| ??? example | |
| The following code shows that `binary_t` is by default, a typedef to | |
| `#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`. | |
| ```cpp | |
| #include <iostream> | |
| #include <iomanip> | |
| #include <nlohmann/json.hpp> | |
| using json = nlohmann::json; | |
| int main() | |
| { | |
| std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl; | |
| } | |
| ``` | |
| Output: | |
| ```json | |
| true | |
| ``` | |
| ## See also | |
| - [byte_container_with_subtype](../byte_container_with_subtype/index.md) | |
| ## Version history | |
| - Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0. | |
| - Fixed [`dump`](dump.md), [`std::hash`](std_hash.md), and [`to_ubjson`](to_ubjson.md) for byte types that are not | |
| integers (e.g., `#!cpp std::byte`) in version 3.13.0. `dump` now writes the bytes of a signed byte type (e.g., | |
| `#!cpp char`) as 0..255 rather than as negative numbers. |