</code></pre></div><p>There are several convenience functions to check and set the subtype:</p><divclass=highlight><pre><span></span><code><spanclass=n>binary</span><spanclass=p>.</span><spanclass=n>has_subtype</span><spanclass=p>();</span><spanclass=w></span><spanclass=c1>// returns false</span>
</code></pre></div><p>As <code>json::binary_t</code> is subclassing <code>std::vector<std::uint8_t></code>, all member functions are available:</p><divclass=highlight><pre><span></span><code><spanclass=n>binary</span><spanclass=p>.</span><spanclass=n>size</span><spanclass=p>();</span><spanclass=w></span><spanclass=c1>// returns 4</span>
</code></pre></div><p>JSON values can be constructed from <code>json::binary_t</code>:</p><divclass=highlight><pre><span></span><code><spanclass=n>json</span><spanclass=w></span><spanclass=n>j</span><spanclass=w></span><spanclass=o>=</span><spanclass=w></span><spanclass=n>binary</span><spanclass=p>;</span><spanclass=w></span>
</code></pre></div><p>Binary values are primitive values just like numbers or strings:</p><divclass=highlight><pre><span></span><code><spanclass=n>j</span><spanclass=p>.</span><spanclass=n>is_binary</span><spanclass=p>();</span><spanclass=w></span><spanclass=c1>// returns true</span>
</code></pre></div><p>Given a binary JSON value, the <code>binary_t</code> can be accessed by reference as via <code>get_binary()</code>:</p><divclass=highlight><pre><span></span><code><spanclass=n>j</span><spanclass=p>.</span><spanclass=n>get_binary</span><spanclass=p>().</span><spanclass=n>has_subtype</span><spanclass=p>();</span><spanclass=w></span><spanclass=c1>// returns true</span>
</code></pre></div><p>For convenience, binary JSON values can be constructed via <code>json::binary</code>:</p><divclass=highlight><pre><span></span><code><spanclass=k>auto</span><spanclass=w></span><spanclass=n>j2</span><spanclass=w></span><spanclass=o>=</span><spanclass=w></span><spanclass=n>json</span><spanclass=o>::</span><spanclass=n>binary</span><spanclass=p>({</span><spanclass=mh>0xCA</span><spanclass=p>,</span><spanclass=w></span><spanclass=mh>0xFE</span><spanclass=p>,</span><spanclass=w></span><spanclass=mh>0xBA</span><spanclass=p>,</span><spanclass=w></span><spanclass=mh>0xBE</span><spanclass=p>},</span><spanclass=w></span><spanclass=mi>23</span><spanclass=p>);</span><spanclass=w></span>
<spanclass=n>j3</span><spanclass=p>.</span><spanclass=n>get_binary</span><spanclass=p>().</span><spanclass=n>subtype</span><spanclass=p>();</span><spanclass=w></span><spanclass=c1>// returns std::uint64_t(-1) as j3 has no subtype</span>
</code></pre></div><h2id=serialization>Serialization<aclass=headerlinkhref=#serializationtitle="Permanent link">¶</a></h2><p>Binary values are serialized differently according to the formats.</p><h3id=json>JSON<aclass=headerlinkhref=#jsontitle="Permanent link">¶</a></h3><p>JSON does not have a binary type, and this library does not introduce a new type as this would break conformance. Instead, binary values are serialized as an object with two keys: <code>bytes</code> holds an array of integers, and <code>subtype</code> is an integer or <code>null</code>.</p><detailsclass=example><summary>Example</summary><p>Code:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// create a binary value of subtype 42</span>
</code></pre></div></details><divclass="admonition warning"><pclass=admonition-title>No roundtrip for binary values</p><p>The JSON parser will not parse the objects generated by binary values back to binary values. This is by design to remain standards compliant. Serializing binary values to JSON is only implemented for debugging purposes.</p></div><h3id=bjdata>BJData<aclass=headerlinkhref=#bjdatatitle="Permanent link">¶</a></h3><p><ahref=../binary_formats/bjdata/>BJData</a> neither supports binary values nor subtypes, and proposes to serialize binary values as array of uint8 values. This translation is implemented by the library.</p><detailsclass=example><summary>Example</summary><p>Code:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// create a binary value of subtype 42 (will be ignored in BJData)</span>
</code></pre></div><p><code>v</code> is a <code>std::vector<std::uint8t></code> with the following 20 elements:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0x7B</span><spanclass=w></span><spanclass=c1>// '{'</span>
<spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x06</span><spanclass=w></span><spanclass=c1>// i 6 (length of the key)</span>
</code></pre></div><p>The following code uses the type and size optimization for UBJSON:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// convert to UBJSON using the size and type optimization</span>
</code></pre></div><p>The resulting vector has 22 elements; the optimization is not effective for examples with few values:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0x7B</span><spanclass=w></span><spanclass=c1>// '{'</span>
<spanclass=w></span><spanclass=mh>0x23</span><spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x01</span><spanclass=w></span><spanclass=c1>// '#''i' type of the array elements: unsigned integers</span>
<spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x06</span><spanclass=w></span><spanclass=c1>// i 6 (length of the key)</span>
<spanclass=w></span><spanclass=mh>0x24</span><spanclass=w></span><spanclass=mh>0x55</span><spanclass=w></span><spanclass=c1>// '$''U' type of the array elements: unsigned integers</span>
<spanclass=w></span><spanclass=mh>0x23</span><spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x04</span><spanclass=w></span><spanclass=c1>// '#' i 4 number of array elements</span>
</code></pre></div><p>Note that subtype (42) is <strong>not</strong> serialized and that UBJSON has <strong>no binary type</strong>, and deserializing <code>v</code> would yield the following value:</p><divclass=highlight><pre><span></span><code><spanclass=p>{</span><spanclass=w></span>
</code></pre></div></details><h3id=bson>BSON<aclass=headerlinkhref=#bsontitle="Permanent link">¶</a></h3><p><ahref=../binary_formats/bson/>BSON</a> supports binary values and subtypes. If a subtype is given, it is used and added as unsigned 8-bit integer. If no subtype is given, the generic binary subtype 0x00 is used.</p><detailsclass=example><summary>Example</summary><p>Code:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// create a binary value of subtype 42</span>
</code></pre></div><p><code>v</code> is a <code>std::vector<std::uint8t></code> with the following 22 elements:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0x16</span><spanclass=w></span><spanclass=mh>0x00</span><spanclass=w></span><spanclass=mh>0x00</span><spanclass=w></span><spanclass=mh>0x00</span><spanclass=w></span><spanclass=c1>// number of bytes in the document</span>
<spanclass=w></span><spanclass=mh>0x04</span><spanclass=w></span><spanclass=mh>0x00</span><spanclass=w></span><spanclass=mh>0x00</span><spanclass=w></span><spanclass=mh>0x00</span><spanclass=w></span><spanclass=c1>// number of bytes</span>
<spanclass=mh>0x00</span><spanclass=w></span><spanclass=c1>// end of the document</span>
</code></pre></div><p>Note that the serialization preserves the subtype, and deserializing <code>v</code> would yield the following value:</p><divclass=highlight><pre><span></span><code><spanclass=p>{</span><spanclass=w></span>
</code></pre></div></details><h3id=cbor>CBOR<aclass=headerlinkhref=#cbortitle="Permanent link">¶</a></h3><p><ahref=../binary_formats/cbor/>CBOR</a> supports binary values, but no subtypes. Subtypes will be serialized as tags. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array.</p><detailsclass=example><summary>Example</summary><p>Code:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// create a binary value of subtype 42</span>
</code></pre></div><p><code>v</code> is a <code>std::vector<std::uint8t></code> with the following 15 elements:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0xA1</span><spanclass=w></span><spanclass=c1>// map(1)</span>
</code></pre></div><p>Note that the subtype is serialized as tag. However, parsing tagged values yield a parse error unless <code>json::cbor_tag_handler_t::ignore</code> or <code>json::cbor_tag_handler_t::store</code> is passed to <code>json::from_cbor</code>.</p><divclass=highlight><pre><span></span><code><spanclass=p>{</span><spanclass=w></span>
</code></pre></div></details><h3id=messagepack>MessagePack<aclass=headerlinkhref=#messagepacktitle="Permanent link">¶</a></h3><p><ahref=../binary_formats/messagepack/>MessagePack</a> supports binary values and subtypes. If a subtype is given, the ext family is used. The library will choose the smallest representation among fixext1, fixext2, fixext4, fixext8, ext8, ext16, and ext32. The subtype is then added as signed 8-bit integer.</p><p>If no subtype is given, the bin family (bin8, bin16, bin32) is used.</p><detailsclass=example><summary>Example</summary><p>Code:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// create a binary value of subtype 42</span>
</code></pre></div><p><code>v</code> is a <code>std::vector<std::uint8t></code> with the following 14 elements:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0x81</span><spanclass=w></span><spanclass=c1>// fixmap1</span>
</code></pre></div><p>Note that the serialization preserves the subtype, and deserializing <code>v</code> would yield the following value:</p><divclass=highlight><pre><span></span><code><spanclass=p>{</span><spanclass=w></span>
</code></pre></div></details><h3id=ubjson>UBJSON<aclass=headerlinkhref=#ubjsontitle="Permanent link">¶</a></h3><p><ahref=../binary_formats/ubjson/>UBJSON</a> neither supports binary values nor subtypes, and proposes to serialize binary values as array of uint8 values. This translation is implemented by the library.</p><detailsclass=example><summary>Example</summary><p>Code:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// create a binary value of subtype 42 (will be ignored in UBJSON)</span>
</code></pre></div><p><code>v</code> is a <code>std::vector<std::uint8t></code> with the following 20 elements:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0x7B</span><spanclass=w></span><spanclass=c1>// '{'</span>
<spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x06</span><spanclass=w></span><spanclass=c1>// i 6 (length of the key)</span>
</code></pre></div><p>The following code uses the type and size optimization for UBJSON:</p><divclass=highlight><pre><span></span><code><spanclass=c1>// convert to UBJSON using the size and type optimization</span>
</code></pre></div><p>The resulting vector has 23 elements; the optimization is not effective for examples with few values:</p><divclass=highlight><pre><span></span><code><spanclass=mh>0x7B</span><spanclass=w></span><spanclass=c1>// '{'</span>
<spanclass=w></span><spanclass=mh>0x24</span><spanclass=w></span><spanclass=c1>// '$' type of the object elements</span>
<spanclass=w></span><spanclass=mh>0x23</span><spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x01</span><spanclass=w></span><spanclass=c1>// '#' i 1 number of object elements</span>
<spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x06</span><spanclass=w></span><spanclass=c1>// i 6 (length of the key)</span>
<spanclass=w></span><spanclass=mh>0x24</span><spanclass=w></span><spanclass=mh>0x55</span><spanclass=w></span><spanclass=c1>// '$''U' type of the array elements: unsigned integers</span>
<spanclass=w></span><spanclass=mh>0x23</span><spanclass=w></span><spanclass=mh>0x69</span><spanclass=w></span><spanclass=mh>0x04</span><spanclass=w></span><spanclass=c1>// '#' i 4 number of array elements</span>
</code></pre></div><p>Note that subtype (42) is <strong>not</strong> serialized and that UBJSON has <strong>no binary type</strong>, and deserializing <code>v</code> would yield the following value:</p><divclass=highlight><pre><span></span><code><spanclass=p>{</span><spanclass=w></span>
