deploy: 94fe31eb9b
This commit is contained in:
1 parent
41c601a7d1
commit
d2e264bd84
1400 files changed
+11859
-5440
No files matched your search
@@ -1,13 +1,22 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/binary_formats/bjdata/" rel="canonical"><link href=../ rel=prev><link href=../bon8/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>BJData - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#bjdata class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> BJData </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-searcLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/binary_formats/bjdata/" rel="canonical"><link href=../ rel=prev><link href=../bon8/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>BJData - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#bjdata class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> BJData </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-searcLine truncated
|
||||
<span class=w> </span><span class=nt>"id"</span><span class=p>:</span><span class=w> </span><span class=mi>300</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"json"</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"pi"</span><span class=p>:</span><span class=w> </span><span class=mf>3.14</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"tags"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
<span class=w> </span><span class=s2>"a"</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=s2>"b"</span>
|
||||
<span class=w> </span><span class=p>]</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p><code>to_bjdata</code> encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.</p> <div class=byte-layout markdown=0><table> <thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> <tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr> <tr><td><code>"id": 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">2C 01</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), little-endian</td></tr> <tr><td><code>"name": "json",</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr> <tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>key: length 2; value: float64 (<code>D</code>), little-endian</td></tr> <tr><td><code>"tags": [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr> <tr><td><code>"a",</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr> <tr><td><code>"b"</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr> <tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr> <tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr> </tbody></table></div> <h2 id=serialization>Serialization<a class=headerlink href=#serialization title="Permanent link">¶</a></h2> <p>The library uses the following mapping from <abbr title="JavaScript Object Notation">JSON</abbr> values types to <abbr title="Binary JData">BJData</abbr> types according to the <abbr title="Binary JData">BJData</abbr> specification:</p> <table> <thead> <tr> <th><abbr title="JavaScript Object Notation">JSON</abbr> value type</th> <th>value/range</th> <th><abbr title="Binary JData">BJData</abbr> type</th> <th>marker</th> </tr> </thead> <tbody> <tr> <td>null</td> <td><code>null</code></td> <td>null</td> <td><code>Z</code></td> </tr> <tr> <td>boolean</td> <td><code>true</code></td> <td>true</td> <td><code>T</code></td> </tr> <tr> <td>boolean</td> <td><code>false</code></td> <td>false</td> <td><code>F</code></td> </tr> <tr> <td>number_integer</td> <td>-9223372036854775808..-2147483649</td> <td>int64</td> <td><code>L</code></td> </tr> <tr> <td>number_integer</td> <td>-2147483648..-32769</td> <td>int32</td> <td><code>l</code></td> </tr> <tr> <td>number_integer</td> <td>-32768..-129</td> <td>int16</td> <td><code>I</code></td> </tr> <tr> <td>number_integer</td> <td>-128..127</td> <td>int8</td> <td><code>i</code></td> </tr> <tr> <td>number_integer</td> <td>128..255</td> <td>uint8</td> <td><code>U</code></td> </tr> <tr> <td>number_integer</td> <td>256..32767</td> <td>int16</td> <td><code>I</code></td> </tr> <tr> <td>number_integer</td> <td>32768..65535</td> <td>uint16</td> <td><code>u</code></td> </tr> <tr> <td>number_integer</td> <td>65536..2147483647</td> <td>int32</td> <td><code>l</code></td> </tr> <tr> <td>number_integer</td> <td>2147483648..4294967295</td> <td>uint32</td> <td><code>m</code></td> </tr> <tr> <td>number_integer</td> <td>4294967296..9223372036854775807</td> <td>int64</td> <td><code>L</code></td> </tr> <tr> <td>number_integer</td> <td>9223372036854775808..18446744073709551615</td> <td>uint64</td> <td><code>M</code></td> </tr> <tr> <td>number_unsigned</td> <td>0..127</td> <td>int8</td> <td><code>i</code></td> </tr> <tr> <td>number_unsigned</td> <td>128..255</td> <td>uint8</td> <td><code>U</code></td> </tr> <tr> <td>number_unsigned</td> <td>256..32767</td> <td>int16</td> <td><code>I</code></td> </tr> <tr> <td>number_unsigned</td> <td>32768..65535</td> <td>uint16</td> <td><code>u</code></td> </tr> <tr> <td>number_unsigned</td> <td>65536..2147483647</td> <td>int32</td> <td><code>l</code></td> </tr> <tr> <td>number_unsigned</td> <td>2147483648..4294967295</td> <td>uint32</td> <td><code>m</code></td> </tr> <tr> <td>number_unsigned</td> <td>4294967296..9223372036854775807</td> <td>int64</td> <td><code>L</code></td> </tr> <tr> <td>number_unsigned</td> <td>Line truncated
|
||||
<span class=w> </span><span class=nt>"_ArrayType_"</span><span class=p>:</span><span class=w> </span><span class=s2>"uint8"</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"_ArraySize_"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>],</span>
|
||||
<span class=w> </span><span class=nt>"_ArraySize_"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>3</span><span class=p>,</span><span class=mi>2</span><span class=p>],</span>
|
||||
<span class=w> </span><span class=nt>"_ArrayData_"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>,</span><span class=mi>4</span><span class=p>,</span><span class=mi>5</span><span class=p>,</span><span class=mi>6</span><span class=p>]</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Likewise, when a <abbr title="JavaScript Object Notation">JSON</abbr> object in the above form is serialized using <a href=../../../api/basic_json/to_bjdata/ ><code>to_bjdata</code></a>, it is automatically converted into a compact <abbr title="Binary JData">BJData</abbr> ND-array.</p> <p>When parsing, an ND-array whose dimension vector is empty, contains a single integer, contains two integers with the first being 1, or contains a 0 is returned as a regular (possibly empty) array rather than an annotated object.</p> <p>An object is only converted if the annotation describes a packed array that is parsed back into the same annotated object; otherwise it is serialized as a regular <abbr title="JavaScript Object Notation">JSON</abbr> object, so the annotation is never lost in a round trip. This requires all of the following:</p> <ul> <li><code>"_ArrayType_"</code> is one of <code>uint8</code>, <code>int8</code>, <code>uint16</code>, <code>int16</code>, <code>uint32</code>, <code>int32</code>, <code>uint64</code>, <code>int64</code>, <code>single</code>, <code>double</code>, <code>char</code>, or <code>byte</code>,</li> <li><code>"_ArraySize_"</code> is an array, since the dimensions are written as the ND-array header's length,</li> <li><code>"_ArraySize_"</code> has at least two entries and is not a 1×N row vector (first entry 1), since other shapes are parsed back as a regular array,</li> <li>every entry of <code>"_ArraySize_"</code> is a positive integer, and their product is representable as a <code>std::size_t</code>,</li> <li><code>"_ArrayData_"</code> is an array holding exactly that many elements, and</li> <li>every element of <code>"_ArrayData_"</code> is a number of the kind named by <code>"_ArrayType_"</code>: for the integer types, a value that fits the named width; for <code>double</code>, any value; for <code>single</code>, a value that survives narrowing to <code>float</code> and back without change (for instance, <code>0.1</code> does not, since it is not exactly representable as <code>float</code>).</li> </ul> <p>An annotated object is always read back with its keys in the order shown above, <code>"_ArrayType_"</code>, <code>"_ArraySize_"</code>, <code>"_ArrayData_"</code>, regardless of the order the ND-array's header stores them in on the wire. This matters for <code>ordered_json</code>, whose comparison takes key order into account.</p> <p>The current version of this library does not yet support automatic detection of and conversion from a nested <abbr title="JavaScript Object Notation">JSON</abbr> array input to a <abbr title="Binary JData">BJData</abbr> ND-array.</p> </div> <div class="admonition info"> <p class=admonition-title>Restrictions in optimized data types for arrays and objects</p> <p>Due to diminished space saving, hampered readability, and increased security risks, in <abbr title="Binary JData">BJData</abbr>, the allowed data types following the <code>$</code> marker in an optimized array and object container are restricted to <strong>non-zero-fixed-length</strong> data types. Therefore, the valid optimized type markers can only be one of <code>UiuImlMLhdDCB</code>. This also means other variable (<code>[{SH</code>) or zero-length types (<code>TFN</code>) can not be used in an optimized array or object in <abbr title="Binary JData">BJData</abbr>.</p> </div> <div class="admonition info"> <p class=admonition-title>Binary values</p> <p><abbr title="Binary JData">BJData</abbr> provides a dedicated <code>B</code> marker (defined in the <a href="https://github.com/NeuroJSON/bjdata/blob/master/Binary_JData_Specification.md#optimized-binary-array"><abbr title="Binary JData">BJData</abbr> specification (Draft 3)</a>) that is used in optimized arrays to designate binary data. This means that, unlike <abbr title="Universal Binary JSON">UBJSON</abbr>, binary data can be both serialized and deserialized.</p> <p>To preserve compatibility with <abbr title="Binary JData">BJData</abbr> Draft 2, the Draft 3 optimized binary array must be explicitly enabled using the <code>version</code> parameter of <a href=../../../api/basic_json/to_bjdata/ ><code>to_bjdata</code></a>.</p> <p>In Draft2 mode (default), if the <abbr title="JavaScript Object Notation">JSON</abbr> data contains the binary type, the value stored as a list of integers, as suggested by the <abbr title="Binary JData">BJData</abbr> documentation. In particular, this means that the serialization and the deserialization of <abbr title="JavaScript Object Notation">JSON</abbr> containing binary values into <abbr title="Binary JData">BJData</abbr> and back will result in a different <abbr title="JavaScript Object Notation">JSON</abbr> object.</p> </div> <details class=example> <summary>Example: serialize <abbr title="JavaScript Object Notation">JSON</abbr> values to <abbr title="Binary JData">BJData</abbr>, with and without size/type optimization</summary> <div class=highlight><pre><span></span><code><span class=cp>Line truncated
|
||||
</code></pre></div> <p>ND-arrays with the element type <code>h</code> (float16) are returned with <code>"_ArrayType_": "half"</code>. <code>to_bjdata</code> does not pack <code>"half"</code> objects; they are written as regular objects, which read back as an equal value.</p> <p>Likewise, when a <abbr title="JavaScript Object Notation">JSON</abbr> object in the above form is serialized using <a href=../../../api/basic_json/to_bjdata/ ><code>to_bjdata</code></a>, it is automatically converted into a compact <abbr title="Binary JData">BJData</abbr> ND-array.</p> <p>When parsing, an ND-array whose dimension vector is empty, contains a single integer, contains two integers with the first being 1, or contains a 0 is returned as a regular (possibly empty) array rather than an annotated object.</p> <p>An object is only converted if the annotation describes a packed array that is parsed back into the same annotated object; otherwise it is serialized as a regular <abbr title="JavaScript Object Notation">JSON</abbr> object, so the annotation is never lost in a round trip. This requires all of the following:</p> <ul> <li>the object has exactly the three keys <code>"_ArrayType_"</code>, <code>"_ArraySize_"</code>, and <code>"_ArrayData_"</code> (any other key, e.g., <code>"_ArrayOrder_"</code>, makes it a regular object),</li> <li><code>"_ArrayType_"</code> is one of <code>uint8</code>, <code>int8</code>, <code>uint16</code>, <code>int16</code>, <code>uint32</code>, <code>int32</code>, <code>uint64</code>, <code>int64</code>, <code>single</code>, <code>double</code>, <code>char</code>, or (only with <code>version = bjdata_version_t::draft3</code>, since the <code>B</code> marker is not part of Draft 2) <code>byte</code>; the names are case-sensitive,</li> <li><code>"_ArraySize_"</code> is an array, since the dimensions are written as the ND-array header's length,</li> <li><code>"_ArraySize_"</code> has at least two entries and is not a two-entry row vector (<code>[1,N]</code>), since other shapes are parsed back as a regular array (<code>[1,2,2]</code> is packed, <code>[1,4]</code> is not),</li> <li>every entry of <code>"_ArraySize_"</code> is a positive integer, and their product is representable as a <code>std::size_t</code>,</li> <li><code>"_ArrayData_"</code> is an array holding exactly that many elements, and</li> <li>every element of <code>"_ArrayData_"</code> is a number of the kind named by <code>"_ArrayType_"</code>: for the integer types, an integer (a floating-point number such as <code>1.0</code> does not qualify) that fits the named width (for <code>char</code>, 0..127); for <code>double</code>, a floating-point number (an integer such as <code>1</code> does not qualify); for <code>single</code>, a floating-point number that survives narrowing to <code>float</code> and back without change (for instance, <code>0.1</code> does not, since it is not exactly representable as <code>float</code>).</li> </ul> <p>With <code>ordered_json</code>, an annotated object read from <abbr title="Binary JData">BJData</abbr> has its keys in the order <code>"_ArrayType_"</code>, <code>"_ArraySize_"</code>, <code>"_ArrayData_"</code>; with <code>json</code>, they are sorted like those of any other object.</p> <p>The current version of this library does not yet support automatic detection of and conversion from a nested <abbr title="JavaScript Object Notation">JSON</abbr> array input to a <abbr title="Binary JData">BJData</abbr> ND-array.</p> </div> <div class="admonition info"> <p class=admonition-title>Restrictions in optimized data types for arrays and objects</p> <p>Due to diminished space saving, hampered readability, and increased security risks, in <abbr title="Binary JData">BJData</abbr>, the allowed data types following the <code>$</code> marker in an optimized array and object container are restricted to <strong>non-zero-fixed-length</strong> data types. Therefore, the valid optimized type markers can only be one of <code>UiuImlMLhdDC</code>, plus <code>B</code> since Draft 3 (the reader accepts <code>B</code> in both drafts). This also means other variable (<code>[{SH</code>) or zero-length types (<code>TFZN</code>) can not be used in an optimized array or object in <abbr title="Binary JData">BJData</abbr>. The library enforces this restriction for both drafts. A <code>C</code> (char) element above 127 is rejected on read with <a href=../../../home/exceptions/#jsonexceptionparse_error113><code>parse_error.113</code></a>, in 1-D and in N-dimensional arrays. With <code>use_type</code>, the elements must have the same marker (<code>[1,200,3]</code> is not optimized, since it mixes <code>i</code> and <code>U</code>); booleans, null, strings, arrays, and objects are never optimized with <code>$</code>.</p> </div> <div class="admonition info"> <p class=admonition-title>Binary values</p> <p><abbr title="Binary JData">BJData</abbr> provides a dedicated <code>B</code> marker (defined in the <a href="https://github.com/NeuroJSOLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=k>namespace</span><span class=w> </span><span class=nn>nlohmann</span><span class=o>::</span><span class=nn>literals</span><span class=p>;</span>
|
||||
|
||||
<span class=c1>// function to print BJData's diagnostic format</span>
|
||||
@@ -15,11 +24,11 @@
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=k>if</span><span class=w> </span><span class=p>(</span><span class=mi>32</span><span class=w> </span><span class=o><</span><span class=w> </span><span class=kt>byte</span><span class=w> </span><span class=k>and</span><span class=w> </span><span class=kt>byte</span><span class=w> </span><span class=o><</span><span class=w> </span><span class=mi>128</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=p>(</span><span class=kt>char</span><span class=p>)</span><span class=kt>byte</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=k>static_cast</span><span class=o><</span><span class=kt>char</span><span class=o>></span><span class=p>(</span><span class=kt>byte</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>else</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=p>(</span><span class=kt>int</span><span class=p>)</span><span class=kt>byte</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=k>static_cast</span><span class=o><</span><span class=kt>int</span><span class=o>></span><span class=p>(</span><span class=kt>byte</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=p>}</span>
|
||||
|
||||
@@ -36,7 +45,7 @@
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>print_byte</span><span class=p>(</span><span class=kt>byte</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// create an array of numbers</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>array</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>,</span><span class=w> </span><span class=mi>3</span><span class=p>,</span><span class=w> </span><span class=mi>4</span><span class=p>,</span><span class=w> </span><span class=mi>5</span><span class=p>,</span><span class=w> </span><span class=mi>6</span><span class=p>,</span><span class=w> </span><span class=mi>7</span><span class=p>,</span><span class=w> </span><span class=mi>8</span><span class=p>};</span>
|
||||
@@ -53,38 +62,29 @@
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>print_byte</span><span class=p>(</span><span class=kt>byte</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=k>for</span><span class=w> </span><span class=p>(</span><span class=k>auto</span><span class=o>&</span><span class=w> </span><span class=kt>byte</span><span class=w> </span><span class=o>:</span><span class=w> </span><span class=n>v_array_size</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>print_byte</span><span class=p>(</span><span class=kt>byte</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=k>for</span><span class=w> </span><span class=p>(</span><span class=k>auto</span><span class=o>&</span><span class=w> </span><span class=kt>byte</span><span class=w> </span><span class=o>:</span><span class=w> </span><span class=n>v_array_size_and_type</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>print_byte</span><span class=p>(</span><span class=kt>byte</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>{</span><span class=n>i7compactTi6schemaF</span><span class=p>}</span>
|
||||
<span class=p>[</span><span class=n>i1i2i3i4i5i6i7i8</span><span class=p>]</span>
|
||||
<span class=p>[</span><span class=err>#</span><span class=n>i8i1i2i3i4i5i6i7i8</span>
|
||||
<span class=p>[</span><span class=n>$i</span><span class=err>#</span><span class=n>i812345678</span>
|
||||
</code></pre></div> </details> <h3 id=byte-layout>Byte layout<a class=headerlink href=#byte-layout title="Permanent link">¶</a></h3> <p>Consider the following <abbr title="JavaScript Object Notation">JSON</abbr> value (shown formatted for readability):</p> <div class=highlight><pre><span></span><code><span class=p>{</span>
|
||||
<span class=w> </span><span class=nt>"id"</span><span class=p>:</span><span class=w> </span><span class=mi>300</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"json"</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"pi"</span><span class=p>:</span><span class=w> </span><span class=mf>3.14</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"tags"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
<span class=w> </span><span class=s2>"a"</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=s2>"b"</span>
|
||||
<span class=w> </span><span class=p>]</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p><code>to_bjdata</code> encodes it to 51 bytes (shown in hexadecimal; the encoding contains no whitespace). The colors mark the role of each byte: <span class="bl bl-t">type/marker</span> <span class="bl bl-l">length/count/size</span> <span class="bl bl-d">data</span>.</p> <div class=byte-layout markdown=0><table> <thead><tr><th>JSON</th><th>Bytes</th><th>Meaning</th></tr></thead><tbody> <tr><td><code>{</code></td><td><span class="bl bl-t">7B</span></td><td>object start (<code>{</code>)</td></tr> <tr><td><code>"id": 300,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">69 64</span> <span class="bl bl-t">49</span> <span class="bl bl-d">2C 01</span></td><td>key: length 2 as int8 (<code>i</code>), then UTF-8 bytes; value: int16 (<code>I</code>), little-endian</td></tr> <tr><td><code>"name": "json",</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">6E 61 6D 65</span> <span class="bl bl-t">53</span> <span class="bl bl-l">69 04</span> <span class="bl bl-d">6A 73 6F 6E</span></td><td>key: length 4; value: string (<code>S</code>), length 4 as int8, UTF-8 bytes</td></tr> <tr><td><code>"pi": 3.14,</code></td><td><span class="bl bl-l">69 02</span> <span class="bl bl-d">70 69</span> <span class="bl bl-t">44</span> <span class="bl bl-d">1F 85 EB 51 B8 1E 09 40</span></td><td>key: length 2; value: float64 (<code>D</code>), little-endian</td></tr> <tr><td><code>"tags": [</code></td><td><span class="bl bl-l">69 04</span> <span class="bl bl-d">74 61 67 73</span> <span class="bl bl-t">5B</span></td><td>key: length 4; value: array start (<code>[</code>)</td></tr> <tr><td><code>"a",</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">61</span></td><td>string, length 1</td></tr> <tr><td><code>"b"</code></td><td><span class="bl bl-t">53</span> <span class="bl bl-l">69 01</span> <span class="bl bl-d">62</span></td><td>string, length 1</td></tr> <tr><td><code>]</code></td><td><span class="bl bl-t">5D</span></td><td>array end (<code>]</code>)</td></tr> <tr><td><code>}</code></td><td><span class="bl bl-t">7D</span></td><td>object end (<code>}</code>)</td></tr> </tbody></table></div> <h2 id=deserialization>Deserialization<a class=headerlink href=#deserialization title="Permanent link">¶</a></h2> <p>The library maps <abbr title="Binary JData">BJData</abbr> types to <abbr title="JavaScript Object Notation">JSON</abbr> value types as follows:</p> <table> <thead> <tr> <th><abbr title="Binary JData">BJData</abbr> type</th> <th><abbr title="JavaScript Object Notation">JSON</abbr> value type</th> <th>marker</th> </tr> </thead> <tbody> <tr> <td>no-op</td> <td><em>no value, next value is read</em></td> <td><code>N</code></td> </tr> <tr> <td>null</td> <td><code>null</code></td> <td><code>Z</code></td> </tr> <tr> <td>false</td> <td><code>false</code></td> <td><code>F</code></td> </tr> <tr> <td>true</td> <td><code>true</code></td> <td><code>T</code></td> </tr> <tr> <td>float16</td> <td>number_float</td> <td><code>h</code></td> </tr> <tr> <td>float32</td> <td>number_float</td> <td><code>d</code></td> </tr> <tr> <td>float64</td> <td>number_float</td> <td><code>D</code></td> </tr> <tr> <td>uint8</td> <td>number_unsigned</td> <td><code>U</code></td> </tr> <tr> <td>int8</td> <td>number_integer</td> <td><code>i</code></td> </tr> <tr> <td>uint16</td> <td>number_unsigned</td> <td><code>u</code></td> </tr> <tr> <td>int16</td> <td>number_integer</td> <td><code>I</code></td> </tr> <tr> <td>uint32</td> <td>number_unsigned</td> <td><code>m</code></td> </tr> <tr> <td>int32</td> <td>number_integer</td> <td><code>l</code></td> </tr> <tr> <td>uint64</td> <td>number_unsigned</td> <td><code>M</code></td> </tr> <tr> <td>int64</td> <td>number_integer</td> <td><code>L</code></td> </tr> <tr> <td>byte</td> <td>number_unsigned</td> <td><code>B</code></td> </tr> <tr> <td>string</td> <td>string</td> <td><code>S</code></td> </tr> <tr> <td>char</td> <td>string</td> <td><code>C</code></td> </tr> <tr> <td>array</td> <td>array (optimized values are supported)</td> <td><code>[</code></td> </tr> <tr> <td>ND-array</td> <td>object (in JData annotated array format)</td> <td><code>[$.#[.</code></td> </tr> <tr> <td>object</td> <td>object (optimized values are supported)</td> <td><code>{</code></td> </tr> <tr> <td>binary</td> <td>binary (strongly-typed byte array)</td> <td><code>[$B</code></td> </tr> </tbody> </table> <div class="admonition success"> <p class=admonition-title>Complete mapping</p> <p>The mapping is <strong>complete</strong> in the sense that any <abbr title="Binary JData">BJData</abbr> value can be converted to a <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> </div> <div class="admonition warning"> <p class=admonition-title>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-8 in string values and object keys</p> <p><abbr title="Binary JData">BJDaLine truncated
|
||||
</code></pre></div> </details> <h2 id=deserialization>Deserialization<a class=headerlink href=#deserialization title="Permanent link">¶</a></h2> <p>The library maps <abbr title="Binary JData">BJData</abbr> types to <abbr title="JavaScript Object Notation">JSON</abbr> value types as follows:</p> <table> <thead> <tr> <th><abbr title="Binary JData">BJData</abbr> type</th> <th><abbr title="JavaScript Object Notation">JSON</abbr> value type</th> <th>marker</th> </tr> </thead> <tbody> <tr> <td>no-op</td> <td><em>no value, next value is read</em></td> <td><code>N</code></td> </tr> <tr> <td>null</td> <td><code>null</code></td> <td><code>Z</code></td> </tr> <tr> <td>false</td> <td><code>false</code></td> <td><code>F</code></td> </tr> <tr> <td>true</td> <td><code>true</code></td> <td><code>T</code></td> </tr> <tr> <td>float16</td> <td>number_float</td> <td><code>h</code></td> </tr> <tr> <td>float32</td> <td>number_float</td> <td><code>d</code></td> </tr> <tr> <td>float64</td> <td>number_float</td> <td><code>D</code></td> </tr> <tr> <td>high-precision number</td> <td>number_integer, number_unsigned, or number_float</td> <td><code>H</code></td> </tr> <tr> <td>uint8</td> <td>number_unsigned</td> <td><code>U</code></td> </tr> <tr> <td>int8</td> <td>number_integer</td> <td><code>i</code></td> </tr> <tr> <td>uint16</td> <td>number_unsigned</td> <td><code>u</code></td> </tr> <tr> <td>int16</td> <td>number_integer</td> <td><code>I</code></td> </tr> <tr> <td>uint32</td> <td>number_unsigned</td> <td><code>m</code></td> </tr> <tr> <td>int32</td> <td>number_integer</td> <td><code>l</code></td> </tr> <tr> <td>uint64</td> <td>number_unsigned</td> <td><code>M</code></td> </tr> <tr> <td>int64</td> <td>number_integer</td> <td><code>L</code></td> </tr> <tr> <td>byte</td> <td>number_unsigned</td> <td><code>B</code></td> </tr> <tr> <td>string</td> <td>string</td> <td><code>S</code></td> </tr> <tr> <td>char</td> <td>string</td> <td><code>C</code></td> </tr> <tr> <td>array</td> <td>array (optimized values are supported)</td> <td><code>[</code></td> </tr> <tr> <td>ND-array</td> <td>object (in JData annotated array format)</td> <td><code>[$.#[.</code></td> </tr> <tr> <td>object</td> <td>object (optimized values are supported)</td> <td><code>{</code></td> </tr> <tr> <td>binary</td> <td>binary (strongly-typed byte array)</td> <td><code>[$B</code></td> </tr> </tbody> </table> <div class="admonition success"> <p class=admonition-title>Complete mapping</p> <p>The mapping is <strong>complete</strong> for the <abbr title="Binary JData">BJData</abbr> types of Draft 2 and Draft 3 with one exception: column-major N-dimensional arrays are rejected with <a href=../../../home/exceptions/#jsonexceptionparse_error113><code>parse_error.113</code></a>. The Draft 4 constructs (structure-of-arrays containers and the extension type <code>E</code>) are not supported either.</p> <p>The digits of an <code>H</code> value are parsed like a <abbr title="JavaScript Object Notation">JSON</abbr> number: integers that fit 64 bits become <code>number_integer</code> or <code>number_unsigned</code>, anything else a <code>number_float</code>; invalid text throws <a href=../../../home/exceptions/#jsonexceptionparse_error115><code>parse_error.115</code></a>.</p> </div> <div class="admonition info"> <p class=admonition-title>Duplicate object keys</p> <p>If an object contains the same key more than once, <code>from_bjdata</code> accepts it and keeps the last value; with <code>ordered_json</code>, the key keeps the position of its first occurrence.</p> </div> <div class="admonition warning"> <p class=admonition-title>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-8 in string values and object keys</p> <p><abbr title="Binary JData">BJData</abbr> strings must use <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoding, but checking it on read is opt-in: with the <a href=../../../api/basic_json/from_bjdata/ ><code>error_handler</code></a> parameter left at <code>keep</code> (the default), <code>from_bjdata()</code> accepts a string value or object key whose bytes are not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and hands them back unchanged. Passing <code>error_handler_t::strict</code> makes <code>from_bjdata()</code> check and throw <a href=../../../home/exceptions/#jsonexceptionparse_error113><code>parse_error.113</code></a> for ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-8, and <code>replace</code>/<code>ignore</code> sanitize the string instead of keeping it. However, <a href=../../../api/basic_json/dump/ ><code>dump()</code></a> still requires valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and throws <a href=../../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> for a value read with the default <code>keep</code> handler, unless an error handler is passed that replaces or ignores the ill-formed bytes. <code>to_bjdata()</code>'s own <code>error_handler</cLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -98,10 +98,10 @@
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>from_bjdata</span><span class=p>(</span><span class=n>v</span><span class=p>);</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// print the deserialized JSON value</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setw</span><span class=p>(</span><span class=mi>2</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>setw</span><span class=p>(</span><span class=mi>2</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>{</span>
|
||||
<span class=w> </span><span class=nt>"compact"</span><span class=p>:</span><span class=w> </span><span class=kc>true</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"schema"</span><span class=p>:</span><span class=w> </span><span class=mi>0</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 24, 2026 15:57:44 UTC">October 24, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 14Line truncated
|
||||
</code></pre></div> </details> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 26, 2026 17:25:46 UTC">October 26, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 14Line truncated
|
||||
@@ -1,209 +1,27 @@
|
||||
# BJData
|
||||
|
||||
The [BJData format](https://neurojson.org) was derived from and improved upon [Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). Specifically, it introduces an optimized array container for efficient storage of N-dimensional packed arrays (**ND-arrays**); it also adds 5 new type markers - `[u] - uint16`, `[m] - uint32`, `[M] - uint64`, `[h] - float16` and `[B] - byte` - to unambiguously map common binary numeric types; furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid unnecessary conversions on commonly available platforms.
|
||||
The [BJData format](https://neurojson.org) was derived from and improved upon [Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). Specifically, it introduces an optimized array container for efficient storage of N-dimensional packed arrays (**ND-arrays**); it also adds four new type markers - `[u] - uint16`, `[m] - uint32`, `[M] - uint64`, and `[h] - float16` - to unambiguously map common binary numeric types (Draft 3 adds `[B] - byte`); furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid unnecessary conversions on commonly available platforms.
|
||||
|
||||
Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare combination of being both binary and **quasi-human-readable**. This is because all semantic elements in BJData and UBJSON, including the data-type markers and name/string types, are directly human-readable. Data stored in the BJData/UBJSON format is not only compact in size, fast to read/write, but also can be directly searched or read using simple processing.
|
||||
|
||||
References
|
||||
|
||||
- [BJData Specification](https://neurojson.org/bjdata/draft2)
|
||||
- [BJData Specification (Draft 3)](https://neurojson.org/bjdata/draft3)
|
||||
- [BJData Specification (Draft 2)](https://neurojson.org/bjdata/draft2)
|
||||
|
||||
## Serialization
|
||||
Supported drafts
|
||||
|
||||
The library uses the following mapping from JSON values types to BJData types according to the BJData specification:
|
||||
The library supports BJData Draft 2 (the default) and Draft 3, except for column-major N-dimensional arrays (see below). The draft used for writing is selected with the [`version` parameter](https://json.nlohmann.me/api/basic_json/bjdata_version_t/index.md) of [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md); [`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md) has no such parameter and reads the markers of both drafts.
|
||||
|
||||
| JSON value type | value/range | BJData type | marker |
|
||||
| --------------- | ----------------------------------------- | ----------- | ------ |
|
||||
| null | `null` | null | `Z` |
|
||||
| boolean | `true` | true | `T` |
|
||||
| boolean | `false` | false | `F` |
|
||||
| number_integer | -9223372036854775808..-2147483649 | int64 | `L` |
|
||||
| number_integer | -2147483648..-32769 | int32 | `l` |
|
||||
| number_integer | -32768..-129 | int16 | `I` |
|
||||
| number_integer | -128..127 | int8 | `i` |
|
||||
| number_integer | 128..255 | uint8 | `U` |
|
||||
| number_integer | 256..32767 | int16 | `I` |
|
||||
| number_integer | 32768..65535 | uint16 | `u` |
|
||||
| number_integer | 65536..2147483647 | int32 | `l` |
|
||||
| number_integer | 2147483648..4294967295 | uint32 | `m` |
|
||||
| number_integer | 4294967296..9223372036854775807 | int64 | `L` |
|
||||
| number_integer | 9223372036854775808..18446744073709551615 | uint64 | `M` |
|
||||
| number_unsigned | 0..127 | int8 | `i` |
|
||||
| number_unsigned | 128..255 | uint8 | `U` |
|
||||
| number_unsigned | 256..32767 | int16 | `I` |
|
||||
| number_unsigned | 32768..65535 | uint16 | `u` |
|
||||
| number_unsigned | 65536..2147483647 | int32 | `l` |
|
||||
| number_unsigned | 2147483648..4294967295 | uint32 | `m` |
|
||||
| number_unsigned | 4294967296..9223372036854775807 | int64 | `L` |
|
||||
| number_unsigned | 9223372036854775808..18446744073709551615 | uint64 | `M` |
|
||||
| number_float | *any value* | float64 | `D` |
|
||||
| string | *with shortest length indicator* | string | `S` |
|
||||
| array | *see notes on optimized format/ND-array* | array | `[` |
|
||||
| object | *see notes on optimized format* | map | `{` |
|
||||
| binary | *see notes on binary values* | array | `[$B` |
|
||||
Draft 4 and column-major ND-arrays are not supported
|
||||
|
||||
Complete mapping
|
||||
BJData Draft 4 (April 2026) adds structure-of-arrays (SoA) containers (`[$` or `{$` followed by a schema object) and the extension type `E`. `from_bjdata` does not implement them and throws [`parse_error.112`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) for such input; `to_bjdata` never writes them.
|
||||
|
||||
The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value.
|
||||
Likewise, column-major ND-arrays of Draft 3 (the `#` marker followed by an array that wraps the dimension vector) are rejected with [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113).
|
||||
|
||||
Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`.
|
||||
## Byte layout
|
||||
|
||||
Size constraints
|
||||
|
||||
The following values can **not** be converted to a BJData value:
|
||||
|
||||
- strings with more than 18446744073709551615 bytes, i.e., 264-1 bytes (theoretical)
|
||||
|
||||
UTF-8 validation of string values and object keys
|
||||
|
||||
BJData strings must use UTF-8 encoding. By default (the [`error_handler`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) parameter left at `keep`), `to_bjdata()` writes the bytes of string values and object keys unchanged, even if they are not valid UTF-8. With `error_handler_t::strict`, it throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) for ill-formed UTF-8 instead; `replace`/`ignore` sanitize the string. [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) makes `strict` the default.
|
||||
|
||||
Unused BJData markers
|
||||
|
||||
The following markers are not used in the conversion:
|
||||
|
||||
- `Z`: no-op values are not created.
|
||||
- `C`: single-byte strings are serialized with `S` markers.
|
||||
|
||||
NaN/infinity handling
|
||||
|
||||
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the [`dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) function which serializes NaN or Infinity to `null`.
|
||||
|
||||
Endianness
|
||||
|
||||
A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on most modern computers where LE is used as the default byte order.
|
||||
|
||||
Optimized formats
|
||||
|
||||
Optimized formats for containers are supported via two parameters of [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md):
|
||||
|
||||
- Parameter `use_size` adds size information to the beginning of a container and removes the closing marker.
|
||||
- Parameter `use_type` further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be used together with `use_size = true`.
|
||||
|
||||
Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed of the number of elements in the container.
|
||||
|
||||
ND-array optimized format
|
||||
|
||||
BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types (referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6` or `[$U#[i2 i3] 1 2 3 4 5 6`.
|
||||
|
||||
To maintain type and size information, ND-arrays are converted to JSON objects following the **annotated array format** (defined in the [JData specification (Draft 3)](https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays)), when parsed using [`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md). For example, the above 2-D `uint8` array can be parsed and accessed as
|
||||
|
||||
```
|
||||
{
|
||||
"_ArrayType_": "uint8",
|
||||
"_ArraySize_": [2,3],
|
||||
"_ArrayData_": [1,2,3,4,5,6]
|
||||
}
|
||||
```
|
||||
|
||||
Likewise, when a JSON object in the above form is serialized using [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md), it is automatically converted into a compact BJData ND-array.
|
||||
|
||||
When parsing, an ND-array whose dimension vector is empty, contains a single integer, contains two integers with the first being 1, or contains a 0 is returned as a regular (possibly empty) array rather than an annotated object.
|
||||
|
||||
An object is only converted if the annotation describes a packed array that is parsed back into the same annotated object; otherwise it is serialized as a regular JSON object, so the annotation is never lost in a round trip. This requires all of the following:
|
||||
|
||||
- `"_ArrayType_"` is one of `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, `single`, `double`, `char`, or `byte`,
|
||||
- `"_ArraySize_"` is an array, since the dimensions are written as the ND-array header's length,
|
||||
- `"_ArraySize_"` has at least two entries and is not a 1×N row vector (first entry 1), since other shapes are parsed back as a regular array,
|
||||
- every entry of `"_ArraySize_"` is a positive integer, and their product is representable as a `std::size_t`,
|
||||
- `"_ArrayData_"` is an array holding exactly that many elements, and
|
||||
- every element of `"_ArrayData_"` is a number of the kind named by `"_ArrayType_"`: for the integer types, a value that fits the named width; for `double`, any value; for `single`, a value that survives narrowing to `float` and back without change (for instance, `0.1` does not, since it is not exactly representable as `float`).
|
||||
|
||||
An annotated object is always read back with its keys in the order shown above, `"_ArrayType_"`, `"_ArraySize_"`, `"_ArrayData_"`, regardless of the order the ND-array's header stores them in on the wire. This matters for `ordered_json`, whose comparison takes key order into account.
|
||||
|
||||
The current version of this library does not yet support automatic detection of and conversion from a nested JSON array input to a BJData ND-array.
|
||||
|
||||
Restrictions in optimized data types for arrays and objects
|
||||
|
||||
Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data types following the `$` marker in an optimized array and object container are restricted to **non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDCB`. This also means other variable (`[{SH`) or zero-length types (`TFN`) can not be used in an optimized array or object in BJData.
|
||||
|
||||
Binary values
|
||||
|
||||
BJData provides a dedicated `B` marker (defined in the [BJData specification (Draft 3)](https://github.com/NeuroJSON/bjdata/blob/master/Binary_JData_Specification.md#optimized-binary-array)) that is used in optimized arrays to designate binary data. This means that, unlike UBJSON, binary data can be both serialized and deserialized.
|
||||
|
||||
To preserve compatibility with BJData Draft 2, the Draft 3 optimized binary array must be explicitly enabled using the `version` parameter of [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md).
|
||||
|
||||
In Draft2 mode (default), if the JSON data contains the binary type, the value stored as a list of integers, as suggested by the BJData documentation. In particular, this means that the serialization and the deserialization of JSON containing binary values into BJData and back will result in a different JSON object.
|
||||
|
||||
Example: serialize JSON values to BJData, with and without size/type optimization
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
// function to print BJData's diagnostic format
|
||||
void print_byte(uint8_t byte)
|
||||
{
|
||||
if (32 < byte and byte < 128)
|
||||
{
|
||||
std::cout << (char)byte;
|
||||
}
|
||||
else
|
||||
{
|
||||
std::cout << (int)byte;
|
||||
}
|
||||
}
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON value
|
||||
json j = R"({"compact": true, "schema": false})"_json;
|
||||
|
||||
// serialize it to BJData
|
||||
std::vector<std::uint8_t> v = json::to_bjdata(j);
|
||||
|
||||
// print the vector content
|
||||
for (auto& byte : v)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << std::endl;
|
||||
|
||||
// create an array of numbers
|
||||
json array = {1, 2, 3, 4, 5, 6, 7, 8};
|
||||
|
||||
// serialize it to BJData using default representation
|
||||
std::vector<std::uint8_t> v_array = json::to_bjdata(array);
|
||||
// serialize it to BJData using size optimization
|
||||
std::vector<std::uint8_t> v_array_size = json::to_bjdata(array, true);
|
||||
// serialize it to BJData using type optimization
|
||||
std::vector<std::uint8_t> v_array_size_and_type = json::to_bjdata(array, true, true);
|
||||
|
||||
// print the vector contents
|
||||
for (auto& byte : v_array)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << std::endl;
|
||||
|
||||
for (auto& byte : v_array_size)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << std::endl;
|
||||
|
||||
for (auto& byte : v_array_size_and_type)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << std::endl;
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
{i7compactTi6schemaF}
|
||||
[i1i2i3i4i5i6i7i8]
|
||||
[#i8i1i2i3i4i5i6i7i8
|
||||
[$i#i812345678
|
||||
```
|
||||
|
||||
### Byte layout
|
||||
BJData follows the structure of UBJSON: a one-byte, human-readable ASCII *type marker* followed by the payload of that type, with strings prefixed by a length that is itself an integer value. In contrast to UBJSON, numbers are stored in little-endian byte order, and additional markers cover unsigned 16/32/64-bit integers, half-precision floats, and bytes. Containers can be written unoptimized (opened with `[` or `{`, closed with `]` or `}`) or optimized with a count (`#`), optionally preceded by a declared element type (`$`). BJData extends the optimized form: the count can be a list of dimensions, which stores an N-dimensional packed array as a flat sequence of values without any per-element markers.
|
||||
|
||||
Consider the following JSON value (shown formatted for readability):
|
||||
|
||||
@@ -233,38 +51,246 @@ Consider the following JSON value (shown formatted for readability):
|
||||
| `]` | 5D | array end (`]`) |
|
||||
| `}` | 7D | object end (`}`) |
|
||||
|
||||
## Serialization
|
||||
|
||||
The library uses the following mapping from JSON values types to BJData types according to the BJData specification:
|
||||
|
||||
| JSON value type | value/range | BJData type | marker |
|
||||
| --------------- | ----------------------------------------- | ----------- | ----------------------------------------------------------------------- |
|
||||
| null | `null` | null | `Z` |
|
||||
| boolean | `true` | true | `T` |
|
||||
| boolean | `false` | false | `F` |
|
||||
| number_integer | -9223372036854775808..-2147483649 | int64 | `L` |
|
||||
| number_integer | -2147483648..-32769 | int32 | `l` |
|
||||
| number_integer | -32768..-129 | int16 | `I` |
|
||||
| number_integer | -128..127 | int8 | `i` |
|
||||
| number_integer | 128..255 | uint8 | `U` |
|
||||
| number_integer | 256..32767 | int16 | `I` |
|
||||
| number_integer | 32768..65535 | uint16 | `u` |
|
||||
| number_integer | 65536..2147483647 | int32 | `l` |
|
||||
| number_integer | 2147483648..4294967295 | uint32 | `m` |
|
||||
| number_integer | 4294967296..9223372036854775807 | int64 | `L` |
|
||||
| number_integer | 9223372036854775808..18446744073709551615 | uint64 | `M` |
|
||||
| number_unsigned | 0..127 | int8 | `i` |
|
||||
| number_unsigned | 128..255 | uint8 | `U` |
|
||||
| number_unsigned | 256..32767 | int16 | `I` |
|
||||
| number_unsigned | 32768..65535 | uint16 | `u` |
|
||||
| number_unsigned | 65536..2147483647 | int32 | `l` |
|
||||
| number_unsigned | 2147483648..4294967295 | uint32 | `m` |
|
||||
| number_unsigned | 4294967296..9223372036854775807 | int64 | `L` |
|
||||
| number_unsigned | 9223372036854775808..18446744073709551615 | uint64 | `M` |
|
||||
| number_float | *any value* | float64 | `D` |
|
||||
| string | *with shortest length indicator* | string | `S` |
|
||||
| array | *see notes on optimized format/ND-array* | array | `[` |
|
||||
| object | *see notes on optimized format* | map | `{` |
|
||||
| binary | *see notes on binary values* | array | `[$B` (Draft 3 with `use_size` and `use_type`), `[U`, or `[B` otherwise |
|
||||
|
||||
Complete mapping
|
||||
|
||||
The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value.
|
||||
|
||||
Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`.
|
||||
|
||||
Size constraints
|
||||
|
||||
The following values can **not** be converted to a BJData value:
|
||||
|
||||
- strings with more than 18446744073709551615 bytes, i.e., 264-1 bytes (theoretical)
|
||||
|
||||
UTF-8 validation of string values and object keys
|
||||
|
||||
BJData strings must use UTF-8 encoding. By default (the [`error_handler`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) parameter left at `keep`), `to_bjdata()` writes the bytes of string values and object keys unchanged, even if they are not valid UTF-8. With `error_handler_t::strict`, it throws [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) for ill-formed UTF-8 instead; `replace`/`ignore` sanitize the string. [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) makes `strict` the default.
|
||||
|
||||
Unused BJData markers
|
||||
|
||||
The following markers are not written:
|
||||
|
||||
- `N`: no-op values are not created (they are skipped when reading).
|
||||
- `C`: single-character strings are serialized with `S` markers (`C` is read, and written for the elements of ND-arrays with `"_ArrayType_": "char"`).
|
||||
- `h`: floating-point numbers are written as `D`, not as float16 (`h` is read).
|
||||
- `B`: only written in Draft 3 mode.
|
||||
- `d` is only written for `single` ND-arrays or if `number_float_t` is `float`; `H` is only written for integers wider than 64 bits (custom `number_integer_t`/`number_unsigned_t`). An unsigned integer above 9223372036854775807 is written as `M`.
|
||||
|
||||
NaN/infinity handling
|
||||
|
||||
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the [`dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) function which serializes NaN or Infinity to `null`.
|
||||
|
||||
Endianness
|
||||
|
||||
A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on most modern computers where LE is used as the default byte order.
|
||||
|
||||
Optimized formats
|
||||
|
||||
Optimized formats for containers are supported via two parameters of [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md):
|
||||
|
||||
- Parameter `use_size` adds size information to the beginning of a container and removes the closing marker.
|
||||
- Parameter `use_type` further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be used together with `use_size = true`.
|
||||
|
||||
Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed of the number of elements in the container.
|
||||
|
||||
ND-array optimized format
|
||||
|
||||
BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types (referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to `[$U#[$i#i2 3 2 1 2 3 4 5 6` or `[$U#[i3 i2] 1 2 3 4 5 6`.
|
||||
|
||||
To maintain type and size information, ND-arrays are converted to JSON objects following the **annotated array format** (defined in the [JData specification (Draft 3)](https://github.com/NeuroJSON/jdata/blob/Draft-3/JData_specification.md#annotated-storage-of-n-d-arrays)), when parsed using [`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md). For example, the above 2-D `uint8` array can be parsed and accessed as
|
||||
|
||||
```
|
||||
{
|
||||
"_ArrayType_": "uint8",
|
||||
"_ArraySize_": [3,2],
|
||||
"_ArrayData_": [1,2,3,4,5,6]
|
||||
}
|
||||
```
|
||||
|
||||
ND-arrays with the element type `h` (float16) are returned with `"_ArrayType_": "half"`. `to_bjdata` does not pack `"half"` objects; they are written as regular objects, which read back as an equal value.
|
||||
|
||||
Likewise, when a JSON object in the above form is serialized using [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md), it is automatically converted into a compact BJData ND-array.
|
||||
|
||||
When parsing, an ND-array whose dimension vector is empty, contains a single integer, contains two integers with the first being 1, or contains a 0 is returned as a regular (possibly empty) array rather than an annotated object.
|
||||
|
||||
An object is only converted if the annotation describes a packed array that is parsed back into the same annotated object; otherwise it is serialized as a regular JSON object, so the annotation is never lost in a round trip. This requires all of the following:
|
||||
|
||||
- the object has exactly the three keys `"_ArrayType_"`, `"_ArraySize_"`, and `"_ArrayData_"` (any other key, e.g., `"_ArrayOrder_"`, makes it a regular object),
|
||||
- `"_ArrayType_"` is one of `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, `single`, `double`, `char`, or (only with `version = bjdata_version_t::draft3`, since the `B` marker is not part of Draft 2) `byte`; the names are case-sensitive,
|
||||
- `"_ArraySize_"` is an array, since the dimensions are written as the ND-array header's length,
|
||||
- `"_ArraySize_"` has at least two entries and is not a two-entry row vector (`[1,N]`), since other shapes are parsed back as a regular array (`[1,2,2]` is packed, `[1,4]` is not),
|
||||
- every entry of `"_ArraySize_"` is a positive integer, and their product is representable as a `std::size_t`,
|
||||
- `"_ArrayData_"` is an array holding exactly that many elements, and
|
||||
- every element of `"_ArrayData_"` is a number of the kind named by `"_ArrayType_"`: for the integer types, an integer (a floating-point number such as `1.0` does not qualify) that fits the named width (for `char`, 0..127); for `double`, a floating-point number (an integer such as `1` does not qualify); for `single`, a floating-point number that survives narrowing to `float` and back without change (for instance, `0.1` does not, since it is not exactly representable as `float`).
|
||||
|
||||
With `ordered_json`, an annotated object read from BJData has its keys in the order `"_ArrayType_"`, `"_ArraySize_"`, `"_ArrayData_"`; with `json`, they are sorted like those of any other object.
|
||||
|
||||
The current version of this library does not yet support automatic detection of and conversion from a nested JSON array input to a BJData ND-array.
|
||||
|
||||
Restrictions in optimized data types for arrays and objects
|
||||
|
||||
Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data types following the `$` marker in an optimized array and object container are restricted to **non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDC`, plus `B` since Draft 3 (the reader accepts `B` in both drafts). This also means other variable (`[{SH`) or zero-length types (`TFZN`) can not be used in an optimized array or object in BJData. The library enforces this restriction for both drafts. A `C` (char) element above 127 is rejected on read with [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113), in 1-D and in N-dimensional arrays. With `use_type`, the elements must have the same marker (`[1,200,3]` is not optimized, since it mixes `i` and `U`); booleans, null, strings, arrays, and objects are never optimized with `$`.
|
||||
|
||||
Binary values
|
||||
|
||||
BJData provides a dedicated `B` marker (defined in the [BJData specification (Draft 3)](https://github.com/NeuroJSON/bjdata/blob/Draft-3/Binary_JData_Specification.md#optimized-binary-array)) that is used in optimized arrays to designate binary data. This means that, unlike UBJSON, binary data can be both serialized and deserialized.
|
||||
|
||||
To preserve compatibility with BJData Draft 2, the Draft 3 optimized binary array must be explicitly enabled: pass `version = bjdata_version_t::draft3` together with `use_size = true` and `use_type = true` to [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md). With Draft 3 and only `use_size` (or neither), a binary value is written as an array of `B` elements.
|
||||
|
||||
In Draft 2 mode (default), if the JSON data contains the binary type, the value is stored as a list of integers, as suggested by the BJData documentation. In particular, this means that the serialization and the deserialization of JSON containing binary values into BJData and back will result in a different JSON object.
|
||||
|
||||
Example: serialize JSON values to BJData, with and without size/type optimization
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using nlohmann::json;
|
||||
using namespace nlohmann::literals;
|
||||
|
||||
// function to print BJData's diagnostic format
|
||||
void print_byte(uint8_t byte)
|
||||
{
|
||||
if (32 < byte and byte < 128)
|
||||
{
|
||||
std::cout << static_cast<char>(byte);
|
||||
}
|
||||
else
|
||||
{
|
||||
std::cout << static_cast<int>(byte);
|
||||
}
|
||||
}
|
||||
|
||||
int main()
|
||||
{
|
||||
// create a JSON value
|
||||
json j = R"({"compact": true, "schema": false})"_json;
|
||||
|
||||
// serialize it to BJData
|
||||
std::vector<std::uint8_t> v = json::to_bjdata(j);
|
||||
|
||||
// print the vector content
|
||||
for (auto& byte : v)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << '\n';
|
||||
|
||||
// create an array of numbers
|
||||
json array = {1, 2, 3, 4, 5, 6, 7, 8};
|
||||
|
||||
// serialize it to BJData using default representation
|
||||
std::vector<std::uint8_t> v_array = json::to_bjdata(array);
|
||||
// serialize it to BJData using size optimization
|
||||
std::vector<std::uint8_t> v_array_size = json::to_bjdata(array, true);
|
||||
// serialize it to BJData using type optimization
|
||||
std::vector<std::uint8_t> v_array_size_and_type = json::to_bjdata(array, true, true);
|
||||
|
||||
// print the vector contents
|
||||
for (auto& byte : v_array)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << '\n';
|
||||
|
||||
for (auto& byte : v_array_size)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << '\n';
|
||||
|
||||
for (auto& byte : v_array_size_and_type)
|
||||
{
|
||||
print_byte(byte);
|
||||
}
|
||||
std::cout << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
{i7compactTi6schemaF}
|
||||
[i1i2i3i4i5i6i7i8]
|
||||
[#i8i1i2i3i4i5i6i7i8
|
||||
[$i#i812345678
|
||||
```
|
||||
|
||||
## Deserialization
|
||||
|
||||
The library maps BJData types to JSON value types as follows:
|
||||
|
||||
| BJData type | JSON value type | marker |
|
||||
| ----------- | ---------------------------------------- | -------- |
|
||||
| no-op | *no value, next value is read* | `N` |
|
||||
| null | `null` | `Z` |
|
||||
| false | `false` | `F` |
|
||||
| true | `true` | `T` |
|
||||
| float16 | number_float | `h` |
|
||||
| float32 | number_float | `d` |
|
||||
| float64 | number_float | `D` |
|
||||
| uint8 | number_unsigned | `U` |
|
||||
| int8 | number_integer | `i` |
|
||||
| uint16 | number_unsigned | `u` |
|
||||
| int16 | number_integer | `I` |
|
||||
| uint32 | number_unsigned | `m` |
|
||||
| int32 | number_integer | `l` |
|
||||
| uint64 | number_unsigned | `M` |
|
||||
| int64 | number_integer | `L` |
|
||||
| byte | number_unsigned | `B` |
|
||||
| string | string | `S` |
|
||||
| char | string | `C` |
|
||||
| array | array (optimized values are supported) | `[` |
|
||||
| ND-array | object (in JData annotated array format) | `[$.#[.` |
|
||||
| object | object (optimized values are supported) | `{` |
|
||||
| binary | binary (strongly-typed byte array) | `[$B` |
|
||||
| BJData type | JSON value type | marker |
|
||||
| --------------------- | ------------------------------------------------ | -------- |
|
||||
| no-op | *no value, next value is read* | `N` |
|
||||
| null | `null` | `Z` |
|
||||
| false | `false` | `F` |
|
||||
| true | `true` | `T` |
|
||||
| float16 | number_float | `h` |
|
||||
| float32 | number_float | `d` |
|
||||
| float64 | number_float | `D` |
|
||||
| high-precision number | number_integer, number_unsigned, or number_float | `H` |
|
||||
| uint8 | number_unsigned | `U` |
|
||||
| int8 | number_integer | `i` |
|
||||
| uint16 | number_unsigned | `u` |
|
||||
| int16 | number_integer | `I` |
|
||||
| uint32 | number_unsigned | `m` |
|
||||
| int32 | number_integer | `l` |
|
||||
| uint64 | number_unsigned | `M` |
|
||||
| int64 | number_integer | `L` |
|
||||
| byte | number_unsigned | `B` |
|
||||
| string | string | `S` |
|
||||
| char | string | `C` |
|
||||
| array | array (optimized values are supported) | `[` |
|
||||
| ND-array | object (in JData annotated array format) | `[$.#[.` |
|
||||
| object | object (optimized values are supported) | `{` |
|
||||
| binary | binary (strongly-typed byte array) | `[$B` |
|
||||
|
||||
Complete mapping
|
||||
|
||||
The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
|
||||
The mapping is **complete** for the BJData types of Draft 2 and Draft 3 with one exception: column-major N-dimensional arrays are rejected with [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113). The Draft 4 constructs (structure-of-arrays containers and the extension type `E`) are not supported either.
|
||||
|
||||
The digits of an `H` value are parsed like a JSON number: integers that fit 64 bits become `number_integer` or `number_unsigned`, anything else a `number_float`; invalid text throws [`parse_error.115`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error115).
|
||||
|
||||
Duplicate object keys
|
||||
|
||||
If an object contains the same key more than once, `from_bjdata` accepts it and keeps the last value; with `ordered_json`, the key keeps the position of its first occurrence.
|
||||
|
||||
Ill-formed UTF-8 in string values and object keys
|
||||
|
||||
@@ -281,7 +307,7 @@ Example: deserialize a JSON value from BJData
|
||||
#include <iomanip>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
using nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -295,7 +321,7 @@ int main()
|
||||
json j = json::from_bjdata(v);
|
||||
|
||||
// print the deserialized JSON value
|
||||
std::cout << std::setw(2) << j << std::endl;
|
||||
std::cout << std::setw(2) << j << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user